Nokia N97 SDK
Example Applications Guide

GUI/Engine Split Example

1 About this Example
2. Architecture
3. Design and Implementation


1 About this Example

The GUI/Engine example demonstrates how to split an application into two components, an 'engine' dll and a GUI application. This configuration separates the GUI parts of an application from the engine data or 'model' that the application uses. This has several advantages:

This example allows the user to place two types of shape onto the display, either a circle or a rectangle. These shapes are placed onto the display using a cursor. This is moved using the direction keys. A shape is placed at the cursor position when the directional rocker is pressed.

As well as demonstrating the GUI/Engine split, this example also shows how to save and restore model data. When the application exits, the positions of all the shapes are saved to the file system. This information is then restored when the application is re-started.

This example documentation starts by explaining how to use the application. Next it presents an overview of the design and major use case scenarios. Finally, it explores the major use case scenarios in more detail.

1.1 APIs demonstrated


1.2 Prerequisites

The example uses Symbian OS Store Streams. The reader is recommended to read the following topics from the Symbian OS SDK documentation before proceeding:

Building and Using

To build the Gui/Engine example application, go to the GuiEngine/group directory and build the application.

The Gui/Engine application consists of two modules, which should be built in the following order:

  1. engine
  2. gui

The definition for the whole application can be found in the bld.inf file in the group subdirectory of the applications main directory.


2. Architecture

This example exists as a complete application and has the standard Symbian OS application architecture employing the Application, Document, UI, and View classes. The reader should be familiar with this architecture before proceeding.

3. Design and Implementation

The application consists of two main components:

The GUI component exists as a standard Symbian OS Application and as such this architecture is not described further in this document. The Engine component exists as a Shared Library DLL providing a fixed API that can be used by more than one program.

To illustrate the Gui/Engine split, as well as saving and restoring data, consider the following scenarios where the end user:

3.2 Design Overview section provides a design overview of this example.

3.3 Invoking the application the application section through 3.6 Exiting the application section describe in detail the processes involved in the above scenarios. These are: invoking the application, drawing a shape, clearing the canvas and exiting the application, respectively.

3.1 Capabilities

The application does not require any capabilities. The program capabilities are defined in mmp-files as CAPABILITY NONE.

3.2 Design Overview

The following component diagram illustrates the split of classes over the GUI and Engine components, and their inter-relationships:
component.jpg

As mentioned previously, the GUI component implements the standard set of Symbian OS application classes. The Engine component provides a managed list of shapes, CShapeListManager, to the GUI. This provides functions to manipulate the contents of the list, and also externalise and internalise the list contents. Items in the list are of an abstract base class TShape. Concrete implementations are provided by TCircle and TRectangle.

The following class diagram shows this structure:

class.jpg

Since the Engine component exists as a DLL, its API functions must be exported. Exported functions are marked in their header using IMPORT_C (see CShapeListManager for an example). In the corresponding implementation, the functions are marked with EXPORT_C, as in CShapeListManager::AddShapeL.

3.3 Invoking the application

Since this is a file-based application, it is necessary to have a file associated with the application. This is used to save and restore data. This application uses the 'default document file' and is created (if it doesn't already exist) by the framework, at application start-up. The filename is specified in the application's .rss file, and must be the second resource specified in the file. For this example, the file is specified as follows:
 RESOURCE TBUF { buf="GuiEngineState"; }

A CStreamStore representing this file is passed to the application's document class, during invocation. A CStreamDictionary is also provided to enable the application to identify individual streams from the stream store. In this application, the stream store holds two streams. These are:

The following diagram shows the sequence involved in restoring these streams when the user invokes the application:

invocation.jpg

  1. The framework calls the document's RestoreL function when the application is started. A CStreamStore object representing the default document file, is supplied along with its root stream dictionary.
  2. The safest approach to reading in the contents of the model is to:
  3. This example stores two streams in the default application file. One for the model, and one for the GUI state. Here, the model's stream identifier is returned by calling CStreamDictionary::At, and providing a UID. This application uses the application UID for the model, and a further UID for the GUI state.
  4. The model's RestoreL function is now called, passing it the file and stream identifier.
  5. The shape list is first cleared,
  6. then a stream is created and
  7. opened using the supplied file and stream identifier. InternalizeL is now called, passing the newly created stream. InternalizeL is the standard Symbian OS function that should be implemented for 'store aware' classes in order to read the class state from a stream.
  8. The number of shapes present in the stream is read, and then 4 steps are repeated for each.
  9. The shape type is required before a shape can be created. Each shape in the file is prepended by a descriptor indicating the shape type. This is now read, and
  10. an appropriate shape instantiated.
  11. This shape's InternalizeL function can now be called to populate its member variables. This diagram shows a TCircle being created.
  12. The shape is added to the list using the RPointerArray::Append function.
  13. Control now returns to the document's RestoreL function, where the old model is deleted, and replaced by the new one. The GUI state is now recovered. Calling CStreamDictionary::At with the GUI UID generates a stream identifier which is now passed to the AppUi's RestoreL function. This now recovers the selected shape type from its corresponding stream. This is not pictured, since it is a similar process to that described above.
  14. The framework now calls the AppUi's HandleModelChangeL function which commands the view to redraw. The redrawing of the display is described in the Drawing a shape section. The filename in the task list is now updated to show the current file.

3.4 Drawing a shape

The following diagram shows the sequence involved when the user places a shape on the canvas:
drawshape.jpg

  1. The framework notifies the application that an event has occurred through the view's OfferKeyEventL function. The event type is checked for an EStdKeyDevice3 event before continuing with this sequence. The EStdKeyDevice3 event signifies that the directional rocker has been pressed.
  2. The currently selected shape type is examined, and a new shape of that type is created using the current cursor position.
  3. The newly created shape is passed to the model, using the AddShapeL function.
  4. The model stores the shape by calling RPointerArray::Append. The model now has the responsibility for deleting the shape when it is no longer required.
  5. The view now calls its inherited DrawNow function, which calls the view's Draw function.
  6. In the Draw function, the canvas is cleared and set up ready for redrawing shapes (not shown on diagram).
  7. CShapeListManager::GetNextShape is called to return the next shape to be drawn.
  8. The view then calls TCircle::Draw to render the shape.

3.5 Clearing the canvas

The following diagram shows the sequence involved when the user selects Clear from the Options menu:
clearcanvas.jpg

  1. When the user selects Clear, the UI's HandleCommandL function is called by the framework.
  2. This, in turn, calls the view's Clear function.
  3. The view calls the model's Clear function, which...
  4. ... removes and destroys the shapes in the store by calling RPointerArray::ResetAndDestroy.
  5. The view now calls its inherited DrawNow function, which calls the view's Draw function.
  6. In the Draw function, the canvas is cleared and set up ready for redrawing the shapes (not shown on diagram).
  7. GetNextShape will return NULL here, since the model has just been cleared, so no shapes will be drawn.

3.6 Exiting the application

The following diagram shows the sequence involved when the user selects Exit from the Options menu:
exitapplication.jpg

  1. When the user presses Exit, the UI's HandleCommandL function is called by the framework.
  2. This, in turn, calls its inherited SaveL function.
  3. The SaveL calls the document's StoreL function, passing it the default document file and root stream dictionary.
  4. The document now calls CShapeListManager::StoreL causing the model to store its state. This is described in the CShapeListManager::StoreL section.
  5. The stream identifier, returned by the previous operation, is now written to the root stream dictionary using CStreamDictionary::AssignL.
  6. The UI now calls CGuiEngineAppUi::StoreL to store its state. This follows a similar pattern to step 4; however, only the selected shape identifier is written to the file.
  7. The stream identifier, returned by the previous operation, is now written to the root stream dictionary using CStreamDictionary::AssignL.

3.6.1 CShapeListManager::StoreL

The following diagram shows the sequence involved in the CShapeListManager::StoreL function (continued from the previous diagram):
man_storel.jpg

  1. StoreL is called, and passed a CStreamStore object representing the default document file.
  2. A stream is created and
  3. prepared for writing by calling RStoreStream::CreateLC. This call must be matched by a call to CommitL before the RStoreStream object is deleted.
  4. ExternalizeL is now called, and is passed the stream as a parameter. ExternalizeL is the standard Symbian OS function that should be implemented for 'store aware' classes in order to write the class state to a stream.
  5. The number of shapes in the model is determined using RPointerArray::Count,
  6. and this is written to the stream using RStoreStream::WriteInt16L.
  7. The shape list is now iterated through, and each shape instructed to externalise itself.
  8. RStoreStream::CommitL can now be called to ensure that any buffered data is written to the stream.

© Nokia 2009

Back to top