S60 3rd Edition SDK for Symbian OS
Example Applications Guide

Landmarks Reference Application Example

1. About this Example
2. Prerequisites
3. Application Output
4. Design and Implementation
5. Error Situations
6. Summary
7. Class Hierarchy

1. About this Example

This tutorial explains the Landmarks reference application, demonstrating how landmarks and landmark categories can be managed. The basic Landmarks API and Landmarks Search API are utilized for this demonstration. In particular, the following operations are exercised:

Creating landmarks Removing landmarks Reading landmarks completely Reading landmarks partially Editing landmarks Updating a landmark to the current location Sorting landmarks Filtering out a subset of landmarks Creating categories Removing categories Reading categories Renaming categories Sorting categories Filtering out a subset of categories Initializing the default landmark database Observing and handling database events Visualizing the progress of an asynchronous landmark function in a progress dialog

The structure of the tutorial is based on the architecture of the Landmark reference application.

2. Prerequisites

This example is a view-based application that makes use of the standard Symbian OS application framework comprising of the Application, Document, UI, and View classes. It also uses standard UI components, such as lists, dialogs and editors, which are described in other SDK examples (see <http://www.forum.nokia.com/>). Further, active objects are used to realize the execution of asynchronous functions and Location Acquisition API is used for acquiring locations. The reader should be familiar with active objects and Location Acquisition API.

2.1 Platform Security aspects

The Landmarks reference application requires the Location, ReadUserData and WriteUserData capabilities.

3. Application Output

3.1 Initializing a database

When started for the very first time, the Landmarks reference application will create and initialize the default landmark database if necessary. This will be indicated by a progress bar monitoring the initialization (see figure 1).

Figure 1 Initializing a database

3.2 Landmarks view

When the Landmarks reference application has been launched, it displays the Landmarks view as default. The Landmarks view consists of a list box and a search field. If the database does not contain any landmarks, the list box will be empty (see figure 2). Otherwise, the existing landmarks will be sorted in alphabetical order and displayed in the list box..

Figure 2 Empty Landmarks view

3.3 Creating landmarks

To create a new landmark, select the New landmark item and then the sub menu item Blank from the Options menu. A landmark editor will be launched where you can edit some landmark fields. The command button Done finishes the landmark editing and saves the changes. The created landmark will be stored in the database resulting in a database event that is distributed to the Landmarks reference application. The Landmarks reference application will handle the event by refreshing its list of sorted landmarks and the created landmark will appear in the list.

Figure 3 Creating a landmark

Another way to create a new landmark is to select the New landmark item and then the sub menu item Current location in the Options menu. A location is then acquired before the landmark editor is launched. The editor's location fields will be automatically configured with data based on the location that was acquired. If no location was acquired, the fields will be blank and the reason to the acquisition failure will be displayed in an Information note.

Figure 4 Creating a landmark by selecting Current location from the Options menu

3.4 Editing landmarks

An already existing landmark can be viewed and/or edited by selecting the item Open from the Options menu. First, the Landmark Information view is opened. In this mode, only the defined fields are displayed. By pressing the left softkey Edit, the Landmark Edit dialog is opened and all the editable fields are displayed.

Figure 5 Editing a landmark

When editing a landmark, the location fields Latitude, Longitude, Altitude, Horizontal accuracy, and Vertical accuracy can be manually edited or automatically updated by selecting the item Fetch current location from the Options menu. A location is then acquired and the location fields in the editor are updated according to the location that was retrieved. If the location retrieval failed for some reason, the location fields will not be modified but the reason to the acquisition failure will be displayed in an Information note.

Figure 6 Fetch current location

A landmark can belong to one or several landmark categories. When editing the Categories field, a markable list of the categories can be launched by selecting the menu item Edit categories. In the list, categories can be added/removed from a landmark by using the Selection key and the Arrow up and Arrow down keys. The left softkey Ok finishes selecting categories. Pressing the softkey Done back in the editor dialog opens a query asking whether to save the changes. If No is pressed, then no changes are applied to the landmark.

Figure 7 Editing categories

3.5 Filtering landmarks

As the number of landmarks grows, browsing for a specific landmark becomes tedious. In this case, filtering out those landmarks whose name contains a certain letter or phrase is helpful. By feeding the search field with text, the list of landmarks will be filtered to display only those landmarks whose name contains the supplied phrase.

Figure 8 Filtering landmarks

This procedure is described in detail in Sections 4.2.2 and 4.2.13.

3.6 Deleting landmarks

To delete a landmark, select the Delete item from the Options menu and accept the query dialog that is launched. The Landmarks Framework will notify the application that a specific landmark has been removed from the database and the landmark will disappear from the Landmarks view

Figure 9 Deleting a landmark

3.7 Categories view

There is another view, the Landmark Categories view. This view is similar to the Landmarks view as it contains a listbox and a search field, but this view displays the landmark categories. When the database was initialized, global categories were created and they can be viewed by switching to the Categories view. The views can be switched by using the Arrow left and Arrow right keys

Figure 10 Categories view

3.8 Creating categories

It is possible to define new categories if the global ones are not sufficient. A new category is defined by selecting the item New Category from the Options menu. After the selection, a dialog is launched where the user can define a name for the category. If the dialog is accepted, the category is stored in the database resulting in a database event that is distributed to the application. The application will handle the event by refreshing its list of sorted categories.

Figure 11 Creating a category

3.9 Renaming categories

A non-global category can be renamed after it has been created. This is analogous to creating a new category and it is done by selecting the Rename item from the Options menu.

Figure 12 Renaming a category

3.10 Deleting categories

A non-global category can also be deleted. This is done by selecting the Delete item from the Options menu and accepting the subsequent query dialog.

Figure 13 Deleting a category

3.11 Filtering categories

It is possible to filter categories. The filtering of categories follows the same procedure as when filtering landmarks (see Section 3.1.5).

4. Design and Implementation

This chapter starts by giving an overview of some of the algorithms used in this application. It then details the design of each of the two application components: the application UI and the application engine. Finally, the realization of the most important use cases is visualized as sequence diagrams

4.1 Design

Figure 14 shows the class diagram for the Landmarks reference application.

The figure shows that the application can be logically divided into two components: the application UI and the application engine. The application UI is dependent on the application engine that is in turn dependent on the Landmarks APIs. Throughout this document, all the classes that are a part of Landmarks API are indicated with blue color and the classes that are a part of Landmarks Search API are indicated with red color.

Figure 14 Landmarks reference application architecture

4.1.1 Application UI

The application UI is responsible for displaying data for the user and catching and reacting to user activity. It uses the application engine to execute commands initiated by the user. Figure 15 below illustrates the most important classes of the application UI. The figure is followed by a brief description of each class.

Figure 15 Application UI class diagram

Class
Description

MLandmarksDbObserver
This interface should be implemented by classes that are interested in handling database events.

MLandmarksOperationObserver
Many operations offered by the application engine are asynchronous. Classes in the application UI that invoke these functions need to be notified when these asynchronous operations are completed. MLandmarksOperationObserver is a generic callback interface implemented by such classes.

CLandmarksAppUi
CLandmarksAppUi inherits from CAknViewAppUi, which indicates that this is a view-based application. It creates the two application views for displaying landmarks and categories as well as the application engine. It also initializes the landmarks database if necessary. For this reason, it implements the MLandmarksOperationObserver interface to be notified when initialization is completed. It takes care of application global events such as exiting the application and switching views.

CLandmarksView
This is the view displaying landmarks. It has CLandmarksContainer that is responsible for the graphical components of the view. It handles commands from the menu items such as deleting landmarks, editing landmarks, creating blank landmarks and creating landmarks based on the current location. To be able to fetch the current location, it implements the MLandmarksOperationObserver interface that is notified when an asynchronous location acquisition request is completed.

CLandmarksContainer
CLandmarksContainer contains a listbox displaying landmark names and a search field for filtering the displayed landmarks. The listbox is dependent on the search field and the responsibility of this class is to update the listbox and the listbox model with new landmarks whenever the search field has been updated or an event from the database has been reported. Since filtering is an asynchronous process, it implements MLandmarksOperationObserver to be notified about the progress of the filter process. It also implements the MLandmarksDbObserver interface to be notified about database events.

CLandmarksModel
This is the data model for the listbox with landmarks. The model consists of a list of the landmark IDs, a list of the landmark icons and a list of the landmark names.

CLandmarksCategoriesView
This is the view displaying categories. It has CLandmarksCategoriesContainer that is responsible for the graphical components of the view. It handles commands from the menu items such as deleting, renaming and creating categories.

CLandmarksCategoriesContainer
CLandmarksCategoriesContainer contains a listbox displaying category names and a search field for filtering the displayed categories. The listbox is dependent on the search field and the responsibility of this class is to update the listbox and the listbox model with new categories whenever the search field has been updated or an event from the database has been reported. Since filtering is an asynchronous process, it implements MLandmarksOperationObserver to be notified about the progress of the filtering process. It also implements the MLandmarksDbObserver interface to be notified about database events.

CLandmarksCategoriesModel
This is the data model for the listbox with categories. The model consists of a list of the category IDs, a list of the category icons and a list of the category names.

CLandmarksContainerBase
This is an abstract class defining the look and behavior of the view containers. It takes care of creating and destroying the graphical components of a view container.

CLandmarksInfoView
This is the view displaying a landmark's information. It does not show empty fields. If 'Edit' left softkey is pressed it opens editor dialog using CLandmarksEditDialog.

CLandmarksInfoContainer
This container controls a listbox, which displays landmark's information. It is used by CLandmarkInfoView and it uses CLandmarksInfoModel.
This class is another candidate to be a listener of MLandmarksDbObserver. If some changes happen to the landmark being shown, the view can be updated. However, for simplicity's sake, this is not implemented.

CLandmarksInfoModel
This is the data model for the landmark's information view. It provides methods for building the container's listbox items.

CLandmarksEditDialog
This class is a dialog for editing a specific landmark. It allows the user to update a landmark to the current location. For this reason, it implements MLandmarksOperationObserver to be notified when a location retrieval is completed. It is also used when a new landmark is being created, in which case an empty landmark is edited.

CLandmarksCategoriesDialog
This class is not shown in figure 15 for simplicity. It is used by CLandmarksEditDialog to allow the changing of landmark categories. It is derived from the CAknMarkableListDialog class.

CLandmarksPositionRequest
This class is inherits from CActive and is responsible for acquiring the current location. Location Acquisition API is used for this purpose. It first tries to utilize the default positioning module. If this fails, it tries to fetch the last known location. If that also fails, no location is returned. During the location retrieval, a Wait note is displayed where the user can cancel the operation.

4.1.2 Application Engine

The application engine is a UI-independent component responsible for executing the commands captured by the application UI. It uses Landmarks API and Landmarks Search API in the Landmarks Framework to accommodate this. Figure 16 below illustrates the classes of the application engine. The figure is followed by a brief description of each class.

Figure 16 Application engine class diagram

Class
Description

CLandmarksApplicationEngine
This class provides the interface to the application engine. It encapsulates the whole engine and can be seen as a wrapper since it contains no complex logic but forwards most requests to the appropriate engine class.

CLandmarksDbEventHandler
Inside the application engine, there is only one instance of the CPosLandmarkDatabase class. Each instance of CPosLandmarkDatabase accepts only one database observer. The CLandmarksDbEventHandler instance is the object that is notified when an event has occurred. The task for this object is to allow several other objects to register for database events and to notify them whenever such an event occurs.

CLandmarksEngineBase
This is an abstract base class for view engines. View engines are active objects, which explains why this class inherits from CActive. It has a CLandmarksLmOpWrapper instance to monitor the execution progress of asynchronous Landmarks Framework functions. It contains a CPosLandmarkSearch instance to be able to search for landmarks and categories and it handles setting the priority of a view engine. A view engine should have low priority when its corresponding view is deactivated and normal priority when its view is activated.

CLandmarksEngine
This view engine serves the Landmarks view. All the functions this view needs to execute are implemented by this class, e.g. filtering landmarks, reading landmarks, removing landmarks, etc.

CLandmarksCategoriesEngine
This view engine serves the Categories view. All the functions this view needs to execute are implemented by this class, e.g. filtering categories, creating categories, committing categories, etc.

CLandmarksLmOpWrapper
As stated before, several time-consuming operations in the Landmarks Framework return a handle to themselves when executed. Such a handle is an instance of the CPosLmOperation class and makes it possible to execute the operation incrementally. CPosLmOpWrapper is an active object that wraps a CPosLmOperation instance. Its task is to take care of the incremental execution.

4.2 Implementation

4.2.1 Algorithms and the usage of asynchronous functions

One key concept when designing one-threaded graphical Symbian applications is to avoid synchronous time-consuming methods. Instead, asynchronous functions that execute time-consuming operations incrementally, i.e. in several small steps, should be used. This gives the UI a chance to respond to user activity whenever needed. The Landmarks Framework is designed to accommodate this. In most cases, a handle is returned to a time-consuming function when it is started. With such a handle, it is possible to execute those operations asynchronously and incrementally. When filtering landmarks or categories, searching, sorting and reading is needed. These operations are time-consuming, especially when a large number of items are involved. This fact has a great impact on the design of the Landmarks reference application.

4.2.2 Filtering landmarks

When filtering landmarks, the following criteria must be considered:

A filter change is caught by the application UI that is the initiator of a filter operation Filtering can be split into two sub-operations: searching/sorting and reading. Filtering must be done incrementally in order to keep the UI ready to respond to user activity. The filtering operation must be carried out by active objects since the Landmarks Framework requires this. In order to update the UI as fast as possible, all the landmarks that match a specific filter cannot be read before updating the UI. Since reading is done incrementally, it is better if the landmarks read so far are displayed. As the number of read landmarks increases, the list is dynamically updated in the background. Only the name field and the icon field of a landmark need to be read. This implies that it is sufficient to read landmarks partially.

All these criteria end up in the following filtering algorithm:

Figure 17 Filtering landmarks state chart

1. The initial state is that the list of landmarks is updated.

2. The list needs to be updated either because the filter has changed or because a database event has been reported.

3. The application UI initiates the application engine to start a search and sort operation. This operation is done asynchronously and incrementally.

4. The search/sort operation may be cancelled for some reason (for example, the filter might have changed) and the application UI cancels the search operation in the application engine and returns to the initial state to wait for a new event.

5. The incremental search/sort operation is not ready and another step of the incremental search has to be executed.

6. The search/sort operation is completed and the reading of the found landmarks can be started.

7. The application UI is notified about the search result and the list displaying the old landmarks is emptied.

8. If no items are found, the application UI returns to the initial state.

9. If there are any landmarks matching the filter, the application UI initiates the application engine to start a landmark read operation.

10. Reading landmarks is done asynchronously, incrementally and partially. Reading landmarks partially means that a subset of all the landmark attributes is read. In this case, only the landmark name and the landmark icon are read.

11. The read operation may also be cancelled for some reason (for example, the filter might have changed) and the application UI cancels the operation in the application engine and returns to the initial state to wait for a new event.

12. If less than one page of landmarks has been read, the reading of landmarks continues incrementally.

13. If a complete page of landmarks has been read, these landmarks can be displayed before reading the next page. This decreases the response time considerably.

14. The application UI is notified that a new page of landmarks has been successfully read and the page is appended to the list.

15. If there are more landmarks to be read, reading is continued.

16. If there are no more landmarks to read, the application UI returns to the initial state.

4.2.3 Filtering categories

Filtering categories is very similar to filtering landmarks. In fact, step 1-9 in figure 16 and figure 17 are identical. The only difference is that the Landmarks Framework allows neither partial nor incremental reading of categories. This results in the algorithm illustrated in figure 17.

Figure 18 Filtering categories state chart

4.2.4 Acquiring the current location

Acquiring the current location does not involve the Landmarks Framework at all. Instead, Location Acquisition API is used. Figure 18 describes the algorithm used by the Landmarks reference application for acquiring the current location.

Figure 18 Acquiring the current location state chart

Transition
Description

1
When acquiring a location, first the default positioning module is used.

2
If the default positioning module succeeds, the location is accepted.

3
If the request for the current location is cancelled, no location is acquired.

4
If the default positioning module fails to acquire the location, an attempt to acquire the last known location is made.

5
If acquiring the last known location succeeds, the location is accepted.

6-7
If acquiring the last known location fails for some reason, no location is acquired.

4.2.5 Application startup

When the application is started, most of the classes are instantiated and certain other important things take place: the database is initialized, partial read parameters are set and database observers are registered. Figure 19 describes this briefly.

Figure 19 Application startup

Message
Description

1-3
Before creating any views, the CLandmarksAppUi instance creates the application engine.

4-5
When the Landmarks view engine is created, partial read parameters are set.

6
The Categories view engine is created.

7-8
Before the database can be utilized by any view, it must be initialized. This is done asynchronously.

9-11
When the database has been initialized, it is safe to create and activate the views.
Note: CLandmarksInfoView is also created at this stage.

12-13
When the Landmarks view is activated for the first, time its container is created. During the construction, the container registers itself as an observer of database events. This procedure is repeated by the Categories view when it is activated for the first time.

14
The last step of the initialization is to start populating the listbox with landmarks.

4.2.6 Setting the partial read parameters

During the application startup, the partial read parameters are set. The partial read parameters are used when reading landmarks during filtering. Figure 20 shows how this is done in detail..

Figure 20 Setting the partial read parameters

Message
Description

1-3
During the construction of CLandmarksEngine, a new CPosLmPartialReadParameters instance is created.

4
The attributes to set are landmark name and landmark icon as this is the only information displayed in the listbox. Note that these partial read parameters have impact when reading landmarks partially. When reading a landmark completely, they have no impact at all.

5
The new partial read parameters are set to the database.

4.2.7 Initializing the database

During the application startup, the database is initialized if necessary. Figure 21 shows how this is done in detail.

Figure 21 Initializing the database

Message
Description

1-4
During the construction of CLandmarksAppUi, it tries to start initializing the database if needed.

5-6
If the database needs to be initialized, a database initialization operation is prepared and an operation handle is returned.

7
The incremental initialization is started by executing the next step.

8-9
If the database needs to be initialized, CLandmarksAppUi creates and launches a progress dialog. Otherwise, no action is taken since the database is already prepared for use.

10-12
The first incremental step of the initialization process is completed and the CLandmarksAppUi instance is notified. It handles this event by updating the progress bar according to the progress status of the operation.

13
The next step of the initialization is executed.

14-16
Step 10-13 are repeated until the initialization process is totally completed. Finally, the progress dialog is dismissed.

4.2.8 Registering a database observer and handling database events

During the application startup, the landmarks container is registered as a database observer in order to keep its data up-to-date. Whenever a landmark or a category is updated, removed or created, an event is generated to all registered objects.

Figure 22 Database events

Message
Description

1-2
During the application startup, the view containers are registered as database observers to the application engine.

3-4
If there is no database event handler, it is dynamically created. During the construction, it starts to listen for database events.

5-6
Whenever an event is generated, the database event handler catches and distributes the event to all registered observers, i.e. the view containers.

7
The view containers investigate the event and start to refresh their contents if necessary.

8
When the database event handler has distributed the event to all registered observers, it immediately starts listening for new events.

4.2.9 Compacting the database

Whenever a landmark or a category is added, updated or removed, the contents of the database are updated. New data is added to the database, but obsolete data is not automatically removed. If the database is never compacted, its size will grow continuously. It is recommended that clients of the Landmarks Framework compact the database when the level of valid information in the database is too low. The Landmarks reference application checks this level before writing anything to the database. Figure 23 describes how this is carried out.

Figure 23 Database events

Message
Description

1-2
A write operation is going to be performed and the size of the database is retrieved.

3-4
The usage of the database is investigated and if the database usage is below a certain level, a compact operation is requested.

5
The compact operation can be executed asynchronously or synchronously. In this case, it is executed synchronously and it is automatically deleted by the framework.

4.2.10 Adding a landmark

There are two ways of creating a new landmark: either a landmark based on the current location is created or a blank one is created. Figure 24 describes the creation of a new landmark based on the current location. When creating a blank landmark, the only difference is that steps 2, 3 and 6 in Figure 24 are omitted.

Figure 24 Adding a landmark

Message
Description

1-3
The user has activated the menu command for adding a landmark. The framework generates an event that is handled by the Landmarks view. A new landmark object instance is created in memory.

4-6
The edit dialog is created and started.

7
The current location is acquired if the user creates a landmark based on the current location and the blank landmark is updated with this location. If no location was acquired, the landmark remains blank.

8-12
The user edits the landmark’s fields and then accepts the changes. The data from the input fields is saved to the landmark.

13-14
The landmark is stored in the database.

15
Since a write operation has taken place in the database, the level of obsolete contents is checked and the database is compacted if necessary.

4.2.11 Acquiring the current location

The algorithm for acquiring the current location is described in detail in Section 4.2.4. Figure 25 describes the special case when the default positioning module fails to retrieve a location but the last known location is successfully acquired. In this diagram, a new landmark is to be created. The sequence is, however, identical when updating the location of a landmark to the current location during editing. The CLandmarksView object can be replaced with a CLandmarksEditDialog object.

Figure 25 Acquiring the current locationk

Message
Description

1
The user has activated the menu command for adding a landmark based on the current location. The framework generates an event that is handled by the Landmarks view.

2-4
A request is made to acquire the current location. A Wait note is created and launched.

5-7
If not already initialized, a connection is established with Location Server, a sub-session to the default positioning module is opened and this application is set as the location requestor.

8
The default positioning module is requested to retrieve a location.

9-10
The default positioning module completes the request and the status is checked. If the request was not successful, another trial is made to acquire the last known location.

11-12
The request for the last known location is completed and the status is checked. The Wait note is dismissed.

13
The caller that requested the current location is notified with the status of the request.

4.2.12 Deleting a landmark

Deleting a landmark is straightforward. The name of the landmark to be deleted is read and displayed in a query dialog. If the query is accepted, the landmark is removed.

Figure 26 Deleting a landmark

Message
Description

1
The user has activated the menu command for deleting a landmark. The framework generates an event that is handled by the Landmarks view.

2-3
The ID of the selected landmark is fetched from the listbox model.

4-6
The selected landmark is read and its name is extracted. A query dialog is launched asking the user to confirm if the landmark should be deleted.

7-8
If the query is accepted, the landmark is removed from the database.

9
Since a write operation has taken place in the database, the level of obsolete contents must be checked. If necessary, the database should be compacted to prevent unrestrained growth.

4.2.13 Filtering landmarks

The algorithm for filtering landmarks is described in detail in Section 4.2.2. Figure 27 shows how this algorithm is realized. In the middle of the diagram, a blue dashed horizontal line indicates when the search/sort phase is completed and the reading phase is started.

Figure 27 Filtering landmarks

Message
Description

1-2
The user has updated the filter in the search field of the Landmarks view. Since CLandmarksContainer is observing the search field, it is notified by the framework. The container handles this event by initiating a new landmark search operation with the current filter.

3-4
The application engine prepares the search operation by constructing the search criteria; only those landmarks whose name contains the filter will be qualified as matches.

5-6
The search/sort operation is created. Note the second parameter indicating that the found matches should be sorted by name in ascending order. Since searching is a heavy operation, an operation handle is returned.

7
The first step of the search/sort operation is executed.

8-9
The first step of the search/sort operation is completed and the next step is started if the operation was not fully completed.

10-15
The last step of the search/sort operation is completed and the matches are retrieved. First an iterator is retrieved, and from this iterator, an array of landmark ids is fetched. The container that initiated the search operation is notified that the sorted matches can be fetched.

16-18
The observer fetches the filtered landmarks and initiates a read operation.

19-21
One page of landmarks is prepared to be partially read. Only the name and the icon of the landmarks will be read. The first incremental step of reading the page is started.

22-23
The first incremental step of reading a page of landmarks is completed. If all the landmarks in the page were not read, the next step of the read operation is executed.

24-29
When the page has been completely read, the container that initiated the read operation is notified. The container fetches the landmarks and updates its listbox of landmarks by appending the current page to it.

30-32
The next page of landmarks is prepared to be read and the procedure of reading a page of landmarks is repeated.

33-34
When there are no more landmarks to read, the container is notified that the read operation is ready.

Another method to filter landmarks is to use the CPosLmDisplayData class from Landmarks Search API along with the CPosLandmarksSearch class. This approach allows the receiving of a landmark's data already during the search operation and avoiding the additional step of reading landmarks.

4.2.14 Renaming a category

This section describes the operation of renaming a category. The creation and deletion of a category are very similar to this operation.

Figure 28 Renaming a category

Message
Description

1
The user has activated the menu command for renaming a category. The framework generates an event that is handled by the Categories view.

2-6
The ID of the selected category is fetched from the listbox model.

7-10
A request is sent to the application engine to read the selected category from the database. The category is read and returned.

11
The name of the category is extracted and a text query editor is launched and initialized with the category name.

12
When the name has been edited and the dialog dismissed, the category is updated with the new name.

13-14
The category is committed to the database.

15
Since a write operation has taken place in the database, the level of obsolete contents must be checked. If necessary, the database should be compacted to prevent unrestrained growth.

5. Error Situations

Whenever a location acquisition or landmark manipulating error occurs, an Information note is shown to the user. The Landmarks reference application does not allow storing empty landmarks and it also handles situations when invalid landmark data is entered by showing an error message to the user.

6. Summary

The Landmarks reference application demonstrates how to manage and display landmarks and landmark categories using the Landmarks Framework. The application is split into two components: an application UI and an application engine, the latter communicating directly with the Landmarks Framework. The application emphasizes how to take advantage of the asynchronous services offered by the Landmarks Framework and how to display the results from such services in GUI components

7. Class Hierarchy

This inheritance list is sorted roughly, but not completely, alphabetically:

Class	Description
MLandmarksDbObserver	This interface should be implemented by classes that are interested in handling database events.
MLandmarksOperationObserver	Many operations offered by the application engine are asynchronous. Classes in the application UI that invoke these functions need to be notified when these asynchronous operations are completed. MLandmarksOperationObserver is a generic callback interface implemented by such classes.
CLandmarksAppUi	CLandmarksAppUi inherits from CAknViewAppUi, which indicates that this is a view-based application. It creates the two application views for displaying landmarks and categories as well as the application engine. It also initializes the landmarks database if necessary. For this reason, it implements the MLandmarksOperationObserver interface to be notified when initialization is completed. It takes care of application global events such as exiting the application and switching views.
CLandmarksView	This is the view displaying landmarks. It has CLandmarksContainer that is responsible for the graphical components of the view. It handles commands from the menu items such as deleting landmarks, editing landmarks, creating blank landmarks and creating landmarks based on the current location. To be able to fetch the current location, it implements the MLandmarksOperationObserver interface that is notified when an asynchronous location acquisition request is completed.
CLandmarksContainer	CLandmarksContainer contains a listbox displaying landmark names and a search field for filtering the displayed landmarks. The listbox is dependent on the search field and the responsibility of this class is to update the listbox and the listbox model with new landmarks whenever the search field has been updated or an event from the database has been reported. Since filtering is an asynchronous process, it implements MLandmarksOperationObserver to be notified about the progress of the filter process. It also implements the MLandmarksDbObserver interface to be notified about database events.
CLandmarksModel	This is the data model for the listbox with landmarks. The model consists of a list of the landmark IDs, a list of the landmark icons and a list of the landmark names.
CLandmarksCategoriesView	This is the view displaying categories. It has CLandmarksCategoriesContainer that is responsible for the graphical components of the view. It handles commands from the menu items such as deleting, renaming and creating categories.
CLandmarksCategoriesContainer	CLandmarksCategoriesContainer contains a listbox displaying category names and a search field for filtering the displayed categories. The listbox is dependent on the search field and the responsibility of this class is to update the listbox and the listbox model with new categories whenever the search field has been updated or an event from the database has been reported. Since filtering is an asynchronous process, it implements MLandmarksOperationObserver to be notified about the progress of the filtering process. It also implements the MLandmarksDbObserver interface to be notified about database events.
CLandmarksCategoriesModel	This is the data model for the listbox with categories. The model consists of a list of the category IDs, a list of the category icons and a list of the category names.
CLandmarksContainerBase	This is an abstract class defining the look and behavior of the view containers. It takes care of creating and destroying the graphical components of a view container.
CLandmarksInfoView	This is the view displaying a landmark's information. It does not show empty fields. If 'Edit' left softkey is pressed it opens editor dialog using CLandmarksEditDialog.
CLandmarksInfoContainer	This container controls a listbox, which displays landmark's information. It is used by CLandmarkInfoView and it uses CLandmarksInfoModel. This class is another candidate to be a listener of MLandmarksDbObserver. If some changes happen to the landmark being shown, the view can be updated. However, for simplicity's sake, this is not implemented.
CLandmarksInfoModel	This is the data model for the landmark's information view. It provides methods for building the container's listbox items.
CLandmarksEditDialog	This class is a dialog for editing a specific landmark. It allows the user to update a landmark to the current location. For this reason, it implements MLandmarksOperationObserver to be notified when a location retrieval is completed. It is also used when a new landmark is being created, in which case an empty landmark is edited.
CLandmarksCategoriesDialog	This class is not shown in figure 15 for simplicity. It is used by CLandmarksEditDialog to allow the changing of landmark categories. It is derived from the CAknMarkableListDialog class.
CLandmarksPositionRequest	This class is inherits from CActive and is responsible for acquiring the current location. Location Acquisition API is used for this purpose. It first tries to utilize the default positioning module. If this fails, it tries to fetch the last known location. If that also fails, no location is returned. During the location retrieval, a Wait note is displayed where the user can cancel the operation.

Class	Description
CLandmarksApplicationEngine	This class provides the interface to the application engine. It encapsulates the whole engine and can be seen as a wrapper since it contains no complex logic but forwards most requests to the appropriate engine class.
CLandmarksDbEventHandler	Inside the application engine, there is only one instance of the CPosLandmarkDatabase class. Each instance of CPosLandmarkDatabase accepts only one database observer. The CLandmarksDbEventHandler instance is the object that is notified when an event has occurred. The task for this object is to allow several other objects to register for database events and to notify them whenever such an event occurs.
CLandmarksEngineBase	This is an abstract base class for view engines. View engines are active objects, which explains why this class inherits from CActive. It has a CLandmarksLmOpWrapper instance to monitor the execution progress of asynchronous Landmarks Framework functions. It contains a CPosLandmarkSearch instance to be able to search for landmarks and categories and it handles setting the priority of a view engine. A view engine should have low priority when its corresponding view is deactivated and normal priority when its view is activated.
CLandmarksEngine	This view engine serves the Landmarks view. All the functions this view needs to execute are implemented by this class, e.g. filtering landmarks, reading landmarks, removing landmarks, etc.
CLandmarksCategoriesEngine	This view engine serves the Categories view. All the functions this view needs to execute are implemented by this class, e.g. filtering categories, creating categories, committing categories, etc.
CLandmarksLmOpWrapper	As stated before, several time-consuming operations in the Landmarks Framework return a handle to themselves when executed. Such a handle is an instance of the CPosLmOperation class and makes it possible to execute the operation incrementally. CPosLmOpWrapper is an active object that wraps a CPosLmOperation instance. Its task is to take care of the incremental execution.

Transition	Description
1	When acquiring a location, first the default positioning module is used.
2	If the default positioning module succeeds, the location is accepted.
3	If the request for the current location is cancelled, no location is acquired.
4	If the default positioning module fails to acquire the location, an attempt to acquire the last known location is made.
5	If acquiring the last known location succeeds, the location is accepted.
6-7	If acquiring the last known location fails for some reason, no location is acquired.

Message	Description
1-3	Before creating any views, the CLandmarksAppUi instance creates the application engine.
4-5	When the Landmarks view engine is created, partial read parameters are set.
6	The Categories view engine is created.
7-8	Before the database can be utilized by any view, it must be initialized. This is done asynchronously.
9-11	When the database has been initialized, it is safe to create and activate the views. Note: CLandmarksInfoView is also created at this stage.
12-13	When the Landmarks view is activated for the first, time its container is created. During the construction, the container registers itself as an observer of database events. This procedure is repeated by the Categories view when it is activated for the first time.
14	The last step of the initialization is to start populating the listbox with landmarks.

Message	Description
1-3	During the construction of CLandmarksEngine, a new CPosLmPartialReadParameters instance is created.
4	The attributes to set are landmark name and landmark icon as this is the only information displayed in the listbox. Note that these partial read parameters have impact when reading landmarks partially. When reading a landmark completely, they have no impact at all.
5	The new partial read parameters are set to the database.

Message	Description
1-4	During the construction of CLandmarksAppUi, it tries to start initializing the database if needed.
5-6	If the database needs to be initialized, a database initialization operation is prepared and an operation handle is returned.
7	The incremental initialization is started by executing the next step.
8-9	If the database needs to be initialized, CLandmarksAppUi creates and launches a progress dialog. Otherwise, no action is taken since the database is already prepared for use.
10-12	The first incremental step of the initialization process is completed and the CLandmarksAppUi instance is notified. It handles this event by updating the progress bar according to the progress status of the operation.
13	The next step of the initialization is executed.
14-16	Step 10-13 are repeated until the initialization process is totally completed. Finally, the progress dialog is dismissed.

Message	Description
1-2	During the application startup, the view containers are registered as database observers to the application engine.
3-4	If there is no database event handler, it is dynamically created. During the construction, it starts to listen for database events.
5-6	Whenever an event is generated, the database event handler catches and distributes the event to all registered observers, i.e. the view containers.
7	The view containers investigate the event and start to refresh their contents if necessary.
8	When the database event handler has distributed the event to all registered observers, it immediately starts listening for new events.

Message	Description
1-2	A write operation is going to be performed and the size of the database is retrieved.
3-4	The usage of the database is investigated and if the database usage is below a certain level, a compact operation is requested.
5	The compact operation can be executed asynchronously or synchronously. In this case, it is executed synchronously and it is automatically deleted by the framework.

Message	Description
1-3	The user has activated the menu command for adding a landmark. The framework generates an event that is handled by the Landmarks view. A new landmark object instance is created in memory.
4-6	The edit dialog is created and started.
7	The current location is acquired if the user creates a landmark based on the current location and the blank landmark is updated with this location. If no location was acquired, the landmark remains blank.
8-12	The user edits the landmark’s fields and then accepts the changes. The data from the input fields is saved to the landmark.
13-14	The landmark is stored in the database.
15	Since a write operation has taken place in the database, the level of obsolete contents is checked and the database is compacted if necessary.

Message	Description
1-2	The user has updated the filter in the search field of the Landmarks view. Since CLandmarksContainer is observing the search field, it is notified by the framework. The container handles this event by initiating a new landmark search operation with the current filter.
3-4	The application engine prepares the search operation by constructing the search criteria; only those landmarks whose name contains the filter will be qualified as matches.
5-6	The search/sort operation is created. Note the second parameter indicating that the found matches should be sorted by name in ascending order. Since searching is a heavy operation, an operation handle is returned.
7	The first step of the search/sort operation is executed.
8-9	The first step of the search/sort operation is completed and the next step is started if the operation was not fully completed.
10-15	The last step of the search/sort operation is completed and the matches are retrieved. First an iterator is retrieved, and from this iterator, an array of landmark ids is fetched. The container that initiated the search operation is notified that the sorted matches can be fetched.
16-18	The observer fetches the filtered landmarks and initiates a read operation.
19-21	One page of landmarks is prepared to be partially read. Only the name and the icon of the landmarks will be read. The first incremental step of reading the page is started.
22-23	The first incremental step of reading a page of landmarks is completed. If all the landmarks in the page were not read, the next step of the read operation is executed.
24-29	When the page has been completely read, the container that initiated the read operation is notified. The container fetches the landmarks and updates its listbox of landmarks by appending the current page to it.
30-32	The next page of landmarks is prepared to be read and the procedure of reading a page of landmarks is repeated.
33-34	When there are no more landmarks to read, the container is notified that the read operation is ready.