Development environment and quick start

From UIQ Books

Development environment and quick start

Introduction

This chapter provides a fast track guide to UIQ 3 development. It describes the development tools and workflow. It highlights the main UIQ architectural concepts that are described in much more detail in later chapters.

We describe how to use both the command line and the Carbide.c++ Integrated Development Environment (IDE). Carbide.c++ is used because a free version is available, and because it is positioned as the primary IDE.

An IDE helps you author and debug code. It uses tools provided by the UIQ SDK and the underlying Symbian OS to compile, link and package up applications. If you install just the UIQ SDK, without an IDE, you get a command line based development environment which you can use if you prefer. The Carbide.c++ IDE provides a Windows based environment that uses the command based tools.

In many development environments, you can work entirely within the IDE for most applications. For non-trivial UIQ 3 applications, however, you will also need to work outside the IDE. The command line provides a richer set of available operations, for example, to gain greater control over packaging up components into an installable SIS file. Hence, you will sometimes find yourself using the command line. Also, as you become more proficient in Symbian OS development, you will probably find it more convenient to use the command line and just use the IDE for editing files and debugging. Due to the variety of available IDEs, specifically Carbide.c++, Carbide.vs and CodeWarrior, the command line also tends to be used in examples and third party documentation.

Development Environment

The development environment is rich mix of UIQ SDK, Symbian tools, IDE, optional manufacturer specific extensions and third party tools. Developers also have a choice of several IDEs, where each has peculiarities and limitations. Running all the tools within a particular existing PC environment can also add complexity and cause failures after initial installation. In fact, simple post-installation configuration can solve most problems. Once set up, the development environment is easy to use.

UIQ SDK

The UIQ SDK is a collection of UIQ, Symbian and third party tools. The SDK is a collection of tools controlled using Perl scripts. For this reason, Activeperl is installed as part of the UIQ SDK. The SDK enables applications to be built from the command line (via Start -> All Programs -> Accessories -> Command Prompt). In simple terms, a Windows based IDE such as Carbide.c++ submits the command line based commands and redirects/filters output to a window.

The UIQ SDK is obtained from developer.uiq.com. You will need to register – for free – before you can download the SDK.

Your choice of SDK is a trade-off between having newer features and bug fixes versus compatibility with older phones. Applications written with, the UIQ 3.0 SDK will run on phones based on UIQ 3.0 or UIQ 3.1 or any future version of UIQ 3. Writing with the UIQ 3.1 SDK, the opposite isn’t true as your code is likely to call system libraries that don’t exist on UIQ 3.0 phones. Keeping compatibility in mind, pick the newest SDK you can for the phones that you want to support, so as to gain the benefit of bug fixes and improvements to the documentation and examples.

Pro tip:

In order to avoid problems, install the SDK and all additional tools to the same root drive. Also, avoid using directories other than those provided by default in the setup. Should you change directories, ensure the install path doesn’t include spaces.

When you run the extracted setup you will be asked which components you wish to install:

Figure 1 UIQ 3 SDK setup window

Enable installation of all the components with the exception of ‘Java Developer’, unless you plan to also develop for Java ME.

WinPcap is a utility that allows you to connect the emulator to the Internet. The GCCE compiler is the one used to compile for the mobile phone while the x86 vs2003 option installs a Nokia Windows compiler for use when compiling for the emulator.

Part way through the installation you may be asked if you want to set the SDK as the default. The Symbian development environment allows you to switch between various installed S60 and UIQ SDKs. If you confirm selection of the UIQ SDK as the default, this will be done automatically for you.

If you encounter problems using the SDK, there are many useful FAQs on developer.uiq.com and developer.symbian.com.

Pro tip:

The default GCCE settings enable no compiler optimization. This leads to binaries that are slower and much larger than they need to be. It’s possible to change the default level of optimisation used by GCCE

Edit the file epoc32\tools\compilation_config\GCCE.mk and change the line:

REL_OPTIMISATION=

to:

REL_OPTIMISATION= -O2 -fno-unit-at-a-time

If you later run into problems running code on the phone, you should undo this change to determine if it has been caused by optimization of the code.

Selecting the UIQ SDK

If you already have an S60 SDK installed, the UIQ installation asks you if you want the UIQ SDK set as the default. The reason for this is because the Symbian development environment allows you to switch between various installed S60 and UIQ SDKs.

You can check or switch between SDKs using the command line devices command or using the windows based UIQ SDK configurator.

To list installed SDKs:

C:\>devices
UIQ3:com.symbian.UIQ – default
S60_3rd:com.nokia.s60

To change the default SDK to the UIQ 3 SDK:

C:\>devices -setdefault @UIQ3:com.symbian.UIQ

To use the SDK configurator, select Start ->All Programs -> UIQ 3 SDK -> SDKConfig. The Devices tab allows you to switch between the SDKs installed on your PC:

Figure 2 SDK configurator

If you use Carbide.c++ then the IDE automatically takes care of switching between SDKs.

Carbide.c++ IDE

Carbide.c++ is the newest family of Eclipse-based development environments for Symbian OS C++ application development. It’s developed and sold by Nokia and is suitable for both UIQ and S60 development.

There are four versions. The free Express edition is suitable for most people doing UIQ development. The Developer edition includes a RAD style UI builder and on-target (phone) debug support both of which are not supported under UIQ as of the time of writing of this book; however, these are anticipated to become available in the future. The Professional version is targeted towards advanced developers who need crash debug and performance investigation tools. The OEM version available during 2007 supports advanced hardware debugging for mobile phone manufacturers.

Carbide.c++ is obtained from forum.nokia.com

You have to register with Forum Nokia before downloading. As with all Symbian related tools, install to the same root drive as the proposed workspace and UIQ SDK.

Pro tip:

When you start Carbide.c++ you will be prompted for a workspace. Specify a path that doesn’t contain spaces otherwise you will have problems importing files and finding headers. Also ensure you use a capitalized drive letter.

Alternative Development IDEs

CodeWarrior 3.0 and 3.1

CodeWarrior for Symbian OS, also owned by Nokia, is being phased out in favor of Carbide.c++ tools. Therefore, we don’t mention it further in this book.

Pro tip:

Should you choose Codewarrior, be sure to obtain version 3.1. Version 3.0 doesn’t allow compilation for GCCE.

Carbide.vs / Visual Studio .NET 2003

Carbide.vs (available from forum.nokia.com) and the associated UIQ support package (from developer.uiq.com) are free plug-ins for Visual Studio.NET 2003 that allow developing for UIQ in Visual Studio. While developing under Visual Studio’s ‘look and feel’ might seem attractive, Symbian, UIQ and Nokia are promoting Carbide.c++ as the preferred development IDE. Hence, Visual Studio based development isn’t mentioned further in this book.

Pro tip:

Using Carbide.vs requires a licensed version of Visual Studio.NET 2003. It won’t work with Visual Studio.NET 2005.

The `QuickStart` Example

The QuickStart example demonstrates features within every UIQ application. For simplicity, all the project files have been placed in the same directory and all of the c++ code in one CPP file. This is unusual and the normal directory and file structure is discussed in the Chapter Building an application.

The QuickStart application itself displays a simple list view and processes commands to display an about dialog. It is a simplified version of the Commands1 application, which you can find in the Chapter Commands and categories.

Application Fundamentals

Application Architecture

UIQ provides an application framework that relieves you of much of the effort in creating a graphical user interface. The application framework will:

create a connection to the file server
create a connection to the window server
create a connection to the memory manager
do some registration work
make sure that we can handle error and out-of-memory situations
initialize other application services (such as font providers)
create the default screen furniture (for example, the status bar, menu bar, softkeys)
start the active scheduler (the event loop).

Most applications consist of at least the following four base classes:

application (CQikApplication)
document (CQikDocument)
application UI, often abbreviated to AppUi (CQikAppUi)
at least one View (CQikViewBase).

Here’s a diagrammatic representation of what happens during application invocation:

Figure 3 Representation of application invocation

The QuickStart example follows a standard format of the application entry point (E32Main) creating a new CQikApplication derived object CAppSpecificApplication which creates a new CQikDocument derived object CAppSpecificDocument.

The main responsibility of the application class is to create a document. It is a common software engineering practice to separate the user interface from the engine. The document is basically the engine while the application UI and the view form the user interface.

CApaDocument* CAppSpecificApplication::CreateDocumentL(void)
  {
  return(CAppSpecificDocument::NewL(*this));
  }
 
LOCAL_C CApaApplication* NewApplication(void)
  {
  return(new CAppSpecificApplication);
  }
 
GLDEF_C TInt E32Main()
  {
  return(EikStart::RunApplication(NewApplication));
  }

The document object is usually responsible for saving and loading objects, for example to and from files, that persist beyond the application lifetime.

Creating the document implicitly causes the CEikAppUi::CreateAppUiL function to be called which creates the CAppSpecificUi that, in turn, creates the view:

void CAppSpecificUi::ConstructL(void)
 
// Normal primary entry point to a Symbian App.
  {
  CQikAppUi::ConstructL();
  CAppSpecificListView* q=new(ELeave)CAppSpecificListView(*this);
  …
  }

The view is constructed using the pre-defined resource (ID):

void CAppSpecificListView::ViewConstructL()
  {
  ViewConstructFromResourceL(R_LIST_VIEW_CONFIGURATIONS);
  …
  }

Project Files

The component description file is always called bld.inf. This file defines the targets (e.g., whether the code is built for the Windows emulator, and what hardware platforms are supported) and lists the file used to define the project. In the example, we wish to build for the emulator (WINSCW) and the phone (using the GCCE compiler) targets:

PRJ_PLATFORMS
WINSCW GCCE
 
PRJ_MMPFILES
QuickStart.mmp

We have one project definition file called QuickStart.mmp.

The MMP file defines the application attributes such as the executable filename, Platform Security capabilities, compiler/linker options and the files to compile and link. The MMP syntax is covered further in the Chapter Building application. Platform Security is discussed in the Chapter Symbian OS essentials and Symbian Signed is covered in the Chapter Symbian Signed.

Unique Application ID (UID 3)

As mentioned in the Chapter Symbian OS essentials every application has a unique ID. The QuickStart example is typical of most applications in that the UID (0xE00000AD) can be found in:

the project definition file (MMP file)
in the QuickStart_reg.rss file
in the QuickStart.pkg file
the code, QuickStart.cpp in this example.

If you change the UID, be sure to change all these files.

Resources, Icons and Controls

Elements of the UIQ user interface, for example, menu panes, views and list boxes are called resources. They are defined in a Symbian-OS specific editable text file that’s later compiled into a compressed binary application resource file. Separating resource files from code allows different localized versions of the application to be built without changing the code. Resource files are much more significant in UIQ 3 compared to UIQ 2 or S60.

It’s also possible to build some resources dynamically in code rather than statically at compile time so as to create dynamic screens and menus based on program data. However, this is beyond the scope of this QuickStart example.

The following screens show how an application, in this case the built-in Web application, automatically adapts from being portrait display with softkey input to landscape with pen input when the user requests to switch from portrait to landscape:


Web application in Softkey Style Portrait configuration. Note the soft menu options at the bottom of the screen	Web application in Pen Style Landscape configuration. Note the drop down menu to the right of the application name

Figure 4 Web application

In the QuickStart example, firstly the screen layout is defined in the QuickStart.rss file. It defines the same view for each supported UI configuration:

RESOURCE QIK_VIEW_CONFIGURATIONS r_list_view_configurations
       {
       configurations =
              {
              QIK_VIEW_CONFIGURATION
                     {
                     ui_config_mode = KQikPenStyleTouchPortrait;
                     command_list = r_quickstart_commands;
                     view = r_quickstart_view;
                     },
              QIK_VIEW_CONFIGURATION
                     {
                     ui_config_mode = KQikPenStyleTouchLandscape;
                     command_list = r_quickstart_commands;
                     view = r_quickstart_view;
                     },
              QIK_VIEW_CONFIGURATION
                     {
                     ui_config_mode = KQikSoftkeyStylePortrait;
                     command_list = r_quickstart_commands;
                     view = r_quickstart_view;
                     },
              QIK_VIEW_CONFIGURATION
                     {
                     ui_config_mode = KQikSoftkeyStyleSmallPortrait;
                     command_list = r_quickstart_commands;
                     view = r_quickstart_view;
                     },
              QIK_VIEW_CONFIGURATION
                     {
                     ui_config_mode = KQikSoftkeyStyleSmallLandscape;
                     command_list = r_quickstart_commands;
                     view = r_quickstart_view;
                     },
              QIK_VIEW_CONFIGURATION
                     {
                     ui_config_mode = KQikSoftkeyStyleTouchPortrait;
                     command_list = r_quickstart_commands;
                     view = r_quickstart_view;
                     }
              };
       }

At the time of writing, if your application supports the six view configurations shown in the resource text above, you will support all the commercially available UIQ 3 phones.

If you examine the QuickStart.rss file you can see that the view (QIK_VIEW) is defined in terms of a page (QIK_VIEW_PAGE) that contains a container (QIK_CONTAINER_SETTINGS) that contains a container item (QIK_CONTAINER_ITEM_CI_LI) that contains a (QIK_LISTBOX).

QuickStart.rss also defines the about dialog (DIALOG) containing labels (EEikCtLabel).

The exact structure of the RSS file and specifically list controls is discussed in detail in the Chapter List boxes.

Commands

The QuickStart.rss file also defines the menu:

  QIK_COMMAND
    {
    id = EAppCmdAbout;
    type = EQikCommandTypeScreen;
    groupId = EAppCmdMiscGroup;
    priority = EAppCmdAboutPriority;
    text = "About";
    },

The “About” string literal is usually placed within a separate RLS localization file but is hardcoded in this example for simplicity.

The exact syntax of commands is covered in the Chapter Commands and categories. For now, it sufficient to know that the resultant ID (EAppCmdAbout) ends up being sent to the command handler:

void CAppSpecificListView::HandleCommandL(CQikCommand& aCommand)
 
//  Handle the commands coming in from the controls that can deliver cmds.
  {
  switch (aCommand.Id())
    {
    case EAppCmdAbout:
    (new(ELeave)CAboutDialog)->ExecuteLD(R_ABOUT_DIALOG);
    break;
    …
}
  }

The about command causes the dialog defined in the RSS file (R_ABOUT_DIALOG) to be invoked.

Building from the Command Line

Start a command prompt window and go to the QuickStart example:

C:\>cd \symbian\quickstartexample

Type:

C:\Symbian\QuickStartExample>bldmake bldfiles

Pro tip:

You may get the warning ‘Cannot determine the version of the RVCT Compiler.’ You can ignore this warning. The tools are looking for an ARM compiler which you don’t have and it doesn’t matter as you are using GCCE. Alternatively, you can remove this error by ensuring that your bld.inf file contains only winscw gcce under PRJ_PLATFORMS.

This creates an abld.bat file in the current directory that is used for building. To build a debug version for emulation, type:

C:\Symbian\QuickStartExample>abld build winscw udeb

The executable called QuickStart.exe is created in C:\Symbian\UIQ3SDK\epoc32\release\winscw\udeb

To build a release version for the phone, without debug information type:

C:\Symbian\QuickStartExample>abld build gcce urel

An executable called QuickStart.exe is created in C:\Symbian\UIQ3SDK\epoc32\release\GCCE\urel

Should you need to remove everything built with abld build use:

C:\Symbian\QuickStartExample>abld clean

To remove everything including generated makefiles and exported files use:

C:\Symbian\QuickStartExample>abld reallyclean

Running on the Emulator

Start the Symbian OS emulator on the command line by typing:

C:\Symbian\QuickStartExample>epoc

You may have to wait a few minutes for the emulator to start. Once started, you will see the Applications view with Quick Start listed as an application:

Figure 5 Quick Start in the application launcher

Navigate to Quick Start and press return. The application will start:

Figure 6 Quick Start application

The emulator itself runs actual Symbian OS code compiled to run on Windows. Hence, it has a very high fidelity to the device itself and apart from hardware specific features, most applications can be developed initially using the emulator for debugging and testing.

It’s possible to configure each of the predefined configurations by name: SoftKey for Softkey Style, SoftKeyTouch for Softkey Style Touch and Pen for pure touchscreen based input in portrait mode:

C:\>UiqEnv –ui softkey
C:\>UiqEnv –ui softkeytouch
C:\>UiqEnv –ui pen

It’s also possible to refine this further by specifying touchscreen on/off, the UI style and screen orientation. Please see the UIQ SDK documentation for further details on the UiqEnv ui arguments. This is also covered further in the Chapter Testing, debugging and deploying.

Running the emulator and the QuickStart application again shows that the application framework automatically adapts the application to horizontal and pen mode:

Figure 7 Quick Start application in Pen Style Landscape

In particular, notice that the soft Select and More softkeys have automatically disappeared and there’s a new drop down arrow to the right of the Quick Start title. If you click on the arrow a drop down menu is shown:

Figure 8 Quick Start application menu in Pen Style Landscape

Selecting About demonstrates how the dialog also automatically adapts to being displayed horizontally:

Figure 9 Quick Start application menu in Pen Style Landscape

Packaging for the Phone

The GCCE UREL EXE can’t be installed directly on the phone without supporting files such as installation registration files and resources. These files must all be packaged up into an installation SIS file before they can be deployed to the phone.

A PKG file is used to define what files are to be contained within the SIS. The PKG file also declares the software developer’s name, the unique ID (UID) for the application, the program version, the versions of the phone the application can be installed on, language variants and an optional pre-install message.

The location of the source files depends on the location of your UIQ SDK. The example assumes this is \Symbian\UIQ3SDK. If this isn’t the case then you will need to edit the package file to use your UIQ install path.

In our example, the example PKG file contains the line:

"\Symbian\UIQ3SDK\epoc32\release\GCCE\urel\QuickStart.exe"-"!:\sys\bin\QuickStart.exe"

This copies the application executable from the GCCE release (as opposed to debug) directory within the SDK to a common sys\bin directory used by all applications on the user specified drive (denoted by the !).

To create a SIS file type:

C:\Symbian\QuickStartExample>makesis quickstart.pkg

QuickStart.sis will be created in the current directory. After the sis file is created, it may need to be signed depending on the capabilities that the application is using. It can then be sent to the phone via Bluetooth or a cable connection or by saving on a removable media card which is then placed in the phone.

Using Carbide.c++

Importing the `QuickStart` example into Carbide.c++

Importing a project into Carbide.c++ is straightforward:

Start up Carbide.c++.
Select File -> Import.
Select ‘Symbian OS Bld.inf file’ and click on Next.
Browse to the QuickStart example bld.inf file and click Next.
Under Symbian OS SDKs, select the UIQ 3 check box (which selects WINSCW and GCCE) and click Next.
QuickStart.mmp should be selected. Click Next.
Keep the default project properties and Finish.

The project files are shown in the left-most panel within a tree view:

Figure 10 Carbide.c++ project files

Double click on a file to view and edit. Double clicking on the MMP file shows a wizard style panel rather than the actual file that makes it easier to edit project options without having to know the syntax for particular keywords and settings.

Building for Emulation

Having imported the QuickStart project, Carbide.c++ will be automatically set up to build for the Windows emulator (WINSCW). However, should you ever need to view and select available builds, use the down arrow next to the hammer icon in the toolbar:

Figure 11 Carbide.c++ tools icon

Click on the hammer icon in top toolbar to start a build.

The window at the bottom right of the screen displays the results of the build. The Problems tab gives a quick summary of errors and warnings. Double click on a problem to go directly to the associated source file. The Console tab gives the similar information as would usually appear if you were to build from the command prompt.

Running the Emulator from the IDE

In order to run in the Symbian OS emulator from Carbide.c++ it is necessary to perform a one-time configuration to tell the IDE what to run and debug:

Select Run -> Debug As.
Double click on ‘Symbian OS Emulation’ and a pane will appear on the right hand side.
Use the default settings by pressing the Debug button.

You are now set up for future debug sessions by just selecting the bug icon in the toolbar, or pressing F11:

Figure 12 Carbide.c++ bug icon

The emulator will start and operate in the same way as was illustrated for running the emulator from the command line. Carbide.c++ will open a new set of windows called the ‘Debug perspective’ showing the call stack, variables and console messages.

You can stop debugging by either closing the emulator window or clicking the red terminate button in the Carbide.c++ toolbar:

Figure 13 Carbide.c++ terminate icon

Pro tip:

If the Debug view loses focus, the terminate control will appear disabled. To regain focus, select a thread in the Debug view to update the tool bar.

The Carbide UI stays in the debug perspective. You can change it back to viewing code by selecting Carbide c/c++ via the double right arrow at the very top right of the Carbide IDE:

Figure 14 Carbide.c++ code/debug selection

Building for the Phone

Use the down arrow next to the hammer icon in the toolbar to select the GCCE configuration. Carbide.c++ will automatically re-build for GCCE.

As with building from the command line, the resulting EXE needs to be packaged up with the installation registration and resource files.

To create a SIS file right click the QuickStart.pkg file and select Build PKG File. QuickStart.sis will be created in the current directory which can be sent to the phone via Bluetooth or a cable connection, or by saving on a removable media card which is then placed in the phone.

The console will show that both MakeSIS and SignSIS are invoked. SignSIS self signs the SIS which isn’t strictly needed for our simple example application. However, this becomes useful should the application need to be signed. Symbian Signed is covered in the Chapter Symbian Signed.

Code

Code for this chapter

DevEnvQuickStart_code.zip

Retrieved from "http://books.uiq.com/index.php/Development_environment_and_quick_start"

Development environment and quick start

From UIQ Books

Contents

Development environment and quick start

Introduction

Development Environment

UIQ SDK

Selecting the UIQ SDK

Carbide.c++ IDE

Alternative Development IDEs

CodeWarrior 3.0 and 3.1

Carbide.vs / Visual Studio .NET 2003

The `QuickStart` Example

Application Fundamentals

Application Architecture

Project Files

Unique Application ID (UID 3)

Resources, Icons and Controls

Commands

Building from the Command Line

Running on the Emulator

Packaging for the Phone

Using Carbide.c++

Importing the `QuickStart` example into Carbide.c++

Building for Emulation

Running the Emulator from the IDE

Building for the Phone

Code

Code for this chapter

Views

Personal tools

Navigation

available chapters

code download

Search

Toolbox

Development environment and quick start

From UIQ Books

Contents

Development environment and quick start

Introduction

Development Environment

UIQ SDK

Selecting the UIQ SDK

Carbide.c++ IDE

Alternative Development IDEs

CodeWarrior 3.0 and 3.1

Carbide.vs / Visual Studio .NET 2003

The QuickStart Example

Application Fundamentals

Application Architecture

Project Files

Unique Application ID (UID 3)

Resources, Icons and Controls

Commands

Building from the Command Line

Running on the Emulator

Packaging for the Phone

Using Carbide.c++

Importing the QuickStart example into Carbide.c++

Building for Emulation

Running the Emulator from the IDE

Building for the Phone

Code

Code for this chapter

Views

Personal tools

Navigation

available chapters

code download

Search

Toolbox

The `QuickStart` Example

Importing the `QuickStart` example into Carbide.c++