Tutorial 4: Building the Yellow Pages Application

Go through Tutorial 3 first.

In this tutorial, we would build a Yellow Pages Application. We will continue it from the last tutorial and extend it to have one more form and another dialog, the MessageQueryDialog to display the required data. We will also look into Symbian File Handling to retrieve the data about businesses.

First, add another form in the resource file in a similar fashion as the earlier form(define a resource in resource file and class to handle the form events) to provide for selection of category. Go through the previous tutorial if you have any problems in adding another form. Once the form is added, we need to execute the form after the city is successfuly selected in the first form. To do this, we make a new form object in the SaveFormDataL() method of the first form(just like we did in HandleCommand for the first form). Once, we have extracted the city and categories, we will now extract the corresponding information about the businesses in the city for the category from te file that we have stored in the phone’s memory.(You need to make those files(or copy them from the YPages folder) and place them in the memory) For running the application on the emulator, just place the folder YPages from the current directory to the SDK’s winscw folder-
Default Path: “C:\S60\devices\S60_5th_Edition_SDK_v1.0\epoc32\winscw\d”

File Handling in Symbian:

First, you need to obtain a handle to File Server session and connect to it. You can do this by:

RFs fileServer;
User :: LeaveIfError (fileServer.Connect());

Now, we will use the RFile class to read data. Open the file for reading. The EFileStreamText flag denotes that the file opened is a text file. The EOF is indicated by the return value of TTextFile::Read(), which is KErrEof.

RFile file;
User::LeaveIfError(file.Open(fileServer, KMyTextFile, EFileRead|EFileStreamText));

The class to read a text file is TFileText. It is declared in f32file.h header file and a library named efsrv.lib(add this to the mmp file). Before using TFileText, we have to open a file using RFile because TFileText does not have an Open method. TTextFile has Read() method which requires a 16 bit descriptor parameter because Symbian OS stores text files in unicode format. Do not use TFileText to open a file other than unicode. we will get garbage characters if trying to access non Unicode files, such as ASCII files. Go through the source code to understand clearly.

Close the file server session after the reading is completed.

After successfuly reading data from the file, we will now print the read data in a MessageQueryDialog. We must first define the resoruce for this dialog. We have defined a r_about_heading_pane resource in the resource file. It is similar to previous dialogs, define the flags, cba function, and items. the difference here is that we do not define a for for this dialog. Instead we define 2 items, heading pane, and a CAknMessageQuery to hold the text.

After defining the resource in the resource file, we must execute the resource in the SaveFormDataL() after reading the data from file. For this, create a new object of type CAknMessageQueryDialog and Prepare it with the resource defined in the resource file. Then, set the header text and finally call RunLD() on dialog to display it. The text to be displayed in the dialog was passed alongwith the dialog’s constructor while making the new object.

Download Source code for this tutorial here.

Tutorial 3: Creating Forms & Supporting Multiple Languages

Go through tutorial 2 first.

In this tutorial, we look into more complex dialogs. For our application, we use the form dialog. A form displays a set of data fields in the form of a list, with each data field in the list consisting of a label and a control. The label can be on the same line as the control, or it can be on a separate line, with the control below it. In addition, a form dialog is automatically associated with a standard menu that supplies the options:
Add field, Edit label, Delete field, Save and, optionally, Edit.

Selecting one of the first four of these options results in a call to the appropriate one of the CAknForm functions: AddItemL(), EditCurrentLabel(), DeleteCurrentItem() and SaveFormDataL(). In our application, we use only the save option which in turn calls the SaveFormDataL() function.
An S60 form has two modes: in ‘view’ mode it acts as an application view that displays a list of data items, and in ‘edit’ mode it can be used to modify the data items displayed. By default, it starts up in ‘view’ mode and you can switch to ‘edit’ mode by selecting the Edit menu option. When you have finished editing the data, you press the right softkey (temporarily labeled Done)to return to the ‘view’ mode. A form is actually more powerful than a dialog. If, for example, the data items it is displaying are the fields of a database record, you can implement the commands described above to add, delete, or modify entire records.
You can specify that the form should be edit-only (via a fiag in the FORM resource), so that the form is always in ‘edit’ mode, and in this case, the Edit menu option does not appear.

You can also override its DynInitMenuPaneL() to disable some or all of the other menu options. You specify a form in the resource file by creating a FORM resource and assigning it to the form attribute of a DIALOG resource (or a PAGE resource for multipage dialogs). The FORM resource contains the list of DLG LINES that specify the label and control for each field in the form’s list.

We can also provide support for multiple languages in the application through the rls file. While you can put text strings directly within the resource file, this is not recommended if you need your application to support different languages. Symbian recommends that you put all your strings into a RLS file, and then include this string file using #includein your RSS file. There should be a separate RLS file for each language you support.
Each string in the RLS file is defined using the rls string keyword. For example:

rls_string STRING_r_gui_start "Start";  

As you can see, the DIALOG resource defines the flags and softkeys, and the form attribute points to a FORM resource. This resource specifies the dialog’s content which, in this case, consists of one dialog line: a S60-specific control, known as a pop-up field (type EAknCtPopupFieldText and control structure POPUP FIELD), which is used to select the city. The FORM resource has an additional flags attribute, which is used here to set each control and its prompt to be displayed on separate lines, and to set the ‘edit only’ mode that was mentioned earlier. We also define the list of cities to appear in the popup field using a RESOURCE ARRAY r_city_list.

PreLayoutDynInit() is overridden to set the initial values of the controls in the form. We also override the SaveFormDataL() method to perform the save operations. For our application, we obtain the index of the selected city from the popup menu using the CurrentValueIndex() method in popupFieldText. we then print a dialog similar to the one printed in the second app to display the selected city index. The descriptor method Format() does this. The format string supplied to Format() is very similar to the format string in C, supporting %d, %s, %f, etc.

This wont display the form on the screen. To make the form appear on the screen once we select the start menu item, we need to handle the command in HandleCommand() method in Application Ui Class. We create a new form object and execute R_THIRDAPP_DIALOG which was defined in the resource file.

Download Source code for this tutorial here.
Go through tutorial 4 now.

Tutorial 2 : First Dialog

Go through tutorial 1 first.

Now that you know how to print text on the screen, lets go to a little more complex application. We aregoing to add a menu to the application, how to handle commands in a little more detail, and finally create an alert dialog.

Here are the changes that it makes to the first tutorial.

• Add the menu bar resource in the resource file to display the menu. The menubar attribute of EIK APP INFO is assigned a resource of type MENU BAR, which specifies the application’s default menu. Menu bar resources have one or more menu titles (type MENU TITLE)and each menu title points to a menu pane (type MENU PANE). The menu bar in the example, r_SecondApp_menubar, has a single menu title and this points to menu pane r_SecondApp_menu. Menu panes define the actual menu items (type MENU ITEM), whichthe user selects to invoke some operation in the application. r_SecondApp_menu defines a menu item labeled ‘Start’ that sends the command ESecondAppCommand to the GUI command handler code when the user selects it (so the code can display the Application’s dialog).

• Now, we need to define the command codes used in the resource file. These are defined in the .hrh file. The file SecondApp.hrh contains the command values that the controls send (specified in the resource file) for the application code to handle. In this case we have only one, used when Start is selected:

  enum TSecondAppIds
      {
      ESecondAppCommand = 1
      };

• the menu item ‘Start’ is selected, the GUI framework invokes the HandleCommandL() method, passing it the command ESecondAppCommand (the command specified in the menu resource in the SecondApp.rss file). HandleCommandL() responds to this command by popping up an alert window with the message ‘Your First Dialog!’.We can use the iEikonEnv->AlertWin() function for the pop-up since this is a core GUI method available to all platforms. This function takes one arguement which is a descriptor.

  • Descriptors are classes that represent data buffers and allow you to safely access them. Symbian OS uses descriptors to store and manipulate strings (as opposed to NULL-terminated C strings), as well as to manage binary data. Descriptor classes, although containing many features, are optimized for minimal overhead, since they are designed to run on memory-constrained devices. There are multiple descriptor classes available in Symbian. You’ll need to use descriptors to call many of the Symbian OS API functions.

  • A String Literal(Descriptor) in Symbian is declared as:

            _LIT(KMessage,"My First Dialog!");

    The LIT macro is called to take the string “My First Dialog!” and stores both the string and the string’s size in the descriptor literal KMessage.

Download Source code for this tutorial here.
Go through tutorial 3 now.

Tutorial 1 : Learning the basics

Now that you have downloaded the SDK and know how to make projects in Carbide, we will now look into our first GUI Application which prints a line of text in the center of the screen. The main goal of this tutorial is to get a feel for developing a basic application by actually building and running one on the emulator.

Application Architecture

A minimal Symbian GUI Application must contain the following 4 classes:

Application View: The view class implements the application’s screen display, including drawing the window and the creation of the initial screen controls. The class is inherited from CCoeControl which is fine for Applications with just one view class. We would only be discussing a single view class for now.

Application UI: This class instantiates the application view and handles the commands sent from the application’s GUI controls.

Application document: This class handles the non-GUI data aspects of the application – the application data. It also instantiates the application’s UI class.

Application: This class is used to identify the application (by returning the application’s UID) and to instantiate, and return a pointer to, your application’s document class.

Now let us discuss these classes one by one.

Application View Class:

The application view class handles the presentation of your application on the smartphone’s screen, as well as allowing the user to interact with your program. In Symbian OS all objects drawn to a screen are controls – including the application view, which is a custom control. It has the following methods:

NewL, NewLC and ConstructL: These methods construct a new object of the view class. We will discuss about why we took these 3 methods and not just the constructor to construct the new object later in error handling.

Draw(): Draw() is a method called by the framework for every control in order to draw it to the screen. The application view is a control, and, we implement the Draw() function to output the text ‘First Application’ in the center of the window. The drawing is performed by opening a graphics context (GC), getting a font, and calling the context’s DrawText() function. Cleanup is performed on the font upon

completion.(Cleanup will be explained in error handling.)

Application UI Class:

Your application’s UI class is responsible, upon construction, for creating the application’s default view. In S60, for basic one-view applications (i.e., the view is a simple control), the UI class contains the command handler that handles all the commands the users initiate via the GUI. If you are using multiple views, however, this command handler would be in the view class. It has the following methods:

ConstructL(): This function does the work of construction of an object of View Class.
HandleCommandL(): This function handles the commands passed from the Application’s GUI controls. In this application, we just need to handle the commands for exiting the application.

Application Document Class:

The document class has two purposes, the first of which is to represent the application’s persistent data(Data that needs to remain after application is exited). The other is to create the application UI instance in which this data (if any) can be manipulated. For applications that have no persistent data, and therefore are not file-based, the document class simply implements the CreateAppUiL() function to return the application’s UI object.

Application Class:

This is the first thing the GUI framework creates. It has the following methods:
CreateDocumentL(): This function creates an object of Document class and returns a pointer to it.
AppDllUid(): This function returns the Application’s Uid.

E32Main()Entrypoint and NewApplication()

A Symbian OS GUI application is a process executable (EXE file) and therefore must contain an E32Main() entrypoint function. For a GUI application this just calls EikStart::RunApplication(), passing it a pointer to a function that returns the application object to run.

Resource Files:

The application resource defines a significant part of how the application will appear and function. The resource file is a text file whose name ends in .rss, and is compiled into a binary form by the SDK’s resource compiler. This compiled version of the resource file is loaded onto the phone along with the application executable and is accessed during application execution.

The RSS_SIGNATURE resource is used to validate the file and must appear, exactly as shown below, as the first resource in every appliation’s resource file.

 RESOURCE RSS_SIGNATURE
  {
  }

TBUF Resource defines the default document name. As a document is not used in the application, it is left blank.
The EIK_APP_INFO Resource defines a Control Button Array(cba) resource that defines the function of the left and right softkeys. We define the cba as "R_AVKON_SOFTKEYS_EXIT". This defines the right softkey as exit and generates the command "EAknSoftkeyBack" when activated which is in turn handled by the Application UI class.

Application Registration Resource File:

GUI applications are EXE files in the sys\bin directory and in order for the device to recognize an executable as a GUI application, and to display them on the desktop for user selection, the application must be registered via a special resource file known as a
registration resource file. The source file names are typically <application name> reg.rss. Walkthrough the reg_rss file for more details.

Project Build Files:

These are the files that define how to build a project:

FirstApp.mmp: It defines what source and resource files should be compiled and what libraries should be used for linking. The locations to search for project-defined and system include files, and source files and locations, are also defined

bld.inf: The file bld.inf points the build tools to the correct project definition
(MMP) file.

Download Source code for this tutorial here.
Go to tutorial 2 now.

Step by step tutorial for your first Symbian Application

An updated version of this post is available here.

Welcome. This post will guide you about C++ programming for the Series 60 v5 platform, based on the Symbian Operating System. I wrote these tutorial along with my colleague Sapan, when we were doing summer internship at IIIT- Hyderabad. We built a simple application named “Yellow Page Application” under guidance of Dr. Rohit Agarwal. The term Yellow Pages refers to a telephone directory of businesses, categorized according to the product or service provided. This application does the work of displaying this information to the user on the go using just his mobile phone. In this way, he can get the information about the business he is looking for in a particular city.This application lists major businesses (Banks, Clinics and Doctors etc.) in 4 major cities of India.

We have divided this tutorial in 5 parts which will guide you How to build a basic Symbian application from scratch. Before going further I suggest you to get familiarize yourself with the application first and read this.

Tutorial Start Page : This part will describe about prerequisite setup needed for building any Symbian Application.

Tutorial 1: This part will tell you about 4 necessary classes that you must define in order to build Symbian Application.

Tutorial 2: This part will show you how to build a dialog box in Symbian Operating System.

Tutorial 3: This part creates forms and provides support for your application.

Tutorial 4: This part focuses on all the code that is required to build this application.

In each part I have provided a link to download source code also. Download the complete source code here.

This tutorials took a long time so if you find any error in this tutorial please feel free to give your suggestions.

Tutorial Start Page

An updated version of this post is available here.

Symbian is a proprietary operating system designed for mobile devices, with associated libraries, user interface, frameworks and reference implementations of common tools, developed by Symbian Ltd. It is a descendant of Psion’s EPOC.

A little history — On 24 June 1998, Symbian Ltd. was formed as a partnership between Ericsson, Nokia, Motorola, and Psion, to exploit the convergence between PDAs and mobile phones. Symbian was previously owned by Nokia (56.3%), Ericsson (15.6%), Sony Ericsson (13.1%), Panasonic (10.5%), and Samsung (4.5%). Ten years later to the day, on 24 June 2008, Nokia announced that they intended to acquire all shares that they did not already own. Subsequently, Nokia opened up the development of Symbian to the broad industry by creating the Symbian Foundation.

In this tutorial,we describe how to get started with Symbian Programming by taking you through the installation steps, and then taking through the design of a sample application. This tutorial assumes that you have worked with C++ before and have a brief knowledge about classes, inheritence etc. If you are facing problems with these topics, please dont start this tutorial before making those concepts clear. This tutorial requires no previous knowledge about Symbian and will be taking you forward from the beginning. The first section in this tutorial describes the installation of the development environment for Symbian Programming and the second part starts from a top down class design for a sample application.

Getting Started: Hardware and SDK Installation

Part 1: The Hardware

The first thing you need is a PC/Monitor/mouse and Keyboard. Almost any machine on market today can be used for development, however some would save you a bit of time:

Don’t pay too much attention to the CPU (just avoid if you can the entry level Celeron and Sempron) but take as much RAM memory as you can. 1GB seems a minimal requirement if you consider doing serious development, a big fast hardisk (Speed is important to reduce compilation times and emulator start time, space is a requirement to handle all your SDKs. As an example, you will need 1GB for the S60 3rd FP1 SDK, 500MB for Carbide.c++, etc…). also avoid Windows Vista for now, the ARM toolchain is not yet compatible with it. If everything is ok on the hardware/operating side, you are almost ready to start.

one last thing to check: make sure you have enough space on your C: drive. This is not an absolute requirement, but if you don’t want to bother mounting virtual drive and editing configuration files again and again, you will need to install everything, the IDE, the SDK(s), your project(s) on C:\ so a minimum of 2GB free space is required before starting installation (and this is a minimum!).

Part 2: The software development toolchain

Now let’s go for a bit of downloading. So download and install: ActivePerl v5.6.1. The latest 5.8 nor 5.10 versions won’t probably work.

 The Carbide.c++ IDE. : Carbide.C++ is a software development tool for C++ development on Symbian OS. It is used to develop phones that use the OS, as well as applications that run on that phone. It is based on Eclipse IDE Platform enhanced with extra plugins to support Symbian OS development. The Express version (which is free) is enough if you are a student or just intend to learn Symbian OS development. The Developer version (or better) is required if you plan to do some commercial development.
To avoid any problem, be sure to install everything on C:\  in their default location.

The Software Development Toolchain: The SDKs

The S60 SDK : The S60 Platform (formerly Series 60 User Interface) is a software platform for mobile phones that runs on Symbian OS. S60 is currently amongst the leading smartphone platforms in the world. It is owned by Nokia. S60 is licensed by Nokia to other manufacturers including Lenovo, LG Electronics, Panasonic and Samsung.

Download the S60 SDK. Install the SDK in its default directory and on the same drive as Carbide.c++ At the end of the installation, you will be prompted to install the CSL Arm Toolchain if it is not already installed on your machine. Make sure you install it or you won’t be able to compile for the phone target.

Reboot your machine

The Software Development Toolchain: Checking the installation

At the command prompt type ‘epoc’. The S60 emulator window should come up.

The Software Development Toolchain: Reference Book :

Developing Software for Symbian OS by Steve Babin.

The Software Development Toolchain: Getting Help

You can refer to following links for help in Symbian Programming

• Nokia Forums
• NewLC
• Symbian Developers

For more help, you can look up the examples provided with Carbide.C++ and the SDK. Here are the instructions to running the Hello World example in Carbide.C++:

• Run Carbide.C++
• Goto File -> Import



• Select Symbian OS -> Symbian OS Build.inf File and click on Next.Then browse to the directory where you installed Symbian SDK, and look for Examples in the subdirectories. The default location should be : C:\Symbian\9.2\S60_3rd_FP1_3\Examples. Once there, browse through Basics -> HelloWorld. Select the bld.inf file and proceed further.



• Proceed through the next screens checking all the check boxes and then Run the Project by Pressing Ctrl+F11 or by selecting Run -> Run.