Carbide.c++ UI Designer WP v1 0 En

F O R U M N O K I A

Carbide.c++ UI Designer White Paper

Version 1.0; November 1, 20062 006

Carbide.c++

Forum.Nokia.com

Copyright © 2006 Nokia Corporation. All rights reserved.

Nokia and Forum Nokia are registered trademarks of Nokia Corporation. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.

Disclaimer

The information in this document is provided “as is,” with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. Furthermore, information provided in this document is preliminary, and may be changed substantially prior to final release. This document is provided for informational purposes only.

Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to implementation of information presented in this document. Nokia Corporation does not warrant or represent that such use will not infringe such rights.

Nokia Corporation retains the right to make changes to this specification at any time, without notice.

License

A license is hereby granted to download and print a copy of this specification for personal use only. No other license to any other intellectual property rights is granted herein.

Carbide.c++ UI Designer White Paper 2

Forum.Nokia.com

Contents

1 Introduction....................................................................................................................................................................5 2 Building a GUI .................................................................................................................................................................6

2.1 The design of the S60 UI.........................................................................................................................................6 2.2 Getting started ..........................................................................................................................................................7 2.3 Using the UI Designer to create an interface ................................................................................................ 12

3 A closer look at UI design ......................................................................................................................................... 15 3.1 Standard components.......................................................................................................................................... 15 3.2 Nonlayout components ....................................................................................................................................... 16 3.3 Properties and events .......................................................................................................................................... 16

4 Working with multiple designs.............................................................................................................................. 18 4.1 Designing multiple views.................................................................................................................................... 18 4.2 Displaying multiple views................................................................................................................................... 18

5 Working with application code.............................................................................................................................. 20 5.1 The generated code.............................................................................................................................................. 20 5.2 Adding functionality ............................................................................................................................................. 20

6 Other UI Designer features....................................................................................................................................... 22 7 Summary....................................................................................................................................................................... 23 8 Evaluate this resource ............................................................................................................................................... 24


Forum.Nokia.com

Change History

November 1, 2006 Version 1.0 Initial document release


Forum.Nokia.com

1 Introduction

Symbian OS APIs provide a comprehensive and versatile way to construct graphical user interfaces for a variety of platforms. However, with that flexibility and versatility comes complexity. It can take time for a developer to master the vast number of classes and function calls, and getting an application UI exactly right can be an intricate task, given the many ways to program and manipulate the UI.

Consider, for example, the CEikEdwin class. This powerful interface object, used to provide plain text editors, is a subclass of five different parent classes. It has 10 enumerations and 147 public functions. It also has a subclass (CEikEdwinExtension) defined in its private section. To fully utilize the power of a CEikEdwin object can take study and understanding.

To assist the developer in working with the many facets of the S60 GUI APIs, Nokia has added the Carbide.c++ UI Designer to the Developer and Professional editions of the Carbide.c++ integrated development environment (IDE). The UI Designer provides developers with a visual interface to create and manipulate GUIs as well as some of the more complicated nonvisual objects of the S60 API.

This tutorial provides an overview of the features of the UI Designer. It describes how to get started with this design assistant and looks at some of the UI Designer’s key features, using a simple converter as an example.


Forum.Nokia.com

2 Building a GUI

This chapter introduces the basic features of the UI Designer — how to create a project and build an interface. The example of a simple unit converter is used to illustrate the use of the UI Designer and provide a basis for exploring its features.

The UI Designer is a set of plug-ins for the Carbide.c++ IDE. Carbide.c++ is based on the Eclipse IDE, which is an open source project focused on providing an extensible development platform and application frameworks for building software. With Eclipse as its base, Carbide.c++ is built by adding a set of plug-ins designed to support Symbian OS development. A built-in updater helps keep the various plug-ins in Carbide.c++ current.

The UI Designer is implemented as a set of plug-ins for the Carbide.c++ tool. With proper configuration, Carbide.c++ can ensure that the UI Designer plug-in is kept current.

2.1 The design of the S60 UI

The S60 UI follows a set of standard style guidelines, regardless of the screen resolution and orientation on which it is displayed. Figure 1 shows two implementation examples, one from the S60 emulator and one from a production Nokia E61 phone. As shown in Figure 1, the S60 UI consists of three main areas:

♦ Status pane: The status pane contains objects such as the application title and icon, and any device status indicators.

♦ Main pane: The main pane is a CCoeControl container, holding interface objects that make up the user interface for the application.

♦ Control pane: The control pane implements menus for the softkeys on an S60 device.

Figure 1: The S60 UI maintains a common structure on different displays.

Each of these areas is integrated into the UI Designer, resulting in a hierarchical design model. The top of the hierarchy is a screen — an interface object that contains all three standard interface areas. Each view comprises a status pane, a control pane, several interface containers, and possibly some nonvisual objects. The interface containers, in turn, hold the interface objects: the buttons, labels, and text fields that make up an application UI. There may be multiple views in an application.

This hierarchy is reflected in the way the UI Designer guides developers to build an S60 interface. An example of this will be shown in the next section.


Forum.Nokia.com

2.2 Getting started

A new Carbide.c++ project is created by selecting File > New (or the New icon on the toolbar). Either a new menu (such as the one shown in Figure 2) or a dialog box (as shown in Figure 3) is then displayed, offering several ways to start a project. To start a Carbide.c++ UI Designer project, choose C++ Application for S60 Project from the menu or dialog box. It should be noted that applications for other Symbian OS platforms can also be created with Carbide.c++. The UI Designer, however, is currently available for S60 applications only, although support for UIQ is expected and more information will be found at www.forum.nokia.com/carbide when it becomes available.

Figure 2: A new Carbide.c++ project can be started from the File > New menu.

Figure 3: Using the New tool button displays the available project wizards.


http://www.forum.nokia.com/carbide

Forum.Nokia.com

Once the project type has been chosen, the New C++ Application for S60 Project Wizard, as shown in Figure 4, is displayed. This asks for the project name and the location at which the project files should be stored.

Figure 4: The New C++ Application for S60 Project Wizard first asks for a project name and storage location.

The project template is selected in the next dialog box, shown in Figure 5. To use the UI Designer, any of the projects including “with UI Designer” in the title can be selected. For this example, “S60 3rd Ed. GUI Application with UI Designer” is chosen.

Figure 5: A new Carbide.c++ UI Designer project is chosen from a template that includes “with UI Designer” in its title.


Forum.Nokia.com

Pressing the Next button brings up the dialog box shown in Figure 6, which allows the SDK and build targets to be chosen. The example is for an S60 3rd Edition application, so the default options are accepted.

Figure 6: The SDK and build options are chosen for the selected template.

The next dialog, shown in Figure 7, allows the application’s baseline SDK and initial language to be chosen. For the Conversion example, S60 3rd Edition is chosen as the SDK and American English as the language.

Figure 7: The baseline SDK and initial application language are selected.

The next dialog, shown in Figure 8, asks for a design to be selected. Currently, the UI Designer offers three commonly used application layouts:

♦ A form — providing a way for users to quickly edit data in a single display.

♦ A list box — providing a tablelike view of data. The screen is made up of rows and takes up the whole screen. The display can have a heading column with words, numbers, or icons. The line height is variable.


Forum.Nokia.com

♦ A setting item list — providing user-configurable settings. Each setting item, when selected, is edited in a full-screen editor.

In addition to these designs, an empty interface can be used to create a UI design from scratch. This style is used for the Conversion example.

Figure 8: The Carbide.c++ UI Designer provides a number of templates for UI designs.

The next dialog, shown in Figure 9, asks about the type of container desired for the application being designed. Although the questions are technical, the choices for answers are few. The default values are usually adequate, and for the Conversion example, the base container is set to the CCoeControl class.

Figure 9: Information is provided on the container name and type.


Forum.Nokia.com

The next two dialog boxes ask basic configuration questions, such as the UID for the application, the text for the copyright notice, and the names of the directories that will hold the application’s files. Once these have been completed and the Finish button pressed, the initial source is generated for the Conversion project. The UI Design Editor is then displayed, as shown in Figure 10.

Figure 10: Once the S60 3rd Ed. GUI Application with UI Designer Wizard is finished, the UI Design Editor is opened.


Forum.Nokia.com

2.3 Using the UI Designer to create an interface

The UI Design Editor displays a design constructed of the three standard S60 interface areas, as discussed in Section 2.1, “The design of the S60 UI.” These objects are listed in the Outline view to the right of the UI Design Editor, as shown in Figure 11. A default name, displayed in the status pane at the top of the S60 UI, is provided for the application and for the menu items, shown in the control pane at the bottom of the S60 UI. Since Conversion is starting with an “empty” design, the basic container is empty.

Figure 11: The three S60 interface areas are shown in the Outline view.

The first step in designing the Conversion application’s UI is to amend the status pane to reflect the title of the application. This is done by selecting the title in the status bar and editing it in place, as shown in Figure 12.

Figure 12: The title can be amended directly in the status pane.


Forum.Nokia.com

The next step is to add the interface objects listed in Table 1.

Interface Object UI Designer Component

UI Designer Category

API Class

Field labels Label Controls CEikLabel

Currency/Temperature Specification

Text Editor Editors CEikEdwin

Currency Amount / Temperature Measure

Fixed Point Editor Editors CEikFixedPointEditor

Time Specification Time Editor Editors CEikTimeEditor

Table 1: Four interface objects are needed to create the Conversion application’s UI.

Each of the interface objects is created by selecting the appropriate entry in the Palette, placing it on the Design canvas, sizing it, and adjusting the properties in the Properties view.

To add the Time Specification field, the Time Editor is selected from the Editors list in the Palette, as shown in Figure 13, and then it is positioned in the Design canvas.

Figure 13: Selecting the Time Editor from the Palette allows the Time Specification to be added to the design.


Forum.Nokia.com

Once the Time Editor is added to the design, its properties can be adjusted in the Properties view, as shown in Figure 14. Although a unique name of the interface object is generated by Carbide.c++, it is not very informative. The default names are shown on the right in the Outline view. These names should be changed as objects are added to the design, since this will make the generated code easier to work with.

Figure 14: The Carbide.c++ UI Designer allows fine-tuning of the UI through an object’s properties.

As objects are added to the design, their associated code is created by the UI Designer. This code is segmented into the generated code, which is demarcated with comments and the areas where application-specific logic can be added.

The code generated by the UI Designer contains the basic UI navigation. For example, the application will react in standard ways to some events, such as moving between fields with arrow keys. Application-specific actions, such as the conversions themselves, will require custom code to be written.

Working with code is discussed further in Chapter 5, “Working with application code.” Before this, however, the next two chapters will examine the design components in more detail.


Forum.Nokia.com

3 A closer look at UI design

The Carbide.c++ UI Designer offers flexibility in specifying a UI. It allows standard components to be manipulated and can be extended to include user-defined custom components. The properties of all types of components are easily specified through the UI Designer.

This chapter provides an overview of the components in a UI that can be designed with the UI Designer.

3.1 Standard components

As defined by the UI Designer, standard components fall into six separate categories:

♦ Control components include images and label specifications.

♦ Editor components include editors specifically built to manipulate certain types of data. These components include integer and floating-point editors, several types of text editors, date and time/date editors, a duration editor, a range editor, time and time offset editors, two types of “secret” information editors, and IP address editors. They are shown in the snapshot of the Palette in Figure 15.

♦ Menu components include the menu pane, the menu bar, and menu items.

♦ Miscellaneous components currently offer a Web client implementing HTTP protocol transactions between an application and a Web server. This component can use a Wait Dialog object to provide feedback during a protocol transaction. It uses a dialog box to prompt for a user name and a password for servers requiring authentication.

♦ Notes and dialog components include notes — global and standard notes — and several different types of dialogs, each corresponding to a dialog box supported by the S60 API.

♦ Status and control components make up the remainder of the built-in components. These include icons and text in the status pane.

These visual components are designed to be created in the main container of a view. Creation of the interface using these components is straightforward and follows the process outlined in Section 2.3, “Using the UI Designer to create an interface.”

Figure 15: The UI Designer supports a comprehensive list of editors.


Forum.Nokia.com

3.2 Nonlayout components

Nonlayout components are those that are not always visible when a screen is displayed or have no UI, such as the Web Client component. For example, menus or dialog boxes are interface objects but have no specific place on visible view. Each is made visible under certain circumstances.

Nonlayout components are made available through the nonlayout display in the UI editor. This display is below the canvas in the UI editor. In Figure 16, an options menu is shown in the nonlayout display. By selecting an item in the nonlayout display, its properties can be adjusted in the Properties view.

To illustrate the use of nonlayout components, consider a dialog box that allows switching between countries. This requires a “List Single Query Dialog” component, which can be selected and dragged to the nonlayout display. The canvas then displays the selected dialog box, and its properties appear in the Properties view, as shown in Figure 16. Notice that the dialog has been added to the Outline. The dialog allows the user to make choices from a list box; items in the list box are specified by dragging the List Box Item component from Controls in the Palette into the dialog box. The properties of each resulting object can then be adjusted in the Properties view.

Figure 16: The Carbide.c++ UI Designer allows for the insertion of nonvisible items.

3.3 Properties and events

The UI Designer allows adjustments to be made to all aspects of an object’s behavior. The UI Designer makes fine-tuning of even obscure aspects of a component straightforward. The ability to adjust the properties of objects and events is a particular benefit of the UI Designer. In addition, in Symbian C++, the behavior of an object may be controlled by C++ code or resource file settings, or both. Learning exactly where an object’s behavior is controlled can be a lengthy process. The UI Designer greatly simplifies this aspect of UI design by correctly creating the code or resource settings as required.


Forum.Nokia.com

Using the Properties window to configure the interface is an effective way to create a design. Often, programmers need the tools of an IDE such as Carbide.c++ to look up all the calls in the API for an object, to find the arguments to those calls, and to look up all the alternatives to those arguments. With the properties of an object displayed and ready for adjustment, it is easy to change and fine-tune the object. Consider the properties displayed in Figure 17 for the CEikEdwin object that will display the converted temperature. Using the Properties view, the size and position can be set easily, as can the text, font, and color of the object.

Figure 17: An object’s properties are set easily using the Properties view.

The UI Design Editor includes several features for adjusting the layout of objects within the design. When coding manually, aligning several objects is a tedious task, involving choosing and specifying specific x and y coordinates for each object. Using the UI Design Editor, the developer simply selects all the items to be aligned with the Marquee, then chooses one of the alignment options from Carbide.c++’s toolbar.

All events associated with an object are accessible through the UI Designer interface. The events specification window allows the developer to assign a specific function to be called when an event occurs. When specified, these functions are written into the generated code as a template to be filled in later.


Forum.Nokia.com

4 Working with multiple designs

An application for an S60 device often consists of more than one view. In other words, applications often use more than one set of interface objects. The UI Designer helps create and use multiple views in an application.

4.1 Designing multiple views

When Carbide.c++ creates a project, it starts by assuming there is a single view to an application’s interface. This view is displayed when an application is created, and code is generated to show the view when the application is run. New views are created and added to the project by selecting File > New > Other or by clicking the New icon button and then selecting the S60 UI Design Wizard from the dialog box. The dialog window, shown in Figure 18, is then displayed.

By selecting an existing project, the wizard assumes that a new view is required. From this point, the wizard follows the sequence of dialogs first seen in Figure 8. Once the new view’s characteristics have been defined to the wizard, a new view is constructed, with a new set of interface areas: status, main, and control panes.

Figure 18: Adding a new view will display the New S60 UI Design Wizard.

Each new view adds new files to the project. A view file is added that controls the settings of the items in the view and fields interface events for the entire view. A container file is also added that controls the container and the interface objects created within that container.

4.2 Displaying multiple views

Once a new view has been designed, it will need to be displayed; the design of the S60 API makes this a simple process.


Forum.Nokia.com

Multiple views are usually handled through the application’s instance of the CAknViewAppUi class. This instance is generated by the UI Designer, and it contains, in the Conversion example, two function definitions, as shown in Example 1.

void CConversionAppUi::InitializeContainersL() { iConversionContainerView = CConversionContainerView::NewL(); AddViewL( iConversionContainerView ); SetDefaultViewL( *iConversionContainerView ); iConversionContainer2View = CConversionContainer2View::NewL(); AddViewL( iConversionContainer2View ); } void CConversionAppUi::ConstructL() { BaseConstructL( EAknEnableSkin ); InitializeContainersL(); }

Example 1: The UI Designer creates an instance of CAknViewAppUi to handle multiple views.

Notice that each view is constructed by calling the NewL() function and added to the interface. Then one view, the view that is to be displayed when the application is started, is set as the default view. This use of the AVKon view API means that switching views is simply a matter of calling the ActivateLocalViewL() function. The definition of the Id() function is built into the code generated by the UI Designer for each view.

In addition, the UI Designer includes the ability to set which design is the default view, as shown in Figure 19.

Figure 19: The initial application view can be set from the UI Designs tab of the application.uidesign.


Forum.Nokia.com

5 Working with application code

The purpose of the UI Designer is to generate code, in C++ and other forms, for the objects designed. However, this code will need to be extended to add the logic that creates the final application. Understanding how the code is generated and how it may be extended is therefore crucial to making the most of the UI Designer.

5.1 The generated code

The UI Designer generates code dynamically as objects are specified and designed. For example, setting the horizontal alignment property for a CEikLabel object to left will add a line to the application’s resource file (after the design has been saved) that sets the horiz_align property to EEikLabelAlignHLeft for that object. This dynamic property of the UI Designer is important, because the generated code is designed to be correct at any time during object design. At any point, the application under development can be built and run (assuming the code supplied by the developer also works).

Code is generated in the standard S60 software design framework: a UI that contains a view, which contains the standard objects, including the interface object container. The UI manages multiple views and fields commands from menu selections and button presses. The interface view, as discussed previously, manages object containers. Each container holds interface objects and manages interface events from those objects.

The generated code performs a number of functions:

♦ Creation of the interface — Each view’s container is populated with code to create the interface objects controlled with that view. This involves both resource and C++ files. This code is placed in a function called by the container’s ConstructL(), which is used to initialize the interface.

♦ Definition of required class functions — Each function that has a required definition, especially in derived classes, is defined for the programmer automatically. Even if the definition is empty, the definition is placed in the appropriate file.

♦ Hooks for working with the interface — Each view’s code contains functions whose purpose is to manipulate the interface when they are called. However, in the initial code, many of these functions are not called, but wait for the introduction of user-defined code that calls them. For example, code to display dialog boxes is placed in the container for code for a view, but calling the code is the responsibility of the programmer.

♦ Responses to interface events — The framework for responding to interface events, such as the press of a button or the choice of a menu item, is generated in the code. This framework is not filled in; that job is the responsibility of the programmer.

♦ Destroying the interface — Shutting down the interface and destroying the instances of classes that manipulate it are built into each view’s code.

In addition to code, there are comments scattered throughout the definitions generated by the UI Designer. These comments document what the UI Designer will control or change and when the various parts were generated.

5.2 Adding functionality

Most of the time, S60 applications are event-driven. This means that code is invoked in response to something external that is detected by the interface, such as the expiration of a timer or the pressing of a number on the keyboard. As mentioned previously, the UI Designer generates the framework for fielding events. In many cases, generic code for responding to events is part of the generated code. It is the developer’s responsibility to add the code to handle events.

In many instances, even this can be handled through the UI Designer. Event-handling code can be added to the generated code. The Events view is usually found in the information area at the bottom of the Carbide.c++ display (as shown in Figure 20); if not, it can be by selecting Window > Show View > Other, opening the Carbide.c++ views, and


Forum.Nokia.com

selecting Events. The Events view lists all events that might be generated for an interaction object. Here, handlers can be added by right-clicking next to the event entry and selecting a handler for that event. The UI Designer will insert code for the event handler and can display the code editor so that handler code can be added.

Figure 20: The Events view allows code to handle events to be added to a project.

Where the programmer needs to add functionality in the conventional way — to handle responses to keystrokes, button presses, and menu selections, for example — the UI Designer provides empty definitions to the proper functions. Examples of these include HandleCommandL(), OfferKeyEventL(), and HandleControlEventL().

In most cases, the UI Designer inserts template-style code with plenty of comments that direct the developer to the location where custom code can be added. For example, to customize the code for pressing the left softkey — the Country menu key — in the Conversion example, select the Function property on the Control pane event view. The UI Designer will then insert a function name and display the code in the editor view. The code to handle the country functionality would then be added at the TODO comment in the generated code, as shown in Example 2.

/** * Handle the leftSoftKeyPressed event. * @return ETrue if the command was handled, EFalse if not */ TBool CConversionContainerView:: HandleControlPaneLeftSoftKeyPressedL( TInt aCommand ) { // TODO: implement leftSoftKeyPressed event handler return EFalse; }

Example 2: Generated code for softkey handling shows where application code should be added.

Notice how relatively long names are used to make each name unique. “TODO:” is added whenever an event handler needs to be customized.

The one area of code that developers should not alter is the code generated by the UI Designer. Any changes to this code will be lost if the UI Designer needs to regenerate the code. The UI Designer clearly flags this code with the following comments:

// [[[ begin generated region: do not modify [Generated Contents]

// ]]] end generated region [Generated Contents]


Forum.Nokia.com

6 Other UI Designer features

The UI Designer is a rich, functional tool and has many previously discussed features that the developer will want to explore. Some other features worth noting are:

♦ Screen resolutions — The UI Designer can represent many of the screen resolutions found in S60 devices. A toolbar option (shown in Figure 21) allows the developer to move between these resolutions.

Figure 21: The UI Designer can display interfaces in several different screen resolutions.

♦ Tab groups — Views can be added to a tab group; this is a group of views that are visually flagged as tabs displayed at the top of the S60 screen. The user switches between these tabs using cursor keys. Any view can be added to a tab group by enabling tab navigation and specifying tab designs. This is done through the “application.uidesign” by selecting the UI Designs tab. When the boxes that enable tabbing are checked, code will automatically be generated to display the tab group and allow movement between tabs. Figure 22 shows an example.

Figure 22: The UI Designs tab of the “application.uidesign” allows tab navigation to be used.

♦ Working with pre-existing projects — Carbide.c++ allows pre-existing projects to be imported and will convert the bld.inf or *.mmp file that holds the project information into the internal structures it needs to allow development. However, pre-existing interface designs cannot be imported into the UI Designer. It is simply not possible to funnel all possible coding styles into the specific structures the UI Designer needs to support a visual design.


Forum.Nokia.com

7 Summary

This tutorial has provided an introduction to the UI Designer plug-in found in the Developer and Professional editions of Carbide.c++. With the use of a simple unit conversion application as an example, many features of the UI Designer have been described. How to start a new S60 application with the UI Designer and how to manage the elements of that design were examined. Working with multiple views and dialog boxes was also discussed, as were the methods for working with the code generated by the UI Designer. Finally, several topics that warrant further exploration were described briefly.

The UI Designer is a powerful tool that simplifies the development of UIs for S60 applications, with support for UIQ expected in the future. It has the ability to speed development and to assist the developer in creating and managing complicated interfaces and the code structures that manipulate them. Because the benefits of improved application development efficiency are significant, developers will find mastering this new feature of Carbide.c++ worthwhile.


Forum.Nokia.com

8 Evaluate this resource

Please spare a moment to help us improve documentation quality and recognize the resources you find most valuable, by rating this resource.


http://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId=1102065e-764e-461d-843d-c432d975df5c/Carbide.cpp_UI_Designer_WP_v1_0_en.pdf

Carbide.c++ UI Designer WP v1 0 En

Documents

Transcript of Carbide.c++ UI Designer WP v1 0 En