/**************************************************************************** ** ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and Digia. For licensing terms and ** conditions see http://qt.digia.com/licensing. For further information ** use the contact form at http://qt.digia.com/contact-us. ** ** GNU Free Documentation License Usage ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of ** this file. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: http://www.gnu.org/copyleft/fdl.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page landmarks.html \title Landmark Examples \brief Landmarks allows management of landmark data, these examples show how it is done. The Landmarks portion of the Location API enables the creation, retrieval, updating and deletion of landmarks from arbitrary data stores. The following page demonstrates how to perform these operations. \tableofcontents \section1 Namespace The QtMobility APIs are placed into the \i{QtMobility} namespace. This is done to facilitate the future migration of QtMobility APIs into Qt. See the \l {Quickstart guide} for an example on how the namespace impacts on application development. \section1 Creating/saving categories and landmarks \section2 Synchronous \section3 Creating/saving 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. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Add category synchronously \section3 Creating/saving a landmark The following example demonstrates synchronously adding a landmark. We create a QLandmark instance, set the desired properties and then use a QLandmarkManger instance to save it. When the landmark is saved, it is assigned a QLandmarkId, which is why it is passed as a pointer. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Add landmark synchronously \section2 Asynchronous \section3 Creating/saving a category We create a QLandmarkCategory instance and set the desired properties. Next we have an instance of a QLandmarkCategorySaveRequest and set the category we want to save. We then connect the \l {QLandmarkAbstractRequest::stateChanged()} {stateChanged()} signal up to a slot which watches the state of the request. To begin the request we invoke \l {QLandmarkAbstractRequest::start()} {start()}. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Add category asynchronously req For brevity, the slot does not process all the different request states or error codes. In our example we watch for the QLandmarkAbstractRequest::FinishedState and see if there are any errors or not. We may reuse the QLandmarkCategorySaveRequest by setting another category and running \l {QLandmarkAbstractRequest::start()} {start()} again. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Add category asynchronously handler \section3 Creating/saving a landmark We create a QLandmark instance and set the desired properties. Next we have an instance of a QLandmarkSaveRequest and set the landmark we want to save. We then connect the \l {QLandmarkAbstractRequest::stateChanged()} {stateChanged()} signal up to a slot which watches the state of the request. To begin the request we invoke \l {QLandmarkAbstractRequest::start()} {start()}. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Add landmark asynchronously For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::FinishedState and see if there are any errors or not. We may reuse the QLandmarkSaveRequest by setting another landmark and running \l {QLandmarkAbstractRequest::start()} {start()} again. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Add landmark asynchronously handler \section1 Retrieving categories and landmarks \section2 Synchronous \section3 Retrieving categories To retrieve categories we simply make the appropriate call to the QLandmarkManager: \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Retrieve categories synchronously When retrieving 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: \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Retrieve categories synchronously by id \section3 Retrieving landmarks To retrieve landmarks we create an appropriate filter, in this case a category filter. In this example, we also provide a \c limit of 5 and \c offset of 0 to only retrieve the first five landmarks and we provide a sort order to the QLandmarkManager. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Retrieve landmarks synchronously Alternatively we can retrieve just the landmark ids. When the landmark data is needed at a later time we can use the id to retrieve the landmark object: \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Retrieve landmarks synchronously by id \section2 Asynchronous \section3 Retrieving categories To retrieve categories we can use a QLandmarkCategoryFetchRequest (or if we wish to fetch id's then a QLandmarkCategoryIdFetchRequest). The request's \l {QLandmarkAbstractRequest::stateChanged()} {stateChanged()} signal is connected to a slot which detects whether the operation is complete. To begin the request we invoke \l {QLandmarkAbstractRequest::start()} {start()}. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Retrieve categories asynchronously For brevity, the slot does not process all the different request states. In our example, we watch for the QLandmarkAbstractRequest::FinishedState and if there are no errors, print out the categories. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Retrieve categories asynchronously handler \section3 Retrieving landmarks To retrieve landmarks we create an appropriate filter, in this case a category filter, and set it in a QLandmarkFetchRequest. In this example, we also provide a \c limit of 5 and \c offset of 0 to only retrieve the first five landmarks and we provide a sort order to the QLandmarkFetchRequest. (If we wanted to operate with ids we would use a QLandmarkIdFetchRequest instead). The request's \l {QLandmarkAbstractRequest::stateChanged()} {stateChanged()} signal is connected to a slot which detects whether the operation is complete. To begin the request we invoke \l {QLandmarkAbstractRequest::start()} {start()}. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Retrieve landmarks asynchronously For brevity, the slot does not process all the different request states. In our example, we watch for the QLandmarkAbstractRequest::FinishedState and if there are no errors, print out the landmarks. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Retrieve landmarks asynchronously handler \section1 Deleting categories and landmarks \section2 Synchronous \section3 Deleting a category To remove a category we simply pass the category id to a QLandmarkManager. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Remove category synchronously \section3 Deleting a landmark To remove a landmark we simply pass the landmark id to a QLandmarkManager. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Remove landmark synchronously \section2 Asynchronous \section3 Deleting a category To remove a category we use a QLandmarkCategoryRemoveRequest and set the id of the category we want to remove. We then connect the \l {QLandmarkAbstractRequest::stateChanged()} {stateChanged()} signal up to a slot which watches the state of the request. To begin the request we invoke \l {QLandmarkAbstractRequest::start()} {start()} \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Remove category asynchronously For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::FinishedState and see if there are any errors or not. We may reuse the QLandmarkCategoryRemoveRequest by setting another category id and running \l {QLandmarkAbstractRequest::start()} {start()} again. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Remove category asynchronously handler \section3 Deleting a landmark To remove a landmark we use a QLandmarkRemoveRequest and set the id of the landmark we want to remove. We then connect the \l {QLandmarkAbstractRequest::stateChanged()} {stateChanged()} signal up to a slot which watches the state of the request. To begin the request we invoke \l {QLandmarkAbstractRequest::start()} {start()} \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Remove landmark asynchronously For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::FinishedState and see if there are any errors or not. We may reuse the QLandmarkRemoveRequest by setting another landmark id and running \l {QLandmarkAbstractRequest::start()} {start()} again. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Remove landmark asynchronously handler \section1 Importing Landmarks \section2 Synchronous To import landmarks from a file we can simply provide the filename to the manager (the manager will try to automatically detect the file format). If we know the format we can provide one of the \l {QLandmarkManager::Gpx} {format strings} as a parameter. Using a QLandmarkManager::TransferOption, an option for controlling import/export behavior, we can choose to include category data that comes with the landmarks(default), exclude category data meaning that the landmarks will not be associated with any categories or we can attach the landmarks to a single category meaning all the imported landmarks will be assigned to the given category. \note Typically an import operation will take a long time to execute, it is therefore recommended that landmarks be imported asynchronously rather than synchronously. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Import landmarks sync complex \section2 Asynchronous To import landmarks we use a QLandmarkImportRequest and set the filename of the file we want to import. We can set other import parameters as necessary such as the file format or the transfer option. We then connect the \l {QLandmarkAbstractRequest::stateChanged()} {stateChanged()} signal up to a slot which watches the state of the request. To begin the request we invoke \l {QLandmarkAbstractRequest::start()} {start()} \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Import landmarks asynchronously For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::FinishedState and see if there are any errors or not. We may reuse the QLandmarkImportRequest by setting filename and running \l {QLandmarkAbstractRequest::start()} {start()} again. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Import landmarks asynchronously handler \section1 Exporting Landmarks \section2 Synchronous To export landmarks we can pass a filename and \l {QLandmarkManager::Gpx} {format} to the manager. If we only want to export a subset of landmarks we can provide a list of landmark ids to export. We may also use a QLandmarkManager::TransferOption to decide whether we want to include(default) or exclude category data for the export (This will only have an affect if the supplied format supports categories.) Typically an export operation will take a long time to execute, it is therefore recommended that landmarks be exported asynchronously rather than synchronously. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Export landmarks sync complex \section2 Asynchronous To export landmarks we use a QLandmarkExportRequest and set the filename of the file we want to export to, as well as the format we wish to use. We can set other export parameters as necessary, such as a list of ids of landmarks we want to export or the transfer option. We then connect the \l {QLandmarkAbstractRequest::stateChanged()} {stateChanged()} signal up to a slot which watches the state of the request. To begin the request we invoke \l {QLandmarkAbstractRequest::start()} {start()} \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Export landmarks asynchronously For brevity, the slot does not process all the different request states. In our example we watch for the QLandmarkAbstractRequest::FinishedState and see if there are any errors or not. We may reuse the QLandmarkExportRequest by setting another filename and/or format and running \l {QLandmarkAbstractRequest::start()} {start()} again. \snippet snippets/qtlandmarksdocsample/qtlandmarksdocsample.cpp Export landmarks asynchronously handler \section1 C++ Examples There are no C++ only, documented examples of the Landmarks API. However, there is the \l {Maps Demo Tutorial} which is C++ only, though being a tutorial it is longer and more complicated than an example. \section1 QML Examples \section2 Landmark Map QML Example The \l {Landmark Map Example} shows how a mobile application might display some map information which includes landmark information imported from a landmark file. \section2 Map Viewer QML Example The \l {Declarative Map Viewer Example}{Map Viewer example} displays a map of the current location or failing that a hard-coded default location to display a typical map navigation application in form typical of a mobile phone. */