S60 Landmarks UI Add Edit API Specification: API description

Landmarks UI Add/Edit API is typically used by applications based on S60 that require landmarks related operations. The UI components, provided by this API, support different landmark related operations through the "Options" menu. Landmarks UI Add/Edit API provides two basic UI components: "Landmark Viewer" and "Landmark Editor".

The client can launch the dialog in one of the two modes (Viewer or Editor). Once the dialog is launched, switching to other mode is not possible using the Landmarks UI Add/Edit API. However, the end-user of the application can switch from Viewer mode to Editor mode by choosing the "edit" item in the Options menu and can switch back to Viewer mode by pressing "done". If the dialog is launched in the Editor mode, then it is not possible to switch to the Viewer mode.

The end-users of the applications making use of these UI components, can perform various operations provided as menu options.

Viewing a landmark: The client application may give its user the possibility to view the contents of a landmark by popping up a CLmkEditorDlg dialog instantiated in view mode.

The viewer dialog can display an already existing landmark in the database using the landmark ID or the newly created CPosLandmark object.

While it is possible to view a pre-populated landmark obtained as a new CPosLandmark object, it will not be saved into the database upon exit.

The main operations that can be performed once the Landmarks Viewer dialog is launched are shown below:

• Edit a Landmark: This option switches the dialog to edit mode.

• Delete a landmark: User can delete the landmark if it exists in the database. If the landmark being viewed is the newly created one then nothing happens on deleting it.

• Show a Landmark on Map: Using the menu items a particular landmark can be seen on the map. This menu item comes only if Map related features are installed.

• Send landmark: The currently viewed landmark can be sent to other phones using Landmarks messaging via bearers such as MMS or Bluetooth or Infrared technology.

• Navigate to a landmark using map: It is possible to navigate to a landmark using an appropriate menu item. This menu item comes only if Map related features are installed.

Editing a landmark: The client application may give its user the possibility to edit a landmark by popping up a CLmkEditorDlg dialog instantiated in edit mode. Using the landmarks Editor dialog, the contents of either an existing landmark or a new landmark can be edited.

The main operations that can be performed once the Landmarks Editor dialog is launched are shown below:

• Selecting the Categories: The user can select the categories for the landmark. It can also show the already selected categories for the marked Landmark.

• Delete a landmark: The user can delete the landmark if it exists in the database.

• Show a Landmark on Map: Using the menu items a particular landmark can be seen on the map. This menu item comes only if Map related features are installed.

• Send landmark: The currently viewed landmark can be sent to other phones using Landmarks messaging via bearers such as MMS or Bluetooth or Infrared technology.

• Navigate to a landmark using map: It is possible to navigate to a landmark using appropriate menu item. This menu item comes only if Map related features are installed.

Landmarks UI Add/Edit API loads the implementation at run-time and the implementation consists only of local objects. The logical type of the API is "Library API" and the technical type is Method call interface.

Use cases

The main use cases of the Landmarks UI Add\Edit API are as follows:

• Launching the landmark Editor\Viewer dialog with an already existing landmark ID.
• Launching the landmark Editor\Viewer dialog with a new landmark object.

API class structure

This section describes the Landmarks UI Add/Edit API class structure.

Landmarks UI Add/Edit API contains one class, CLmkEditorDlg. This class provides the functionality for creating a new landmark to a database or for updating an already existing landmark in a landmark database.

TLmkEditorParams is a class contained within the class CLmkEditorDlg. This class provides a mechanism for specifying which of the landmark attributes are to be shown and the mode in which the editor dialog is to be launched. This class provides an interface for specifying the Editor or Viewer mode while launching the landmark editor dialog.