Quick Recipes on Symbian OS Sample Chapter

8/14/2019 Quick Recipes on Symbian OS Sample Chapter

1/20


2/20

10 QUICK START

Figure 2.1 Selecting a Workspace in Carbide.c++

will get a compilation error when using a workspace with a path thatcontains spaces).

After selecting a workspace, you will see the main window of Car-bide.c++ (Figure 2.2), which is also known as a perspective. This bookdoes not explain the user interface of Carbide.c++. Please refer to Car-bide.c++ Help to learn about it, or refer to the Symbian Press booklet atdeveloper.symbian.com/carbide booklet wikipage .

Figure 2.2 Main Window of Carbide.c++

2.3 Generating the Hello World ProjectFollow the instructions below to create a new Hello World project.


3/20


4/20

12 QUICK START

4. Click Next and select the SDK where you want to build the project(see Figure 2.5). Note that this template is compatible with S60 3rdEdition (all Feature Packs) and UIQ 3 (UIQ 3.0 and 3.1). You canchoose S60 3rd Edition or UIQ 3.x or both of them.

Figure 2.5 Select SDK

5. Click Next to enter the basic properties of the project (see Figure 2.6).The most important eld on this dialog is the Application UID. It is aunique identier for your application.

Figure 2.6 Entering Basic Properties of the Project

You can apply for UIDs for your applications on the Symbian Signedwebsite (www.symbiansigned.com ). For now, for development and


5/20

BUILDING THE HELLO WORLD PROJECT 13

testing purposes, you can use UIDs in the range of 0xE0000000-0xEFFFFFFF. By default, Carbide.c++ assigns a random UID in thisrange for your project.

6. Click Finish button to create the project.

If successful, Carbide.c++ will have created a Hello World project thatcontains several folders (see Figure 2.7):

group contains the project les used to build the application.

src contains the source code les ( .cpp les).

inc contains the header les ( .h les).

data contains the resource denition les ( .rss les) used to createmenus and some other UI-related components.

gfx contains the graphic les used to create icons. sis contains the package les ( .pkg les) used to create an installa-

tion le.

Figure 2.7 The Folders Created for a Standard Symbian C++ Project

2.4 Building the Hello World Project

A Symbian OS project can be built for the emulator or for a smartphone(sometimes known as a device or target hardware). Separate builds arerequired for the emulator and the smartphone; that is, an executable lefor the emulator cannot be run on the smartphone, and vice versa. Toallow you to switch easily between these builds, Carbide.c++ creates aconguration for each.

Building a project from Carbide.c++ IDE can be done by selecting theProject | Build project menu. Alternatively, you can also right click theproject name and select the Build project menu.

Before building a project, you can set the active conguration, tobuild for the emulator or device target. Setting the active congurationcan be done by right clicking the project name and selecting the Build congurations | Set Active conguration menu (see Figure 2.8).


6/20

14 QUICK START

Figure 2.8 Selecting the Active Build Conguration on Carbide.c++ IDE

There are normally two build congurations:

Emulator Debug (WINSCW). This requires a compiler, called NokiaCodewarrior C/C++ Compiler for Windows/x86 . This compiler isinstalled with Carbide.c++.

Phone Release (GCCE). This requires the GCC-E (GNU Compiler Col-

lection for Embedded ) compiler. The SDKs provide this free compileras part of their installation packages.

(If you have the RVCT compiler installed, you may have additionalbuild congurations available for smartphone builds. For the discussionin this chapter, we will be concentrating on WINSCW and GCCE buildcongurations only, but more information about the differences betweenthe GCC-E and RVCT compilers can be found in Chapter 6, Section 6.1.3.)

Tip: At the time of writing this book, most SDKs do not supportWindows Vista. There is a workaround available from the ForumNokia wiki (see links section at the end of this chapter) to make anSDK work on Windows Vista.

2.5 Running the Hello World Application on the EmulatorSelect the Run | Run menu from the Carbide.c++ IDE to run Hello Worldon the emulator. You can select the Run | Debug menu to debug theproject. Alternatively, you can also right click the project name to selectthe same menus.

Figure 2.9 shows the Hello World application running from the emu-lator. The S60 3rd Edition emulator is shown on the left, and the UIQ 3emulator on the right.

This Hello World application simply displays the text HelloWorld,which is the project name, on the screen, as can be seen in Figure 2.9.


7/20

RUNNING THE HELLO WORLD APPLICATION ON THE EMULATOR 15

(a) S60 3rd Edition emulator (b) UIQ 3 emulator

Figure 2.9 Hello World Application Running on the Emulators

The application also contains a single menu item that can be selectedeither via the Option softkey on S60 or by a mouse click on the Hel-loWorld title on UIQ (that area is called the title bar). Selecting theCommand1 menu item displays a notication dialog.

2.5.1 Conguring the EmulatorThe S60 emulator is congurable to represent different screen resolutionsand orientations (portrait or landscape). To do this, click the buttonat the top left of the emulators window. Figure 2.10 shows the sameHello World application running in the landscape mode. Notice that theOptions menu is on the bottom right of the screen and the Exit menu onthe top right of the screen.

Figure 2.10 Hello World Application Running on the S60 3rd Edition Emulator in Land-scape Mode


8/20

16 QUICK START

The UIQ emulator can be congured to represent different inputmodes, softkey or pen mode, as well as screen orientation. This can bedone using the uiqenv command. The following command changes theinput mode to pen mode and the screen orientation to landscape:

uiqenv -ui penlandscape

The following command changes the input mode to softkey mode:

uiqenv -ui softkey

Figure 2.11 shows the same Hello World application running on theUIQ 3 emulator in softkey mode. Notice that now the application has aMore softkey label at the bottom right of the screen. Pressing the rightsoftkey on the emulator will bring up the menu.

Figure 2.11 Hello World Application Running on the UIQ Emulator in Softkey Mode

Please refer to the SDK documentation for more information aboutvarious UI congurations.

2.6 Running the Hello World Application on the Device

Running the Hello World application on the device requires a SIS installa-tion le (.sis le). The installation le is created from the PKG package

le (.pkg le), located in the \ sis folder of the project. More informa-tion about the syntax to use in a PKG le can be found in the SymbianDeveloper Library CHM documentation, found in each SDK.

During the build process, the SIS le will be created automaticallyfrom the HelloWorld.pkg le. The result is HelloWorld.sis andHelloWorld.sisx . The .sis le is an unsigned installation le andthe .sisx a signed installation le. Nothing enforces that difference in


9/20

RUNNING THE HELLO WORLD APPLICATION ON THE DEVICE 17

lename extensions. Although it is unlikely you will ever see an unsigned.sisx le, signed .sis les are common.

You can use a number of ways to transfer the SIS le from yourPC to the smartphone. For example, the phone manufacturers normallyprovide a PC application to install the SIS le to the smartphone (Nokia

releases Nokia PC Suite for S60 devices; Sony Ericsson releases PC Suite for Smartphones for their UIQ 3 devices). So you could use the PCapplication that comes with the phone to install the SIS le or you couldsend an SMS that can be used to point the web browser of the phone tothe SIS le, so that you can download and install it. Alternatively, you cansimply use a Bluetooth connection between a PC and the smartphone tosend it to the phone.

Figure 2.12 shows the Hello World application running on S60 3rdEdition and UIQ 3 devices.

(a) S60 3rd Edition device (b) UIQ 3 device

Figure 2.12 Hello World Application Running on the Device

What may go wrong when you install the SIS le:

You may get an error message when you come to install the SIS le,which reads something like Certicate error. Contact the applicationsupplier.

This is because some devices, such as most S60 3rd Edition devices,do not allow installation of unsigned SIS les. You must self-sign theSIS le, using your own certicate (or you could get it signed by acerticate/key pair from Symbian Signed).

There are also some smartphones, such as Nokia ESeries phones,that do not allow the installation of self-signed applications by default.You have to make a change in the Settings menu to enable installationof self-signed applications.

On the other hand, there are some other devices, such as UIQ 3devices from Sony Ericsson, which allow installation of unsigned SISles.

The bottom line is that each device manufacturer may have adifferent policy about installing unsigned and self-signed applications.The developer community for your platform can help you sort it all out.


10/20


11/20

MODIFYING THE HELLO WORLD PROJECT 19

stateFlags = EQikCmdFlagDebugOnly;text = string_r_helloworld_close_debug;},

QIK_COMMAND{id = EHelloWorldSelectMe;type = EQikCommandTypeScreen;text = string_r_helloworld_selectme;},

QIK_COMMAND{id = EHelloWorldCommand1;type = EQikCommandTypeScreen;text = string_r_helloworld_command1;}

};}

3. Open \ inc \ HelloWorld.hrh . It is the header le for the resourcele. Add a new command identier, EHelloWorldSelectMe .

enum THelloWorldCommand{EHelloWorldCommand1 = 0x1000 ,EHelloWorldSelectMe

};

4. Open \ data \ HelloWorld_01.rls , which contains the denitionof localized strings. The sufx _01 in the lename indicates that it isthe localization le for UK English language. Add a new line belowto HelloWorld_01.rls .

rls_string string_r_helloworld_selectme "Select me"

At this point, if you build and run the application, you should see anew item (see Figure 2.13). This menu item does not do anything yet. Thenext section discusses how to handle the menu event from this new item.


Figure 2.13 Hello World Application With a New Menu Item


12/20

20 QUICK START

2.7.2 Handling a Menu Event

1. Open \ data \ HelloWorld_01.rls to add the string that is goingto be displayed when the menu item is selected.

rls_string string_r_helloworld_title "Title"

rls_string string_r_helloworld_description "Congratulations on yourfirst Symbian OS application."

The two lines above added two strings to the localization le for UKEnglish language. The rst string is used as the title for the noticationdialog and the second one is used as the content.

2. Open \ data \ HelloWorld_string.rss to add resources thatpoint to the two strings above.

RESOURCE TBUF256 r_helloworld_title{ buf = string_r_helloworld_title; }

RESOURCE TBUF256 r_helloworld_description{ buf = string_r_helloworld_description; }

The lines above added two string resources with the maximum lengthof 256 characters.

3. Open \ src \ HelloWorldAppUi.cpp . This le contains the deni-tion of CHelloWorldAppUi class, which handles various aspects

of the applications user interface, including the menu bar.Every GUI application should have its own AppUi class derivedfrom CEikAppUi or one of its derivative classes. For example, S60applications usually use CAknAppUi and UIQ applications usuallyuse CQikAppUi .One of the main roles of the AppUi class is to handle commands fromthe UI in its HandleCommandL() method. Add the code writtenin bold below in CHelloWorldAppUi::HandleCommandL() tohandle the menu event from our new menu item.

void CHelloWorldAppUi::HandleCommandL(TInt aCommand){

switch (aCommand){

#ifdef __SERIES60_3X__// For S60, we need to handle this event, which is normally// an event from the right soft key.case EAknSoftkeyExit:

#endifcase EEikCmdExit:


13/20

ADVANCED TOPICS ON CARBIDE.c++ 21

{Exit();break;}

case EHelloWorldCommand1 :{iEikonEnv->InfoWinL(R_HELLOWORLD_CAPTION,

R_HELLOWORLD_CAPTION);break;}

case EHelloWorldSelectMe :{iEikonEnv->InfoWinL(R_HELLOWORLD_TITLE,

R_HELLOWORLD_DESCRIPTION);break;}

default:// Do nothingbreak;

}}

Figure 2.14 shows the notication dialog that is shown when the userselects our new item on S60 and UIQ devices.


Figure 2.14 Displaying the Notication Dialog on the Hello World Application

Tip: This example uses a generic dialog, CEikonEnv::InfoWinL() ,to make it compatible with S60 and UIQ. Each platform also hasmore types of dialog that can be used for different purposes. Forexample, S60 has CAknInformationNote to display informationand CAknErrorNote to display error messages.

2.8 Advanced Topics on Carbide.c++This section describes some more advanced topics when using Car-bide.c++:


14/20

22 QUICK START

Modifying the project les.

Importing project les.

Changing the certicate/key pair.

You may prefer not to read this section now, but to continue to thenext chapter and come back later as needed.

2.8.1 Modifying the Project FilesA Symbian OS project is represented by a build conguration le (knownas a bld.inf le) and one (or several) project (MMP) les. Most examplesin this book have only one MMP le.

Both bld.inf andMMPles are ASCII text les. Carbide.c++ providesa user interface to edit them visually (see Figure 2.15a). They can also beedited using the standard text editor (see Figure 2.15b).

(a) An MMP file in the GUI editor (b) An MMP file in the text editor

Figure 2.15 Editing an MMP File using Carbide.c++

A bld.inf le is made up of a number of sections, such as a list of MMP les to build and a list of les to be exported. The following codeshows the content of bld.inf for our Hello World project:

PRJ_MMPFILESHelloWorld.mmp

#ifndef UIQ_UMTS_AVAILABLEgnumakefile icons_scalable_dc.mk#endif

As you can see, the bld.inf above contains one MMP le, which isHelloWorld.mmp . It also includes a GNU makele, icons_scalable_dc.mk , which is invoked if the macro UIQ_UMTS_AVAILABLE is notdened. This macro is dened on the UIQ SDK only. In other words, the


15/20


GNU makele will be used if the project is compiled using S60 SDK. Thisparticular makele will build a scalable icon to be used to represent theapplication in the main menu of the smartphone.

An MMP le species the properties of a project in a platform- andcompiler-independent way. During the build process, Symbian OS build

tools convert the MMP le into makeles for particular platforms.The following code shows the rst couple of lines of HelloWorld. mmp:

TARGET HelloWorld.exeTARGETTYPE EXEUID 0x100039CE 0xEF1D5F42

CAPABILITY None

LANG SC

...

When do you need to modify the project les? One case that you willnd very often in the following chapters is adding libraries. The HelloWorld project includes some general libraries (see Figure 2.16). In orderto use some specic APIs, such as multimedia or telephony, you wouldneed to add additional libraries. To add libraries, click Add and selectthe libraries you want to add.

Figure 2.16 Adding Libraries to the Project File

Another case that you will also nd quite often is adding platform

security capabilities (they are described in Chapter 3). The Hello Worldproject does not include any capabilities, as you can see in Figure 2.17.Many APIs discussed in this book require additional capabilities. Forexample, the telephony API requires NetworkServices . Click Choose to add more capabilities to the project le, as shown in Figure 2.17.


16/20

24 QUICK START

Figure 2.17 Adding Capabilities to the Project Files

2.8.2 Importing Project FilesAll sample codes from this book are available for download from

developer.symbian.com/quickrecipesbook . In order to compile themin Carbide.c++, you need to import their project les ( bld.inf les).Follow the steps below to import a project le:

1. Select File | Import menu from Carbide.c++ IDE.

2. In the Import dialog, select Symbian OS | Symbian OS Bld.inf le (see Figure 2.18).

3. Click Next and select the bld.inf le you want to import (seeFigure 2.19).

Figure 2.18 Import a Project File into Carbide.c++


17/20


Figure 2.19 Browse to the bld.inf of the Project to be Imported

4. Click Next and select the SDK. The dialog is similar to the one whencreating a new project (shown in Figure 2.5).

5. Click Next to select the MMP les to be imported (see Figure 2.20).Since most examples contain only one MMP le, you can just pressNext again.

6. The next dialog asks for project name and location (see Figure 2.21).You can usually just use the default values and click Finish.

Figure 2.20 Select the MMP Files to be Imported


18/20

26 QUICK START

Figure 2.21 Enter the Project Name and Location

2.8.3 Changing the Certicate/Key PairBy default, Carbide.c++ creates a self-signed certicate/key pair whencreating a SIS le. A self-signed certicate is sufcient for many applica-tions. However, there are cases when you need to apply for a developercericate at Symbian Signed (www.symbiansigned.com ), for examplewhen using the Location API (see Section 4.10). The developer certicateallows your application to use restricted APIs that cannot be accessedusing a self-signed certicate.

Follow the instructions below to change the certicate/key pair of your

project:1. Right click the project name and select Properties .

2. In the Properties dialog, select Carbide.c++ | Carbide Build Cong-uration. On the SIS Builder box, select the name of the SIS le andclick Edit (see Figure 2.22).

3. In the SISProperties dialog, enter the certicate/key pair les (seeFigure 2.23). If your key requires a password, you can enter it hereas well.

2.9 Links Code samples for Symbian Press books, including this one:

developer.symbian.com/quickrecipesbook .

Forum Nokia wiki Moving to Windows Vista: wiki.forum.nokia.com/index.php/Moving to Windows Vista .


19/20

LINKS 27

Figure 2.22 SIS Builder in Carbide.c++ IDE

Figure 2.23 Change the Certicate/Key Pair in the SIS Builder

Information about errors that occur when installing self-signed, orunsigned, SIS les:www.antonypranata.com/articles/ interpreting-signing-error-messages-s60-3rd-edition .


20/20

Quick Recipes on Symbian OS Sample Chapter

Documents

Transcript of Quick Recipes on Symbian OS Sample Chapter