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.
[cpp] RESOURCE RSS_SIGNATURE { }[/cpp]
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 sysbin 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.