Qt Mobility Reference Documentation

Landmark Examples

Note: This API and documentation is a Technology Preview and is still subject to change.

The Landmarks portion of the Location API facilitates the creation, retrieval, updating and deletion of landmarks from arbitrary data stores. The following page demonstrates how to perform these operations.

Namespace

The QtMobility APIs are placed into the QtMobility namespace. This is done to facilitate the future migration of Mobility APIs into Qt. See the Quickstart guide for an example on how the namespace impacts on application development.

Creating categories and landmarks

Synchronous

Creating a category

The following example demonstrates how to synchronously add a category. We create a QLandmarkCategory instance, set the desired properties and then use a QLandmarkManager instance to save it. When the category is saved, it is assigned a QLandmarkCategoryId which is why it passed as a pointer.

     QLandmarkCategory cafes;
     cafes.setName("Cafes");
     cafes.setDescription("Small diners");
     cafes.setIconUrl(QUrl("cafe.png"));
     lm->saveCategory(&cafes);  //lm is a QLandmarkManager *

Creating landmark

The following example demonstrate synchronously adding a landmark. We create a QLandmark instance, set the desired properties and then use a QLandmarkMangerInstance to save it. When the landmark is saved, it is assigned a QLandmarkId, which is why it is passed as a pointer.

     QLandmark monks;
     monks.setName("Monk's cafe");
     monks.setCoordinate(QGeoCoordinate(40.81, 73.97));

     QGeoAddress address;
     address.setThoroughfareNumber("2880");
     address.setThoroughfareName("112th Street");
     address.setCity("New York City");
     address.setState("New York");
     address.setCountry("United States");
     address.setCountryCode("US");
     monks.setAddress(address);

     monks.setDescription("Jerry's favourite diner");
     monks.addCategoryId(cafes.categoryId());

     lm->saveLandmark(&monks); //lm  is a QLandmarkManager*

Asynchronous

Creating a category

We create a QLandmarkCategory instance and set the desired properties. Next we have an instance of a QLandmarkCategorySaveRequest and set its QLandmarkManager and the append the category we want to save. We then connect the stateChanged() signal up to a slot which watches the state of the request. To begin the request we invoke start().

 void RequestExample::categorySaveRequest()
 {
     QLandmarkCategory cafes;
     cafes.setName("Cafes");
     cafes.setDescription("Small diners");
     cafes.setIconUrl(QUrl("cafe.png"));

     //catSaveRequest was created with catSaveRequest = new QLandmarkCategorySaveRequest(lmManager)
     //in the ctor, where lmManager is a QLandmarkManager *
     catSaveRequest->setCategory(cafes);

     connect(catSaveRequest, SIGNAL(stateChanged(QLandmarkAbstractRequest::State)), this,
             SLOT(categorySaveRequestHandler(QLandmarkAbstractRequest::State)));
     if (!catSaveRequest->start())
         qDebug() << "Unable to save category error code: " << catSaveRequest->error();
     else
         qDebug() << "Saveing category; awaiting results...";
 }

For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::Finished state and see if there are any errors or not. We may reuse the QLandmarkCategorySaveRequest by setting another category and running start() again.

 void RequestExample::categorySaveRequestHandler(QLandmarkAbstractRequest::State state)
 {
     if (state == QLandmarkAbstractRequest::FinishedState) {
         if (catSaveRequest->error() == QLandmarkManager::NoError) {
             qDebug() << "Category save succesfully completed";
         }
         else {
             qDebug() << "Category save was unsuccessful";
         }
     }
 }

Creating a landmark

We create a QLandmark instance and set the desired properties. Next we have an instance of a QLandmarkSaveRequest and set its QLandmarkManager and the append the category we want to save. We then connect the stateChanged() signal up to a slot which watches the state of the request. To begin the request we invoke start().

 void RequestExample::landmarkSaveRequest()
 {
     //Creating and saving a landmark
     QLandmark monks;
     monks.setName("Monk's cafe");
     monks.setCoordinate(QGeoCoordinate(40.81, 73.97));

     QGeoAddress address;
     address.setThoroughfareNumber("2880");
     // ...
     address.setCountryCode("US");
     monks.setAddress(address);

     //lmSaveRequest was created with lmSaveRequest = new QLandmarkSaveRequest(lmManager)
     //in the ctor, where lmManager is a QLandamrkManager constructor
     lmSaveRequest->setLandmark(monks);

     monks.setDescription("Jerry's favourite diner");

     connect(lmSaveRequest, SIGNAL(stateChanged(QLandmarkAbstractRequest::State)), this,
             SLOT(landmarkSaveRequestHandler(QLandmarkAbstractRequest::State)));
     if (!lmSaveRequest->start())
         qDebug() << "Unable to save landmark error code: " << lmSaveRequest->error();
     else
         qDebug() << "Saving landmark; awaiting results...";
 }

For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::Finished state and see if there are any errors or not. We may reuse the QLandmarkSaveRequest by setting another landmark and running start() again.

 void RequestExample::landmarkSaveRequestHandler(QLandmarkAbstractRequest::State state)
 {
     if (state == QLandmarkAbstractRequest::FinishedState) {
         if (lmSaveRequest->error() == QLandmarkManager::NoError) {
             qDebug() << "Landmark save succesfully completed";
         }
         else {
             qDebug() << "Landmark save was unsuccessful";
         }
     }
 }

Retrieving categories and landmarks

Synchronous

Retrieving categories

When retrieiving categories we may do so by the category ids. When the category data is needed we may use the id to retrieve a category object:

     QList<QLandmarkCategoryId> categoryIds = lm->categoryIds();
     foreach(QLandmarkCategoryId id, categoryIds) {
         qDebug() << "Found category: " << lm->category(id).name();
     }

Alternatively we could retrieve the category objects directly:

     QList<QLandmarkCategory> categories = lm->categories();
     foreach(QLandmarkCategory category, categories) {
         qDebug() << "Found category: " << category.name();
     }

Retrieving landmarks

To retrieve landmarks we create an appropriate filter, in this case a category filter, and use it with a sort order on a QLandmarkManager. We can either retrieve the appropriate ids as shown below:

     QLandmarkCategoryFilter filter;
     //categoryId is a previously retrieved QLandmarkCategoryId
     filter.setCategoryId(categoryId);

     //retrieval via ids
     QList<QLandmarkId> landmarkIds;
     QLandmarkNameSort sortOrder(Qt::AscendingOrder);
     landmarkIds = lm->landmarkIds(filter, sortOrder);
     foreach(QLandmarkId id, landmarkIds) {
         qDebug() << "Found landmark:" << lm->landmark(id).name();
     }

Or alternatively retrieve the landmark objects directly:

     QList<QLandmark> landmarks;
     landmarks = lm->landmarks(filter, sortOrder);
     foreach(QLandmark landmark, landmarks) {
         qDebug() << "Found landmark:" << landmark.name();
     }

Asynchronous

Retrieving categories

To retrieve categories we can use a QLandmarkCategoryFetchRequest (or if we wish to fetch id's then a QLandmarkCategoryIdFetchRequest) and set its manager. The request's stateChanged() signal is connected to a slot which detects whether the operation is complete. To begin the request we invoke start().

     //catFetchRequest was created with catFetchRequest = new QLandmarkCategoryFetchRequest(lmManager)
     //in the ctor, where lmManager is a QLandmarkManager*

     connect(catFetchRequest, SIGNAL(stateChanged(QLandmarkAbstractRequest::State)),
             this, SLOT(categoryFetchRequestHandler(QLandmarkAbstractRequest::State)));

     if(!catFetchRequest->start()) {
         qDebug() << "Unable to request categories, error code:" << catFetchRequest->error();
         QCoreApplication::exit(0);
     } else {
         qDebug() << "Requested categories, awaiting results...";
     }

For brevity, the slot does not process all the different request states. In our example, we watch for the QLandmarkAbstractRequest::Finished state and if there are no errors, print out the categories.

 void RequestExample::categoryFetchRequestHandler(QLandmarkAbstractRequest::State state)
 {
     if (state == QLandmarkAbstractRequest::FinishedState) {
         previousLastIndex = 0;
         if (catFetchRequest->error() == QLandmarkManager::NoError) {
             QList<QLandmarkCategory> categories = catFetchRequest->categories();
             qDebug() << "Category fetch succesfully completed";
             for(int i=0; i < categories.count(); ++i) {
                 qDebug() << categories[i].name();
             }
         }
         else {
             qDebug() << "Category fetch was unsuccessful";
         }
     }
 }

Retrieving landmarks

To retrieve landmarks we create an appropriate filter, in this case a category filter, and use it with a sort order on a QLandmarkFetchRequest. (If we wanted to operate with ids we would use a QLandmarkIdFetchRequest). We also set the manager of the request. The request's stateChanged() signal is connected to a slot which detects whether the operation is complete. To begin the request we invoke start().

     QLandmarkCategoryFilter filter;
     QLandmarkNameSort sort(Qt::AscendingOrder);
     //categoryId is a previously retrieved QLandmarkCategoryId
     filter.setCategoryId(categoryId);

     //lmFetchRequest was created with lmFetchRequest = new QLandmarkFetchRequest(lmManager)
     //in the ctor, where lmManager is a QLandmarkManger *
     lmFetchRequest->setFilter(filter);
     lmFetchRequest->setSorting(sort);

     connect(lmFetchRequest, SIGNAL(stateChanged(QLandmarkAbstractRequest::State)),
             this, SLOT(landmarkFetchRequestHandler(QLandmarkAbstractRequest::State)));

     if(!lmFetchRequest->start()) {
         qDebug() << "Unable to request landmarks, error code:" << lmFetchRequest->error();
         QCoreApplication::exit(0);
     } else {
         qDebug() << "Requested landmarks, awaiting results...";
     }

For brevity, the slot does not process all the different request states. In our example, we watch for the QLandmarkAbstractRequest::Finished state and if there are no errors, print out the landmarks.

 void RequestExample::landmarkFetchRequestHandler(QLandmarkAbstractRequest::State state)
 {
     if (state == QLandmarkAbstractRequest::FinishedState) {
         previousLastIndex = 0;
         if (lmFetchRequest->error() == QLandmarkManager::NoError) {
             qDebug() << "Landmark fetch succesfully completed";
             QList<QLandmark> landmarks = lmFetchRequest->landmarks();
             for(int i=0; i < landmarks.count(); ++i) {
                 qDebug() << landmarks[i].name();
             }
         }
         else {
             qDebug() << "Landmark fetch was unsuccessful";
         }
     }
 }

Deleting categories and landmarks

Synchronous

Deleting a category

To remove a category we simply pass the category id to a QLandmarkManager.

     //category is a previously retrieved QLandmarkCategory object
     lm->removeCategory(category.categoryId());

Deleting a landmark

To remove a landmark we simply passs the landmark id to a QLandmarkManager.

     //landmark is a previously retrieved QLandmark object
     lm->removeLandmark(landmark.landmarkId());

Asynchronous

Deleting a category

To remove a category we use a QLandmarkCategoryRemoveRequest and set its manager and the id of the category we want to remove. We then connect the stateChanged() signal up to a slot which watches the state of the request. To begin the request we invoke start()

 void RequestExample::categoryRemoveRequest()
 {
     //catRemoveRequest was created with catRemoveRequest = new QLandmarkCategoryRemoveRequest(lmManager)
     //in the ctor, where lmManager is a QLandmarkManager*
     catRemoveRequest->setCategoryId(category.categoryId()); //category is a previously retrieved QLandmarkCategory

     connect(catRemoveRequest, SIGNAL(stateChanged(QLandmarkAbstractRequest::State)),
         this, SLOT(categoryRemoveRequestHandler(QLandmarkAbstractRequest::State)));

     if(!catRemoveRequest->start()) {
         qDebug() << "Unable to request category removal, error code:" << catRemoveRequest->error();
         QCoreApplication::exit(0);
     } else {
         qDebug() << "Requested category removal, awaiting results...";
     }
 }

For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::Finished state and see if there are any errors or not. We may reuse the QLandmarkCategoryRemoveRequest by setting another category id and running start() again.

 void RequestExample::categoryRemoveRequest()
 {
     //catRemoveRequest was created with catRemoveRequest = new QLandmarkCategoryRemoveRequest(lmManager)
     //in the ctor, where lmManager is a QLandmarkManager*
     catRemoveRequest->setCategoryId(category.categoryId()); //category is a previously retrieved QLandmarkCategory

     connect(catRemoveRequest, SIGNAL(stateChanged(QLandmarkAbstractRequest::State)),
         this, SLOT(categoryRemoveRequestHandler(QLandmarkAbstractRequest::State)));

     if(!catRemoveRequest->start()) {
         qDebug() << "Unable to request category removal, error code:" << catRemoveRequest->error();
         QCoreApplication::exit(0);
     } else {
         qDebug() << "Requested category removal, awaiting results...";
     }
 }

Deleting a landmark

To remove a landmark we use a QLandmarkRemoveRequest and set its manager and the id of the landmark we want to remove. We then connect the stateChanged() signal up to a slot which watches the state of the request. To begin the request we invoke start()

 void RequestExample::landmarkRemoveRequest()
 {
     //lmRemoveRequest was created with lmRemoveRequest = new QLandmarkSaveRequest(lmManager)
     //in the ctor, where lmManager is a QLandmarkManager*
     lmRemoveRequest->setLandmarkId(landmark.landmarkId());  //landmark is a previously retrieved QLandmark

     connect(lmRemoveRequest, SIGNAL(stateChanged(QLandmarkAbstractRequest::State)), this,
             SLOT(landmarkRemoveRequestHandler(QLandmarkAbstractRequest::State)));
     if (!lmRemoveRequest->start())
         qDebug() << "Unable to remove landmark, error code: " << lmSaveRequest->error();
     else
         qDebug() << "Removing landmark; awaiting results...";
 }

For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::Finished state and see if there are any errors or not. We may reuse the QLandmarkRemoveRequest by setting another category id and running start() again.

 void RequestExample::landmarkRemoveRequestHandler(QLandmarkAbstractRequest::State state)
 {
     if (state == QLandmarkAbstractRequest::FinishedState) {
         if (lmRemoveRequest->error() == QLandmarkManager::NoError) {
             qDebug() << "Landmark removal succesfully completed";
         }
         else {
             qDebug() << "Landmark removal was unsuccessful";
         }
     }
 }


Copyright © 2009-2010 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt Mobility Project 1.1.0