Changes

The following header file(s) have changed.

- - No Changes

Purpose

Landmarks UI Add/Edit API provides ready-made UI components for landmark related operations, like viewing and editing of a existing landmark, creating a new landmark, etc. The UI components also allow sending of a landmark using "Landmark Messaging" and support map related operations involving landmarks.

Dependencies

Landmarks UI Add/Edit API internally utilizes:

  • The position classes and generic position field IDs from Location Acquisition API (see reference document [2] )

  • The classes of Landmarks API (see reference document [1] ) for accessing the landmark database.

  • "Send" functionality (to send landmarks using "Landmark Messaging" , see reference document [3] )

Constraints

This API is valid for all platforms running on Symbian OS v9.4 or later.

Classification and release information

This API is an SDK API and was first published in S60 release 3.0.

API description

Landmarks UI Add/Edit API is typically used by applications 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.

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. The requested attributes to be shown is overridden by Product configuration (refer " " section). This class provides an interface for specifying the Editor or Viewer mode while launching the landmark editor dialog.

Related APIs
  • CLmkEditorDlg
  • TLmkEditorParams
Related APIs
  • CLmkEditorDlg
  • CPosLandmark

Using Landmarks UI Add Edit API

Before using this API, client applications need to open an existing landmark database and obtain the database handle. This can be done using the CPosLandmarkDatabase class from .

Launching the landmark Editor\Viewer dialog with an already existing landmark ID

To launch landmarks Editor/Viewer dialog with an existing landmark Id, at first, the client typically needs to obtain the landmark Id from an existing and opened database. Client applications can obtain existing landmark Ids in various ways, like using Landmarks API or Landmarks Search API (when the user interface is not involved) or using Landmarks UI Selector API (when a user interface is involved).

To launch the dialog, the client first needs to create an instance of CLmkEditorDlg using the NewL() method and then calling the ExecuteLD() method. The parameters provided to the NewL() method differentiate the operation. The client can specify the Viewer or Editor mode while launching the dialog.

In the Editor mode, any landmark attribute can be edited by the end user. The end user can select a category or a set of categories for the landmark from the Options menu of the editor. The modified landmark is saved into the landmark database when the user presses "done" .

In the Viewer mode, the user can only view the attributes of the landmark. The user can view the landmark categories to which the current landmark belongs from the dialog’s Options menu.

The client can set its view or AppUI as the parent object of the landmarks Editor\Viewer dialog, thereby creating a network of object providers using the SetMopParent() method.

The client can set its own help context by using the SetHelpContext() method.

Although by default the Landmarks viewer dialog provides the Map and Navigation related functionality, the client can choose to disable these menu items while launching the dialog using the DisableMapAndNavigationMenuOptions() method.

The following diagram illustrates steps involved in launching the landmark dialog in Editor or Viewer mode with an already existing landmark ID.

The following example code depicts launching of editor dialog with an already existing landmark ID.

             
              void CMyLmUiAppView::LaunchLmkViewerWithLmkIdL(TLmkItemIdDbCombiInfo almItem)
              
    {
  //extract the database handle.
  CPosLandmarkDatabase* db =almItem.GetLmDb();
  //extract the seleted landmarks item id
  TPosLmItemId itemId = almItem.GetItemId();
  CLmkEditorDlg::TLmkEditorParams editParams;
  //set to make visible all the fields in viewer.
  editParams.iAttributes = CLmkEditorDlg::ELmkAll;
  //set to launch viewer
  editParams.iEditorMode = CLmkEditorDlg::ELmkViewer;
  CLmkEditorDlg *dlg = CLmkEditorDlg::NewL(*db,itemIdeditParams);
  dlg->DisableMapAndNavigationMenuOptions();
      //Set the Help context
  TCoeHelpContext aContext;
  dlg->SetHelpContext(aContext);
  //Set Mop parent
  dlg->SetMopParent(this);
  dlg->ExecuteLD()
  }
Related APIs
  • CLmkEditorDlg
  • DisableMapAndNavigationMenuOptions()
  • ExecuteLD()
  • NewL()
  • SetHelpContext()
  • SetMopParent()

Launching the landmark Editor\Viewer dialog with a new landmark

To launch the landmark Editor/Viewer dialog for a new landmark (does not exist in any landmark database), client applications need to create an instance of CPosLandmark with empty or partially filled attributes (see Landmarks API ) and use it while instantiating the CLmkEditorDlg class.

To launch the dialog, the client first needs to create an instance of CLmkEditorDlg using the NewL() method and then call the ExecuteLD() method. The user can fill/modify different landmark attributes in the Editor dialog. Once the new landmark is saved (by pressing "done" ) and the dialog is closed by the user, the client application can retrieve the newly created landmark's Id by using LandmarkId() method of the same CPosLandmark class.

The following diagram illustrates steps involved in launching the landmark dialog in Editor or Viewer mode with a new landmark object.

The following example code depicts launching of editor dialog with a new landmark object.

              
               void CLmUiRefAppView::LaunchLmkViewerWithLmkObjectL()
               
    {
  //Create an empty landmark object   
  CPosLandmark* lmk = CPosLandmark::NewL();
  CleanupStack::PushL(lmk);
  //Specify the various fields for landmark
  TLocality locality;
  locality.SetAccuracy(32.2,32.4);
  locality.SetCoordinate(56,25);
  locality.SetHorizontalAccuracy(33.1);
  locality.SetVerticalAccuracy(24.2);
  lmk->SetLandmarkNameL(_L("Forum Mall"));
  lmk->SetLandmarkDescriptionL(_L("Shopping Complex"));
  //Populate the landmark with the specified field information
  lmk->SetPositionL(locality);
  //open database
  CPosLandmarkDatabase* db = CPosLandmarkDatabase::OpenL();
  CleanupStack::PushL(db);
  CLmkEditorDlg::TLmkEditorParams editParams;
  //set to make visible all the fields in viewer.
  editParams.iAttributes = CLmkEditorDlg::ELmkAll;
  //set to launch viewer
  editParams.iEditorMode = CLmkEditorDlg::ELmkViewer;
  
  CLmkEditorDlg *dlg = CLmkEditorDlg::NewL(*db,*lmk,editParams);
  dlg->ExecuteLD();
  //Get the Id of the newly created Landmark
  TPosLmItemId lmkId = lmk->LandmarkId();
  CleanupStack::PopAndDestroy(2);//db,lmk
    }

Related APIs
  • CLmkEditorDlg
  • CPosLandmark
  • ExecuteLD()
  • LandmarkId()
  • NewL()

Error handling

Landmark UI Add/Edit API uses the standard Symbian error reporting mechanism. Errors are reported through return codes or leaves.

Variation

Landmark attributes like Latitude, Longitude, Altitude, Position accuracy and Altitude accuracy visibility will be variated depending on the product configuration/regional variation. This overwrites the requested attributes to be shown through TLmkEditorParams.

Memory overhead

The extra memory required to use this API is quite small and negligible.

Extensions to the API

There are no extensions defined to Landmarks UI Add/Edit API.

Limitations of the API

  • Once the dialog is launched using the Landmarks UI Add/Edit API in any mode (Viewer or Editor), switching to other mode is not possible (refer section " API description " in this document).

  • When a pre-populated landmark is viewed, it will not be saved to the landmark database upon exit ( refer topic "Viewing a landmark" in " API Description " section).

Related APIs
  • CPosLandmarkDatabase

Glossary

Abbreviations

API Application Programming Interface

AppUI

Application UI

AVKON

UIKON extended GUI

CONE

Control Environment, graphical UI framework for Symbian platform

DLL

Dynamic Link Library

MLFW

Mobile Location Framework

UI

User Interface

UIKON

GUI library for Symbian platform.

UML

Unified Modeling Language

Definitions

Landmark A saved location with a name. Includes coordinates, address, and other data related to the location.

Landmark category

An attribute that is assigned to a landmark. This typically helps to describe the landmark (e.g. House, Shop or Restaurant).

Landmark collection

A collection of landmarks (in implementation, maps directly to a landmark database).

Position

Coordinates in a reference system.

ID

The identifier of a landmark or a category in the landmark database.

Landmarks Framework

A component that implements Landmarks Engine, landmarks parsing functionality, etc.

Map and Navigation Framework

Map and Navigation Framework enables applications to use map, navigation and geocoding features offered by third party Provider applications. The framework exposes its basic features via AIW menus and services. Also native Symbian call-based APIs are provided for direct access to map and navigation services from client applications.

References

[1] Landmarks API Specification Document

[2] Location Acquisition API Specification Document

[3] Send UI API Specification Document