path: root/doc/src/qlandmarks.qdoc

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $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.



*/