Landmarks UI Add/Edit API
Changes in Landmarks UI Add/Edit API documentation
| 1.0 |
08.01.2007 |
Approved |
|
|
2.0
|
31.03.2009
|
Approved
|
Added Variation to hide Landmark attributes like Latitude, Longitude,
Altitude, Position accuracy and Altitude accuracy
|
Changes in Landmarks UI Add/Edit API
Changes
The following header file(s) have changed.
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:
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:
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:
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
CLmkEditorDlgTLmkEditorParams
Related APIs
CLmkEditorDlgCPosLandmark
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
CLmkEditorDlgDisableMapAndNavigationMenuOptions()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
CLmkEditorDlgCPosLandmarkExecuteLD()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.
Related APIs
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
|