Contents

• Changes
• Purpose
  • Dependencies
  • Constraints
  • Classification and Release Information
• API description
  • Use cases
  • API class structure
• Using Landmarks UI Selector API
  • Launching a single landmark selector dialog
  • Launching a multiple landmark selector dialog
  • Launching a single category selector dialog
  • Launching a multiple category selector dialog
  • Error handling
  • Memory overhead
  • Extensions to the API
  • Limitations of the API
• Glossary
  • Abbreviations
  • Definitions
• References

Dependencies

Landmarks UI Selector API internally utilizes:

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

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.

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.

• CLmkCategorySelectorDlg
• CLmkLandmarkSelectorDlg
• TLmkItemIdDbCombiInfo
• TLmkItemIdDbCombiInfo,CLmkLandmarkSelectorDlg,

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(); 
              

                      }
              

                 }     
             
            

• 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 );
               

                 }
              
             

• 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 );
              

                  }
             
            

• 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 );
              

                }
             
            

• 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.

Limitations of the API

• None

Abbreviations

Definitions