Symbian
Home | Developer | Technology | Partner | News & Events | About us
  
Developer home
Downloads
Tech papers
System docs
FAQs
Newsletter
SDKs
Books
C++ papers
Java papers
Expo transcripts
Technology white papers
Books
Glossary
C++ developer paper
Getting Started with C++ Development on the Series 60 SDK

Doug Marshall & Colin Turfus, Symbian Developer Network
Last revised: June 2002, Version 1.0

Introduction

Series 60 Platform is a new wireless software product based on Symbian OS. Created by Nokia, it is freely available for licensing by other handset manufacturers. Siemens are the first announced licensee. Easy to use, and interoperable with a wide range of standards, it is designed to take advantage of the latest mobile services. Developers can write C++- or J2ME-based applications for Series 60 phones.

In this tutorial we're going to have a look at how to create a simple C++ application for the Series 60 platform. Symbian OS is an open, robust and fit-for-purpose operating system designed specifically for use in next generation mobile telephones and communicators with integrated voice and data capabilities. It is written largely in C++ and that language therefore represents a strong development choice for 3rd parties.

We shall assume no prior specific knowledge of Symbian OS but it does assume familiarity with C++ syntax and also that the reader has obtained the Series 60 Software Development Kit (SDK) from http://www.forum.nokia.com/ as well as having installed Microsoft Visual C++. The SDKs provide documentation, tools and example code to assist developers along with a Microsoft Windows hosted Series 60 emulator. The SDK is essential for developing, testing and debugging C++ applications.

The tutorial aims to provide a brief overview of the main components which make up an application suitable for use on a Series 60 phone such as the Nokia 7650. It will explain in detail the code for a basic example application and the key concepts involved. It is not, however, intended to replace the comprehensive system documentation provided with the SDK and as such minimal treatment is given to the Symbian tool chain and development environment used to create applications.

1. Overview of “Hello World”

We shall create from scratch a minimal "Hello World" example application and run it in the Series 60 emulator. We'll do this using the application wizard, to which you will be introduced in the next section. We'll go on to describe the small amount of customization of the template project produced by the wizard that is needed to get a minimal Hello World app up and running.

Next we will look in more detail at the various files which are created by the wizard as part of your project. We will discuss their function and how this relates to the Symbian OS application architecture which is common across all Symbian OS C++ applications.

Next we'll look at each of the folders in turn which make up our Hello World project and explain the function of the various files in each, including how and why you might want to customize them when writing your own application. We'll look at the contents of the more important source documents as we go along to get a feel for what different parts of the code do, and how they relate to the application architecture as a whole.

2. The Nokia Series 60 AppWizard

Our work in creating a minimal "Hello World" application will be much reduced by taking advantage of the Nokia Series 60 Appwizard. This allows you to carry out at one fell swoop all the repetitive boiler plating needed to create a new Series 60 application, build it in its own project, and run/debug it in the Series 60 emulator. All that we need for the task is contained in the folder \NokiaTools\ApplicationWizard in your SDK root.

In fact all you need is the one file AvkonAppWiz.awx. To use the wizard you should copy this file to your Visual C++ template directory, e.g.
"c:\Program Files\Microsoft Visual Studio\Common\MsDev98\Template"
if you have installed your Microsoft Visual C++ into "c:\Program files\ Microsoft Visual Studio". Then, to create your HelloWorld application, do the following:

  • If you have more than one SDK installed on your computer, ensure that EPOCROOT is set appropriately
  • Start up Visual C++ and open the "File/New" dialog.
  • On the "Projects" tab you should find a "Nokia Series 60 AppWizard v1.7" item. Select that.
  • Specify "Hello" as the Project name and, in the Location box, browse to the folder \NokiaEx in your SDK root. You should see a "Hello" folder appended to the path. Then press OK.


Figure 1. The App Wizard for the Series 60

  • From the wizard dialog you can select which type of application you would like to create. Leave the "EIKON Control" option selected and specify "Hello World" as the Application Title. Choose any UID of the form 0x01??????, where "?" is a hex symbol, to uniquely identify your application to the system. Leave all the other boxes unchecked. Then hit Next.

    NOTE: The latest version of the Series 60 SDK (beta 0.3) generates a unique number for you, chosen from a range of test UIDs. If this number is the same as another existing app on your emulator its icon will not be displayed and you will be unable to launch the app. If you plan on releasing an app you will need to request that a UID or UIDs be allocated to you - more details can be found in the SDK.


Figure 2. Selecting a UID

You don't need to do anything on the next two screens, just hit Next then Finish. You will be shown a list of all the project and source code files you have just created: no small number of these!

If the version of your Series 60 SDK is beta 0.3 or later than you can skip the following three steps

  • When you hit OK, the wizard automatically tries to open the generated project in Visual C++. It fails as the project is not yet of Visual C++ type.
  • To create a project which can be so opened, start up a command prompt and navigate to the newly created \NokiaEx\Hello\group folder in your SDK root and enter "bldmake bldfiles". A file "abld.bat" should be created for you in that folder. Now enter "abld makefile vc6". (If you haven't already set the environment for Visual C++ tools, you may need to invoke vcvars32.bat at this stage.) A workspace called Hello.dsw should be created for you in the folder \epoc32\build\NokiaEx\Hello\Group\Hello\Wins in your SDK root. (There are reasons the path is so long which you don't want to worry about here.)
  • Double-click on the workspace file in an Explorer window and your project will open up in your Visual C++ IDE, where you can browse the associated files and class hierarchy.

At this point you should be able to compile and run the minimal application. Compile it in the usual way, e.g. hitting F7. This may generate two warnings about a missing file called edll.pdb which is used for debugging purposes – this one is rarely used and you do not need to worry about it.

To run the application, hit CTRL+F5. When asked for the executable, navigate to Epoc.exe in the folder \Epoc32\Release\wins\udeb in your SDK root. This launches the debug emulator, the default for your project.

If you would like to run the app through the debugger, press F5. You will be warned that there is no debug information associated with Epoc.exe. This is OK as it is your app (essentially a DLL) which will be debugged, not the emulator itself. Check the box so you won’t receive this warning again for this project. The app, and the associated debug information, are in fact located in Epoc32\Release\wins\udeb\z\system\apps\Hello.

Once the emulator has been launched, you must navigate to your app in the system shell and click on it. First navigate down to the Other folder using either the cursor keys on the emulator fascia or your PC's cursor keys. To open the folder, you must click on the action button in the middle of the cursor controls. Navigate to Hello World and click on the action button again.


Figure 3. Selecting the Hello World Application from the System Shell

3. Customizing the application

Let's now do some customizing of the application so we can display our own message texts. Close down the emulator (if you haven't already done so) and return to the project in Visual C++. Find the source for the method void CHelloContainer::ConstructL(const TRect& aRect)in the file Hellocontainer.cpp. It contains the two labels you will have seen on the screen when you ran your app. Change the text of iLabel to "Hello World!" and delete the three lines defining iToDoLabel. Your method should now look as follows:

void CHelloContainer::ConstructL(const TRect& aRect)
    {
    CreateWindowL();

    iLabel = new (ELeave) CEikLabel;
    iLabel->SetContainerWindowL( *this );
    iLabel->SetTextL( _L("Hello World!") );

    SetRect(aRect);
    ActivateL();
    }

You will also have to remove iToDoLabel from the container's destructor:

CHelloContainer::~CHelloContainer()
    {
    delete iLabel;
    }

and from the SizeChanged() method in which the size of the controls is determined:

void CHelloContainer::SizeChanged()
    {
    // TODO: Add here control resize code etc.
    iLabel->SetExtent( TPoint(10,10), iLabel->MinimumSize() );
    }

and from the ComponentControl() which the system uses to access the controls:

CCoeControl* CHelloContainer::ComponentControl(TInt aIndex) const
    {
    switch ( aIndex )
        {
        case 0:
            return iLabel;
        default:
            return NULL;
        }
    }

Since we have changed the number of controls (labels) in the container, we must also modify the control count. Change the CountComponentControls() method to return 1 instead of 2:

TInt CHelloContainer::CountComponentControls() const
    {
    return 1; // return nbr of controls inside this container
    }

Some other tidying up is strictly needed of header and resource files following the removal of the extra label. But that will not stop us from successfully re-compiling and running our app, so we'll leave it for now. Finally let's make a few modifications to the Options menu. This is handled in the file Helloappui.cpp. in the HandleCommandL() method. Let's change the InfoMsg text to say "Hello again":

void CHelloAppUi::HandleCommandL(TInt aCommand)
    {
    switch ( aCommand )
        {
        case EAknSoftkeyBack:
        case EEikCmdExit:
            {
            Exit();
            break;
            }
        case EHelloCmdAppTest:
            {
            iEikonEnv->InfoMsg(_L("Hello again"));
            break;
            }
        // TODO: Add Your command handling code here

        default:
            break;
        }
    }

We'd also like to change the "Test" menu item so it describes itself more appropriately. The changes need to be made in the resource file hello.rss. Change the EHelloCmdAppTest text in the r_hello_menu struct to "Say Hello":

RESOURCE MENU_PANE r_hello_menu
    {
    items=
        {
        MENU_ITEM { command=EAknCmdExit; txt="Exit"; },
        MENU_ITEM { command=EHelloCmdAppTest;
        txt="Say Hello"; }
        };
    }

We're now all set to recompile. Following the same procedure as before, when you run the re-compiled app and click on the Options soft button, you should see the following


Figure 4. Options Menu

Clicking on the "Say Hello" option directly or moving the cursor down to "Say Hello" and hitting the action button results in the display of an InfoMessage in the top right hand corner for about three seconds:


Figure 5. “Hello Again” Infoprint

4. The Application Framework on Symbian OS

The way applications are launched on Symbian OS varies slightly between the Microsoft® Windows™ hosted emulator (technically called “WINS” which stands for WINdows Single process) and a ‘real’ target device such as the Nokia 7650. To all intents and purposes this is largely irrelevant to most developers – only developers doing more advanced work need worry about the differences between WINS and a target device.

A key part of the application framework is UIKON. This is a standard framework common to all devices running Symbian OS. It not only provides the framework for launching applications but it also provides a rich array of standard control “components” (e.g. dialog boxes, number editors, date editors, etc.) which applications can make use of at runtime.

An “application” on Symbian OS actually consists of four distinct components, each with a corresponding class within the UIKON framework. It helps to view this as follows:

  1. The Application ‘shell’ itself. This is derived from CEikApplication and this class is instantiated first by the framework. Once created it has responsibility for initialising the rest of the code. Your CEikApplication-derived class then creates…
  2. The Document. This is derived from CEikDocument. This can be slightly misleading in that not all applications actually have ‘documents’ associated with them as far as the user is concerned. For example, the NotePad application is very obviously ‘document based’ while Clockapp or Idleapp do not offer the user the ability to create, open or edit documents. In reality, all applications have a CEikDocument-derived class but for applications such as Clockapp or Idleapp (and indeed our own Hello World) this is little more than a shell, required by the framework to create…
  3. The App UI. Your App UI class is derived from the UIKON class CEikAppUi. This is the class, which provides major functionality to all applications such as event handling, control creation, access to many useful system calls, etc. The CEikDocument-derived class is responsible for creating the final part of the application…
  4. The View. This is what the user actually sees on screen. It can be used to simply display data (as we do in Hello World) or to collect data from the user in more complex applications (for example, the editor in the Word application where text is typed is simply a standard control provided by UIKON, contained within the view). While all applications have one default view, the most complex ones can offer many views (e.g. ToDo). The physical appearance of your views (and also menus, dialog boxes, etc.) can be made more professional by complying with the Nokia Series 60 UI Style Guide, which is part of the Series 60 SDK Help documentation.

A visual representation of this process is as follows:



Figure 6. How an application is launched in Symbian OS

5. The Hello World Application Code

The code for HelloWorld is broken down into several .CPP files, each designed to represent a segment of the above application launching process. These files are:

  • HelloApp.cpp              - The Application
  • HelloAppUi.cpp           - The Application UI
  • HelloContainer.cpp      - The View
  • HelloDocument.cpp     - The Document

In addition the following files make up the rest of the source for the project:

  • Hello.h                    - Header file with class definitions
  • hello.rss                  - Standard resource file containing many UI definitions
  • hello_caption.rss      - Contains captions for the application’s icon
  • Hello.uid.cpp            - UID source file, generated by build tools
  • Hello.hrh                  - Definitions of some UI control identifier numbers
  • HelloApp.h               - Header file for Helloapp.cpp
  • HelloAppUi.h            - Header file for Helloappui.cpp
  • HelloContainer.h       - Header file for Hellocontainer.cpp
  • HelloDocument.h      - Header file for Hellodocument.cpp

Finally, the following files make up the build files used by the Symbian SDK tools to create the project (for more details please see the SDK system documentation);

  • Bld.inf
  • HelloWorld.mmp

We will now examine in turn the role of various files which make up our project.

5.1 Files in \aif\ - The Application Information Files

Application Information Files, extension .aif, store data concerning an application including:

  1. icons in various sizes used by the system to represent your application
  2. caption in supported languages
  3. capabilities, such as embedding, new-file and hidden
  4. MIME-type support priorities

Without an aif file an application will use a default icon, and will use the application name as a caption. It can be created independently of the app wizard by the aif builder tool, and it is used at runtime.

5.2 Files in \data\ - The Resource Files

A resource file is used in Symbian OS to define the characteristics of the widgets your application uses to display itself on screen. Everything from the status pane, the menu and hotkeys through to individual dialog boxes can be defined in the resource file. Resources initially look rather complex but when taken step-by-step they are quite straightforward. Comprehensive documentation and explanations are available in the SDK.

hello.rss

This resource file lists the names for menu options and other headings within the application as detailed above. For definition of Avkon specific constants, see %epocroot%Epoc32\include\avkon.hrh

hello_caption.rss

This file contains the application name for display in the “app launcher” of the Series 60 UI. Two sizes are quoted to accommodate zoom levels of the UI.

Both of these files are used by the resource compiler (rcomp) which is automatically called before the compilation of the source files, but only if the resource file has been updated since the last running of rcomp.

5.3 Files in \group\ - The Build Files

As mentioned above, these files are used by the toolchain to construct your project files and build the application from source. Please see the SDK for detailed descriptions of these files.

Abld.bat

Uses the build batch .make files, generated by the bldmake tool. It is used to carry out the various stages of the building of components which have been defined by a bldmake component description file (bld.inf).

BLD.INF

This is a component description file, which lists all the projects in a component (in our case just one) and may give additional build instructions. It specifies the location of the component’s mmp file(s).

Hello.mmp

An mpp project definition file specifies the properties of a project in a platform and compiler-independent way. The makmake tool converts project definition files into makefiles for particular platforms. The abld tool wraps calls to makmake, and can be more convenient to use than makmake directly.

5.4 Files in \inc\ - The Hello World Header Files

These files are all used at build time by the C++ compiler.

Hello.hrh

This file contains declarations of enumerated constants which are used in both source files (cpp) and resource files (rss). These constants are Command IDs specific to our application. They may be used for key handling or for command handling in Dialogs. For the moment our app has only got one: EHelloCmdAppTest = 1.

Note that avkon.hrh in %epocroot%Epoc32/Include/ contains many enumerated constants defined by the Series 60 UI framework this is a very important file for Series 60 applications. For example, one of the constants defined is EAknCmdExit; this is the standard value passed by the framework when your application should close down (a system backup for example).

Hello.loc

This is a localisation file for Hello – the .loc extension is not necessary but helps in identifying the file. It is #included in Hello.rss and is the place where the logical strings to be localised are defined.

Hello*.h

Contains the Class definitions for Hello*.cpp

5.5 Files in \install\ - To create SIS files

The Symbian Installation System provides a simple and consistent user interface for installing applications, data, or configuration information to Symbian OS phones. End users install components packaged in SIS files either from a PC, using the installer, or from a Symbian OS phone, using the Add/remove program (called “Application Controller” on Series 60 phones).

Hello.pkg

A pkg file is a text file which contains installation information for applications or files. It is either created by or imported into the Sisar tool, which bundles all application files into one .sis file for ease of installation onto target hardware.

5.6 Files in \src\ - The Hello World Source Files

The source files for the Hello World application are all in this directory. The file names reflect the classes that are implemented in them. For example Helloappui.cpp contains all the source for the implementation of CHelloAppUi, our AknAppUI derived class. You can refer back to section 5 for a description of each component. Detailed information can be found in the SDK.

These files, along with the header files in \inc\ and the compiled resource files (rsc and rsg), are used by Microsoft Visual C++ for emulator builds, or the GCC compiler for target hardware builds, to create the binaries for your application.

To get a better grasp of what is going on it will be beneficial to look at a few important functions in these files

Helloappui.cpp

Every Series 60 application should use its own class derived from CEikAppUi to handle application-wide user interface details. Responses to various kinds of events can be handled at the level of the app UI by providing suitable implementations of various functions. The two present in Hello World are as follows:

  • HandleCommandL()
    This function
    is called by the UI framework when a command has been issued. In the Hello World application, a command can originate through the selection of a menu item, or the selection of a CBA button. The various command IDs are defined in the hrh file, and are associated with the menu and CBA items in the application resource file hello.rss.
  • HandleKeyEventL()
    Key events come from the window server. Each keyboard key press generates three separate key events in the order; EEventKeyDown, EEventKey, and EEventKeyUp. Most controls are mainly interested in EEventKey for handling ordinary events. This function may be overridden by derived classes.

In our Hello World application they don’t do anything. To add commands to this application they would need to be defined in the resource file and they would then be handled in the appropriate function above.

Please see the SDK for a full list of CEikAppUi function used to handle various types of event.

Hellocontainer.cpp

The class contained in this file is a container control (or compound control). This is a control that contains other controls within it (which are called component controls). There are therefore a few important functions to consider, especially if you are to add more component controls to the container control.

  • CountComponentControls()
    Returns the number of controls within the container. As you add controls you will need to ensure that this function increments the amount of controls appropriately.
  • ComponentControl()
    R
    eturns a control depending on the index passed into the function. Within a container control, each component control is identified by an index, where the index depends on the order the controls were added: the first is given an index of 0, the next an index of 1, and so on.
  • SizeChanged()
    This function provides the ideal location to set the position of the component controls as it is called by the framework whenever a function that could affect the container’s size is called. For a list of these functions, please see the SDK documentation.
  • ActivateL()
    The application should call this function on all controls that are not components in a compound control. The purpose of this function is that controls are not always ready to draw as soon as they have been constructed. For example, it may not be possible to set the control's extent during construction, but its extent should always be set before it is drawn. Similarly, if a control is to be made invisible, this should be done before it is activated. The default implementation sets a flag in the control to indicate it is ready to be drawn. If the control is a compound control, the default implementation also calls ActivateL() for all the control's components. To get the control's components it uses CountComponentControls() and ComponentControl(), which should be implemented by the compound control. ActivateL() is typically called from the control's ConstructL() function.

6. Where to now?

6.1 Portability of code across Symbian OS phones

One of the main reasons for the creation of Symbian OS was to enable a cross-platform development environment for products built by more than one mobile phone manufacturer. After you have gained familiarity with developing and deploying C++ applications for the Nokia Series 60 using the Series 60 SDK, you should be able to do the same easily on other Symbian OS SDKs customized for other phones.

6.2 Support

Forum Nokia

Forum Nokia is Nokia’s support forum for developers using its technologies and is found at http://www.forum.nokia.com/

The forum contains a wealth of information on Symbian OS for the Nokia Series 60, as well as free SDKs. Access to these resources is available free to all registered developers. Resources also include discussion forums devoted to Symbian OS development on Nokia phones.

Symbian Developer Network

As a developer targeting Symbian OS phones, Symbian Developer Network (Symbian DevNet) is your primary resource to get access to the technical and commercial information and resources you need to succeed in the wireless space. Symbian DevNet provides:

  • discussion forums, code resources, and tips about Symbian OS development
  • a portal to other such resources and technical and commercial services on Symbian DevNet partner sites
  • a newsletter keeping you informed of what's new and hot on the Symbian DevNet Web site and across all our partner sites
  • the Symbian OS Knowledgebase which provides up-to-the-minute information about Symbian OS such as:
    • answers to frequently asked questions
    • defect reports and the corresponding workarounds
    • useful code snippets illustrating Symbian OS techniques
    • other development information which is not available in the Software Development Kit documentation

6.3 Further Reading

  • Series 60 SDK: Symbian OS v6.1 Edition for C++ » Tools and Utilities » Build Tools Reference » Tools and file types used in build process
  • Series 60 SDK: Series 60 » Series 60 Developer Guides » Nokia Series 60 Application Framework Handbook
  • Series 60 SDK: Series 60 » Series 60 Developer Guides » Nokia Series 60 UI Style Guide
 
Legal Disclaimer | Privacy Policy | Sitemap | Media center | Contact us | © 2005 Symbian Ltd.