S60 3rd Edition SDK for Symbian OS Example Applications Guide |
1. About this Example
2. Prerequisites
3. Design and Implementation
4. Class Hierarchy
1 The application is launched, the framework loads the application EXE and the E32Main method is called.
2 The framework calls the function NewApplication. This creates an instance of the HelloWorldApplication class, and returns a pointer to it. The framework subsequently uses this pointer to complete construction of the application.
3 The framework calls AppDllUid to get the UID of this particular application. The UID is used to, for example, see if an instance of the application is already running, so than the existing instance can be switched to, rather than a new instance created.
4 The framework calls CreateDocumentL on the CHelloWorldApplication object. This creates an instance of the application Document and returns a pointer to it. This allows the framework to call certain Document methods directly. The Document object is constructed using the Symbian OS construction sequence, using the Document object's static method NewL.
5 The framework calls AppDllUid, to see if it is necessary to load a file from the filing system. The HelloWorld example does not need to persist any information, and so does not have a file associated with it.
6 The framework calls the Document object's CreateAppUiL method. This creates the AppUI object and returns a pointer to it.
7 The framework completes the construction of the AppUI object by calling its ConstructL method. The fact the framework calls the AppUi object's constructor and ConstructL separately allows the framework to complete any necessary initialisation before construction of the AppUI object is completed.
8 The ConstructL method first calls the base class's BaseConstructL. This performs such tasks as reading the resource file associated with an application.
9 The AppUi calls NewL to create the AppView object, using Symbian two phase construction.
10 The framework calls the Draw method is called by the framework to draw the view. In this case it will cause a blank screen to be displayed.
11 Whenever the user selects a menu option, HandleCommandL is called by the framework and is passed an argument, aCommand, that indicates the command the user selected. The AppUI can then perform whatever actions are required for that particular menu option:
11 a) In case of "Hello", it creates an Information note with the text "Hello World" in it, and displays it.
11 b) In case of "Hello from file", it reads text from Hello.txt -file and displays it in Information note.
The framework calls the function that is exported by the application at ordinal 1 in the DLL. This means that the first function defined in the DEF file for an application must be the NewApplication method. By default, the tool chain automatically ensures that this is the case for a Symbian OS application.
Note that this construction does not use the usual Symbian OS new (ELeave) method, but the C++ style new method. This is because a TRAP harness has not been created for the application at this point. If the system is unable to allocate memory for a new instance of the application, the returned instance pointer will be NULL. The framework checks for, and copes with, this possibility.
The programmer cannot call the Draw method directly, as it requires the system's graphics context to be activated before it is called. Instead, if the programmer wishes to have the screen redrawn, they should call the DrawNow method.
Note that the Draw function cannot leave. This is because the function may be called directly by the framework, and the framework would not know how to handle any errors that might occur. Instead the Draw function must TRAP and handle any errors that might occur.
An HBufC descriptor is created from the RFileReadStream object.
The descriptor reads from the stream both the length of the data followed by the data. After this descriptor has been read the stream will be positioned at the beginning of the data.
Information note is shown from descriptor
If the view is on the control stack, then whenever the user presses a key the OfferKeyEventL method is called. This has arguments that indicate the type of key event (key down, key press or key up) as well as the code of the key pressed.
When the AppUi object is destroyed, the AppView must be removed from the stack. This is done by calling RemoveFromStack in the AppUi object's destructor.
© Nokia 2006 |