Purpose
The purpose of Landmarks UI Selector API is to provide UI components to
applications for listing and selecting one or more landmarks or categories,
which exist in the landmark database. This interface allows displaying a dialog
for the user to list landmarks or categories , to select landmarks or categories
and return the IDs of the selected items.
Dependencies
Landmarks UI Selector API internally utilizes:
Constraints
This API is valid
for all platforms running on Symbian OS 9.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 Selector API is typically used by applications that need to provide landmarks/categories listing or selection functionality
that exist in the landmarks database.
The following are snap-shots of single and multiple landmarks selector
dialogs.
The following are snap-shots of single and multiple categories selector
dialogs.
Use cases
The main use cases of Landmarks UI Selector API are as follows
-
Launching a single landmark selector dialog.
-
Launching a multiple landmark selector dialog.
-
Launching a single category selector dialog.
-
Launching a multiple category selector dialog.
API class structure
This section describes the Landmarks UI Selector API class structure.
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. 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.
Related APIs
CLmkCategorySelectorDlg
CLmkLandmarkSelectorDlg
TLmkItemIdDbCombiInfo
TLmkItemIdDbCombiInfo,CLmkLandmarkSelectorDlg,
Using Landmarks UI Selector API
Launching a single landmark selector dialog
The client can use this API to launch a dialog that allows the end-user
to select one landmark from a list of landmarks. The single landmark selector
dialog is launched by creating an instance of
CLmkLandmarkSelectorDlg
class
using the NewL()
method and then calling the ExecuteLD()
method.
A reference to a single instance of the TLmkItemIdDbCombiInfo
class
is passed while calling ExecuteLD()
that will contain the
selected landmark's information.
Once the user selects a landmark and confirms (by pressing "ok" ) the dialog
is closed and the selected landmark's Id and database handle can be retrieved
by the client application using
GetItemId()
and GetLmDb()
methods
of the TLmkItemIdDbCombiInfo
class respectively.
The client can set its view or AppUI as the parent object of the landmark
\ category selector dialog, thereby creating a network of object providers
using the
SetMopParent()
method.
Following diagram illustrates steps involved in launching a single landmark
selector dialog and retrieving the selected landmark's Id and database handle
after user's selection.
The following code snippet shows launching of single landmark selector
dialog.
void CMyLmUiAppView::LaunchLandmarksSingleSelectorL()
{
//It will hold the landmars id,after a selection is made
//using single landmark selector.
TPosLmItemId selectedItem;
CPosLandmarkDatabase* db = NULL;
//Launch LMK Selector
CLmkLandmarkSelectorDlg* lmkSelectDlg = CLmkLandmarkSelectorDlg::NewL();
lmkSelectDlg->SetMopParent(this);
TLmkItemIdDbCombiInfo selItem;
TInt retVal = lmkSelectDlg->ExecuteLD( selItem );
if (retVal !=0)
{
//Extract the selected landmarks id
selectedItem = selItem.GetItemId();
//extract the database handle returned.
//this data base handle can be used for viewing the
//landmark using Add/Edit API's.
db = selItem.GetLmDb();
}
}
Related APIs
CLmkLandmarkSelectorDlg
ExecuteLD()
GetItemId()
GetLmDb()
NewL()
SetMopParent()
TLmkItemIdDbCombiInfo
Launching a multiple landmark selector dialog
The client can do this by creating an object of
CLmkLandmarkSelectorDlg
class
and then launching the dialog using the ExecuteLD()
method.
On return from ExecuteLD()
, a reference to the array of TLmkItemIdDbCombiInfo
will
hold the selected landmark Ids.
While launching the dialog , the client can also set some landmarks to
be shown as already pre-selected and this is done by adding the landmark Ids
of such landmarks to the same array of
TLmkItemIdDbCombiInfo
before
calling ExecuteLD()
.
The following diagram illustrates steps involved in launching a multiple
landmark selector dialog.
The landmarks that are sent while launching the dialog are shown as pre-selected.
Following code snippet shows launching of multiple landmark selector dialog.
void CMyLmUiAppView::LaunchLandmarksMultipleSelectorL()
{
//using multiple landmark selector.
// Launch LMK Selector
CLmkLandmarkSelectorDlg* lmkSelectDlg = CLmkLandmarkSelectorDlg::NewL();
lmkSelectDlg->SetMopParent(this);
RArray<TLmkItemIdCombiInfo> selItemArray;
TInt retVal = lmkSelectDlg->ExecuteLD( selItemArray );
}
Related APIs
CLmkLandmarkSelectorDlg
ExecuteLD()
TLmkItemIdDbCombiInfo
Launching a single category selector dialog
The client can use this API to launch a dialog that allows the end-user
to select one category from a list of categories. The single category selector
dialog is launched by creating an instance of the
CLmkCategorySelectorDlg
class
using the NewL()
method and then calling the ExecuteLD()
method.
Rest of the usage of Single category selector is same as the single landmark
selector described above.
The following diagram illustrates steps involved in launching a single
category selector dialog.
void CMyLmUiAppView::LaunchSingleCategoryDlgL()
{
//Using single category selector
//Launch single category selector
CLmkCategorySelectorDlg* categorySelectDlg = CLmkCategorySelectorDlg::NewL();
categorySelectDlg->SetMopParent(this);
TInt retVal=categorySelectDlg->ExecuteLD( selItem );
}
Related APIs
CLmkCategorySelectorDlg
ExecuteLD()
NewL()
Launching a multiple category selector dialog
The client can launch a multiple category selector dialog by creating an
object of
CLmkCategorySelectorDlg
class and then launching
the dialog using ExecuteLD()
method. On return from ExecuteLD()
,
a reference to the array of TLmkItemIdDbCombiInfo
will hold
the selected category Ids.
While launching the dialog , client can also set some categories to be
shown as already pre-selected and this is done by adding the category Ids
of such categories to the same array of
TLmkItemIdDbCombiInfo
before
calling ExecuteLD().
.
Following diagram illustrates steps involved in launching a multiple category
selector dialog.
The categories that are sent while launching the dialog are shown as pre-selected.
void CMyLmUiAppView::LaunchMultiCategorySelectorDlgL()
{
// Launch multiple Category Selector
CLmkCategorySelectorDlg* categorySelectDlg = CLmkCategorySelectorDlg::NewL();
categorySelectDlg->SetMopParent(this);
//This array can hold, even the pre-filled category id's.
//If the dialog is launched with the pre-filled id's,corresponding
//categories will be shown as pre-selected.
//After the dialog is launched,category id's for the selected categories
//along with the pre-selected id's, will be returned in the array.
RArray <TLmkItemIdCombiInfo> selItemArray;
TInt retVal = categorySelectDlg->ExecuteLD( selItemArray );
}
Related APIs
CLmkCategorySelectorDlg
ExecuteLD()
ExecuteLD().
TLmkItemIdDbCombiInfo
Error handling
Landmark UI Selector API uses the standard Symbian error reporting mechanism.
The errors are reported through leaves
Memory overhead
The memory consumption depends upon the number of landmarks \ categories
present in the database.
Extensions to the API
There are no extensions defined to Landmarks UI Selector API.