Figure 1: Landmarks UI Selector API class diagram
The type of this interface is method-call (the interface uses only local objects).
Landmarks UI Selector API loads the implementation at run time but the implementation consists only of local objects.
This section describes the Landmarks UI Selector API class structure. UML diagrams are used to present the classes. The detailed description of the API classes is provided in the Detailed description section.
Figure 1: Landmarks UI Selector API class diagram
Landmarks UI Selector API consists of the classes TLmkItemIdDbCombiInfo, CLmkLandmarkSelectorDlg and CLmkCategorySelectorDlg.
The CLmkLandmarkSelectorDlg class provides methods for creating and launching a dialog for listing and selecting the landmarks in the landmark database. The methods of this class return the ID of the selected landmark and the database to which the selected landmark belongs. This class provides methods for selecting a single landmark or multiple landmarks.
The CLmkCategorySelectorDlg class provides methods for creating and launching a dialog for listing and selecting the categories in the landmark database. The methods of this class return the ID of the selected category and the database to which the selected category belongs. This class provides methods for selecting a single category or multiple categories.
The TLmkItemIdDbCombiInfo class provides methods for getting the ID of a landmark or category and the database handle to which the selected landmark or category belongs. The client application executes these methods to get the ID of a landmark and the database handle and then uses those for its internal usage, such as for modifying the landmark attributes or for renaming the category. The client takes the ownership of the database handle which is returned. The database handle returned to the client will be the same for all landmarks from the same database.
The following sections describe the usage of Landmark UI Selector API.
The client application creates an instance of this class and passes its reference to Landmark UI Selector API while creating the selector dialog.
When the client application launches the selector dialog, the ID of the selected landmark or category and the database to which it belongs are returned to the client application in an instance of TLmkItemIdDbCombiInfo.
The client application can then get the values of the ID of the landmark and the database handle by executing the GetItemId() and GetLmDb() methods of this class.
An instance of CLmkLandmarkSelectorDlg is created using the NewL() method.
The landmark selection dialog is launched by the ExecuteLD() method.
The client specifies the number of landmarks selected (single or multiple) by passing a reference to a single instance or an array of TLmkItemIdDbCombiInfo.
An instance of CLmkCategorySelectorDlg is created using the NewL() function.
The category selection dialog is launched by the ExecuteLD()method.
The client specifies the number of categories selected (single or multiple) by passing a reference to a single instance or an array of TLmkItemIdDbCombiInfo.
The object provider mechanism allows an object to be a part of a network of object providers. This can be used to find and access the objects of a given type where the type is defined by a unique identifier object. Object providers may be arranged in a hierarchy, i.e. an object provider may have a parent-child relationship with another object provider. Standard AVKON dialog implementation provides a mechanism to add the dialog object to a network of object providers. Landmarks UI Selector API uses the standard AVKON dialog implementation for selector dialogs. Hence, it provides methods for adding the selector dialogs to an object provider hierarchy.
For example, the client application can form a network of object providers with its view or AppUI acting as a parent and the landmark or category selector dialog of Landmarks UI Selector API acting as a child.
A view or the AppUI of the client application can set itself as the parent object of the landmark or category selector dialog using the SetMopParent() method of the selector dialog class, there by making the landmark or category selector dialog a part of the object provider hierarchy.
Landmark UI Selector API uses the standard Symbian error reporting mechanism. The errors are reported through return codes or leaves.
This API does not use any extra memory.
There are no extensions defined to Landmarks UI Selector API.
The details of the Landmarks UI Selector API classes are given in the following sections.
The client creates an instance of this class and passes its reference to Landmarks UI Selector API.
The ID of the selected landmark or category and the database handle to which the ID belongs are returned to the client application by the methods of the landmark or category selector dialog.
The client can then get the values by executing the GetItemID() and GetLmDb() methods of this class.
The client application creates an instance of the class TLmkItemIdDbCombiInfo and the default constructor mentioned below will be automatically invoked during the object creation.
TLmkItemIdDbCombiInfo ()
TPosLmItemId GetItemId () const
Usage:
The client application executes this method to get the ID of a landmark or category.
Returns:
The ID of the selected landmark or category.
CPosLandmarkDatabase* GetLmDb () const
Usage:
The client application executes this method to get the handle to a landmark database.
The client takes the ownership of database handle. It is the responsibility of the client to manage this database handle and delete it when it is not needed anymore.
The database handle is the same for all landmarks from the same database. The client should not delete same handle twice.
Returns:
A handle to the landmark database to which the landmark or category belongs.
static CLmkLandmarkSelectorDlg * NewL ()
Usage:
This is a two-phased constructor. It creates a selector for selecting one or more landmarks.
All landmarks from all the databases are shown in the selector.
The construction leaves with KErrNotSupported if the Landmarks Framework is not available.
Returns:
A new instance of this class.
void SetMopParent( MObjectProvider* aParent )
Usage:
The client application executes this method to set its view or AppUI as the parent object of the landmark selector dialog, thereby creating a network of object providers.
Parameters:
| aParent | A parent object, which can be set as the parent of the landmark selector dialog in the object provider’s hierarchy. |
TInt ExecuteLD (TLmkItemIdDbCombiInfo& aSelected)
Usage:
Runs the single landmark selection dialog.
The landmark selector object is destroyed when this function returns or leaves.
Parameters:
| aSelected | TLmkItemIdDbCombiInfo containing the ID of the selected landmark and the handle to the landmark database to which this landmark belongs. |
Returns:
Non-zero if the dialog is accepted. Zero if the dialog is cancelled.
TInt ExecuteLD (RArray<TLmkItemIdDbCombiInfo>& aSelectedItems)
Usage:
Runs the multiple landmark selection dialog.
The landmark selector object is destroyed when this function returns or leaves.
Parameters:
| aSelectedItems | An array of TLmkItemIdDbCombiInfo containing the IDs of the selected landmarks and the handles to the landmark databases to which these landmarks belong. |
Returns:
Non-zero if the dialog is accepted. Zero if the dialog is cancelled.
static CLmkCategorySelectorDlg * NewL (TBool aShowEmptyCategories = EFalse)
Usage:
This is a two-phased constructor. It creates a selector for selecting one or more categories.
Categories from all the databases are shown in the selector.
The construction leaves with KErrNotSupported if the Landmarks Framework is not available.
Parameters:
| aShowEmptyCategories | A flag specifying whether the categories in the category selector are shown with landmarks or without landmarks. By default, the categories in the category selector are shown with landmarks. |
Returns:
A new instance of this class.
void SetMopParent( MObjectProvider* aParent )
Usage:
The client application executes this method to set its view or AppUI as the parent object of the category selector dialog, thereby creating a network of object providers.
Parameters:
| aParent | A parent object, which can be set as the parent of the selector dialog in the object provider’s hierarchy. |
TInt ExecuteLD (TLmkItemIdDbCombiInfo& aSelected)
Usage:
Runs the single category selection dialog.
The category selector object is destroyed when this function returns or leaves.
Parameters:
| aSelected | TLmkItemIdDbCombiInfo containing the ID of the selected category and the handle to the landmark database to which this category belongs. |
Returns:
Non-zero if the dialog is accepted. Zero if the dialog is cancelled.
TInt ExecuteLD (RArray<TLmkItemIdDbCombiInfo>& aSelectedItems)
Usage:
Runs the multiple category selection dialog.
The category selector object is destroyed when this function returns or leaves.
Parameters:
| aSelectedItems | An array of TLmkItemIdDbCombiInfo containing the IDs of the selected categories and the handles to the landmark databases to which these categories belong. |
Returns:
Non-zero if the dialog is accepted. Zero if the dialog is cancelled.
Figure 2: Files needed by the Landmarks UI Selector API client
The Landmarks UI Selector API classes are defined in the header files shown in the Files needed by the Landmarks UI Selector API client figure above. LmkCommonUi.LIB contains the link-time information and LmkCommonUi.DLL contains the run-time information.
