Merge remote-tracking branch 'origin/5.6' into 5.7

Change-Id: I18bb1c341e7d87cd1d649f2c3fc9c50141c6a1a9

10 files changed, 639 insertions, 0 deletions

diff --git a/examples/location/mapviewer/doc/images/mapviewer.png b/examples/location/mapviewer/doc/images/mapviewer.png
new file mode 100644
index 00000000..4dc13f72
--- /dev/null
+++ b/examples/location/mapviewer/doc/images/mapviewer.png
diff --git a/examples/location/mapviewer/doc/src/mapviewer.qdoc b/examples/location/mapviewer/doc/src/mapviewer.qdoc
new file mode 100644
index 00000000..e0c320c8
--- /dev/null
+++ b/examples/location/mapviewer/doc/src/mapviewer.qdoc
@@ -0,0 +1,171 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** 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 The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/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$
+**
+****************************************************************************/
+
+/*!
+    \example mapviewer
+    \title Map Viewer (QML)
+    \ingroup qtlocation-examples
+
+    \brief The Map Viewer example shows how to display and interact with a map,
+           search for an address, and find driving directions.
+
+    \image mapviewer.png
+
+    This is a large example covering many basic uses of maps, positioning, and
+    navigation services in Qt Location. This page is divided into sections
+    covering each of these areas of functionality with snippets from the code.
+
+    \include examples-run.qdocinc
+
+    \include example-parameters.qdocinc
+
+    \section1 Overview
+
+    QML types shown in this example:
+
+    \list
+    \li Displaying a map
+        \list
+        \li \l{QtLocation::Map}{Map}
+        \li \l{QtLocation::MapGestureArea}{MapGestureArea}
+        \li \l[QML]{Coordinate}
+        \endlist
+    \li Finding an address
+        \list
+        \li \l{QtLocation::GeocodeModel}{GeocodeModel}
+        \li \l{QtLocation::MapItemView}{MapItemView}
+        \li \l{QtLocation::MapCircle}{MapCircle}
+        \endlist
+    \li Directions and travel routes
+        \list
+        \li \l{QtLocation::RouteModel}{RouteModel}
+        \li \l{QtLocation::MapRoute}{MapRoute}
+        \endlist
+    \endlist
+
+    \section1 Displaying a Map
+
+    Drawing a map on-screen is accomplished using the Map type, as shown
+    below.
+
+    \snippet mapviewer/map/MapComponent.qml top
+    \snippet mapviewer/map/MapComponent.qml coord
+    \snippet mapviewer/map/MapComponent.qml end
+
+    In this example, we give the map an initial center \l [QML]{Coordinate}{coordinate}
+    with a set latitude and longitude. We also set the initial zoom level to 50% (halfway between
+    the maximum and minimum).
+
+    \section1 Finding an Address (Geocoding)
+
+    To locate a certain address or place on the map uses a process called
+    geocoding. In order to perform a geocode operation, we first need to adjust
+    our Map object to be able to receive the result.
+
+    Receiving results of geocoding is done through a GeocodeModel:
+
+    \snippet mapviewer/map/MapComponent.qml geocodemodel0
+
+    To display the contents of the GeocodeModel we use a MapItemView:
+
+    \snippet mapviewer/map/MapComponent.qml geocodeview
+
+    MapItemView uses an object called a "delegate" to act as a template for the
+    items it creates. This can contain any map object desired, but in this case
+    we show a MapCircle:
+
+    \snippet mapviewer/map/MapComponent.qml pointdel0
+    \snippet mapviewer/map/MapComponent.qml pointdel1
+
+    With these three objects, we have enough to receive Geocode responses and
+    display them on our Map. The final piece is to send the actual Geocode
+    request.
+
+    To send a geocode request, first we create an \l [QML]{Address} object, and fill it
+    in with the desired parameters.
+
+    \snippet mapviewer/mapviewer.qml geocode0
+
+    Then we set "geocodeModel.query" to the filled in \l [QML]{Address},
+    and call update() on the GeocodeModel.
+
+    \snippet mapviewer/map/MapComponent.qml geocode1
+
+    \section1 Directions and Travel Routes
+
+    Similar to the GeocodeModel, Qt Location also features the RouteModel type,
+    which allows information about routes (for example driving directions) between two
+    or more points, to be received and used with a Map.
+
+    Here again, we instantiate the RouteModel as a property of our Map:
+
+    \snippet mapviewer/map/MapComponent.qml routemodel0
+
+    To display the contents of a model to the user, we need a view. Once again
+    we will use a MapItemView, to display the Routes as objects on the Map:
+
+    \snippet mapviewer/map/MapComponent.qml routeview0
+    \snippet mapviewer/map/MapComponent.qml routeview1
+
+    To act as a template for the objects we wish the view to create, we create
+    a delegate component:
+
+    \snippet mapviewer/map/MapComponent.qml routedelegate0
+    \snippet mapviewer/map/MapComponent.qml routedelegate1
+
+    With the model, view and delegate now complete, the only missing component
+    is some kind of control over the model to begin the Route request process.
+    In the simplest case, we can fill out a Route request using two already
+    available \l [QML]{Coordinate}{coordinates}:
+
+    \snippet mapviewer/mapviewer.qml routecoordinate
+
+    In the next snippet, we show how to set up the request object and instruct
+    the model to update. We also instruct the map to center on the start
+    coordinate for our routing request.
+
+    \snippet mapviewer/map/MapComponent.qml routerequest0
+    \snippet mapviewer/map/MapComponent.qml routerequest1
+    \snippet mapviewer/map/MapComponent.qml routerequest2
+
+    This is all that is required to display a Route on the Map. However, it is
+    also useful to be able to retrieve the written directions and explanation
+    of the travel route. In the example, these are displayed in a \l {ListView} element.
+    To create this content, we use a standard \l {Models and Views in Qt Quick#ListModel}{ListModel} and
+    \l {ListView} pair. The data in the \l {Models and Views in Qt Quick#ListModel}{ListModel} is
+    built from the routeModel's output:
+
+    \snippet mapviewer/forms/RouteList.qml routeinfomodel0
+    \snippet mapviewer/forms/RouteList.qml routeinfomodel1
+    \snippet mapviewer/forms/RouteList.qml routeinfomodel3
+
+    Inside the RouteModel, as you can see above, we add an
+    \l{QtLocation::RouteModel::status}{onStatusChanged} handler, which
+    calls the \c{showRouteList()} which updates the \c{routeInfoModel}:
+
+    \snippet mapviewer/forms/RouteList.qml routeinfomodel2
+*/
diff --git a/examples/location/places/doc/images/places.png b/examples/location/places/doc/images/places.png
new file mode 100644
index 00000000..0b1ac8b7
--- /dev/null
+++ b/examples/location/places/doc/images/places.png
diff --git a/examples/location/places/doc/src/places.qdoc b/examples/location/places/doc/src/places.qdoc
new file mode 100644
index 00000000..bc93bcaf
--- /dev/null
+++ b/examples/location/places/doc/src/places.qdoc
@@ -0,0 +1,166 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** 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 The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/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$
+**
+****************************************************************************/
+
+/*!
+    \example places
+    \title Places (QML)
+    \ingroup qtlocation-examples
+
+    \brief The Places example demonstrates how to search for Places and access
+           related content.
+
+    \image places.png
+
+    The Places example demonstrates how to search for Places. In particular it shows
+    how further information such as reviews, images and related content can be retrieved.
+
+    \include examples-run.qdocinc
+
+    \include example-parameters.qdocinc
+
+    \section1 Overview
+
+    The Places example presents an application window displaying a map.  At the top of the window
+    is a search box, which is used to enter a place search query.  To search for a place enter a
+    search term into the text box and click the magnifying glass icon.  To search for a place by
+    category, click the category icon to display the list of available categories and select the
+    desired category.  The place search query will be for places that are near the current location
+    shown on the map.
+
+    For some plugins like \l {Qt Location HERE Plugin} the search box provides search term
+    suggestions when three or more characters are entered. Selecting one of the suggestions will
+    cause a place search to be performed with the selected search text.
+
+    Clicking on a search result will display details about the place. If a places has rich content
+    (editorials, reviews and images), these can be accessed by the buttons on the details page.
+    To find similar places click the "Find similar" button.
+
+    The geo service provider can be changed by accessing the "Provider" menu.
+
+    \section1 Displaying Categories
+
+    Before search by category can be performed, the list of available categories needs to be
+    retrieved.  This is achieved by creating a \l CategoryModel.
+
+    \snippet places/places.qml CategoryModel model
+
+    The \l CategoryModel type provides a model of the available categories.  It can provide
+    either a flat list or a hierarchical tree model.  In this example, we use a hierarchical tree
+    model, by setting the \l {CategoryModel::hierarchical}{hierarchical} property to \e true.  The
+    \l {CategoryModel::plugin}{plugin} property is set during example intalization.
+
+    Next we create a \l {ListView} to display the category model.
+
+    \snippet places/views/CategoryView.qml CategoryModel view
+
+    Because a hierarchical model is being used, a \l DelegateModel is needed to provide
+    navigation functionality.  If flat list model was being used the view could use the
+    \l CategoryModel directly.
+
+    The \e rootIndex property sets the root index of the \l DelegateModel. Categories are
+    displayed by the \e CategoryDelegate, which provides two signals. The \e onShowSubcategories
+    emits the \b showSubcategories() signal with root index to the current index causing the
+    sub categories of the selected category to be displayed.  The \e onSearchCategory handler emits
+    the \b searchCategory() signal with a category parameter indicating which specific category
+    has been chosen.
+
+    The \e CategoryDelegate displays the category name and emits the \b searchCategory() signal when
+    the \l {Label} is clicked:
+
+    \snippet places/views/CategoryDelegate.qml CategoryModel delegate text
+
+    The \e CategoryDelegate also displays \e arrow \l {ToolButton} when \e hasModelChildren property is set.
+
+    \snippet places/views/CategoryDelegate.qml CategoryModel delegate arrow
+
+
+    \target Presenting-Search-Suggestions
+    \section1 Presenting Search Suggestions
+
+    The \l PlaceSearchSuggestionModel type is used to fetch suggested search terms based on a
+    partially entered search term.
+
+    A new suggestion search is triggered whenever the entered search term is changed.
+
+    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 1
+    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 2
+    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 3
+
+    Suggestions are only queried if the length of the search term is three or more characters.
+
+    When the status of the \l PlaceSearchSuggestionModel changes, search suggestions are displayed.
+
+    \snippet places/places.qml PlaceSearchSuggestionModel model
+
+    The main object in the "SuggestionsShown" state is the \l ListView showing the search
+    suggestions.
+
+    \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 1
+    \codeline
+    \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 2
+
+    A \l {Label} object is used as the delegate to display the suggestion text.  Clicking on the
+    suggested search term updates the search term and triggers a place search using the search
+    suggestion.
+
+
+    \section1 Searching for Places
+
+    The \l PlaceSearchModel type is used to search for places.
+
+    \snippet places/places.qml PlaceSearchModel model
+
+    First some of the model's properties are set, which will be used to form the search request.
+    The \l {PlaceSearchModel::searchArea}{searchArea} property is set to the
+    \e searchRegion object which is a \l [QML]{geocircle} with a center that is linked to the current
+    location displayed on the \l Map.
+
+    Finally, we define three helper functions \b searchForCategory(), \b {searchForText()} and
+    \b searchForRecommendations() which set either the \l {PlaceSearchModel::categories}{categories} or
+    \l {PlaceSearchModel::searchTerm}{searchTerm} or \l {PlaceSearchModel::recommendationId}{recommendationId}
+    properties and invokes the \l {PlaceSearchModel::update()}{update()} method to start the
+    place search.  The search results are displayed in a \l ListView.
+
+    \snippet places/views/SearchResultView.qml PlaceSearchModel place list
+
+    The delegate used in the \l ListView, \e SearchResultDelegate, is designed to handle multiple
+    search result types via a \l Loader object.  For results of type \e PlaceResult the delegate
+    is:
+
+    \snippet places/views/SearchResultDelegate.qml PlaceSearchModel place delegate
+
+    \section1 Displaying Place Content
+
+    Places can have additional rich content, including editorials, reviews and images.  Rich
+    content is accessed via a set of models.  Content models are generally not created directly by
+    the application developer, instead models are obtained from the
+    \l {Place::editorialModel}{editorialModel}, \l {Place::reviewModel}{reviewModel} and
+    \l {Place::imageModel}{imageModel} properties of the \l Place type.
+
+    \snippet places/views/EditorialView.qml PlaceEditorialModel view
+
+*/
diff --git a/examples/location/places_list/doc/images/places_list.png b/examples/location/places_list/doc/images/places_list.png
new file mode 100644
index 00000000..bf09a031
--- /dev/null
+++ b/examples/location/places_list/doc/images/places_list.png
diff --git a/examples/location/places_list/doc/src/places_list.qdoc b/examples/location/places_list/doc/src/places_list.qdoc
new file mode 100644
index 00000000..ee9925a1
--- /dev/null
+++ b/examples/location/places_list/doc/src/places_list.qdoc
@@ -0,0 +1,76 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** 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 The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/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$
+**
+****************************************************************************/
+
+/*!
+    \example places_list
+    \title Places List (QML)
+    \ingroup qtlocation-examples
+
+    \brief The Places List example demonstrates how to search for and display a list of places using a \l ListView.
+    \image places_list.png
+
+    \include examples-run.qdocinc
+
+    The \c {Places List} example demonstrates how to search for a list of places
+    in a certain area and displays the result using a \l ListView. In this particular case, a search
+    for places associated with the term \c pizza is performed.
+
+    \section1 Performing a Place Search
+
+    To write a QML application that will show places in a list, we start by
+    making the following import declarations.
+
+    \snippet places_list/places_list.qml Imports
+
+    Instantiate a \l Plugin instance.  The \l Plugin is effectively the backend
+    from where places are sourced from.  Depending on the type of the plugin,
+    some mandatory parameters may be need to be filled in. The most likely type
+    of PluginParameter are some form of service access token which are documented
+    in the service plugin. As an example see the \l
+    {Mandatory Parameters} {HERE Plugin} documentation. In this snippet the \c osm
+    plugin is used which does not require any further parameter:
+
+    \snippet places_list/places_list.qml Initialize Plugin
+
+    Next we instantiate a \l PlaceSearchModel which we can use to specify
+    search parameters and perform a places search operation.  For illustrative
+    purposes, \l {PlaceSearchModel::update} {update()} is invoked once
+    construction of the model is complete.  Typically \l
+    {PlaceSearchModel::update} {update()} would be invoked in response to a
+    user action such as a button click.
+
+    \snippet places_list/places_list.qml PlaceSearchModel
+
+    Finally we instantiate a \l ListView to show the search results found by
+    the model.  An inline delegate has been used and we have assumed that
+    every search result is of \l {Search Result Types} {type} \c
+    PlaceSearchesult.  Consequently it is assumed that we always have access to
+    the \e place \l {PlaceSearchModel Roles} {role},  other search result types
+    may not have a \e place \l {PlaceSearchModel Roles} {role}.
+
+    \snippet places_list/places_list.qml Places ListView
+*/
diff --git a/examples/location/places_map/doc/images/places_map.png b/examples/location/places_map/doc/images/places_map.png
new file mode 100644
index 00000000..4982df23
--- /dev/null
+++ b/examples/location/places_map/doc/images/places_map.png
diff --git a/examples/location/places_map/doc/src/places_map.qdoc b/examples/location/places_map/doc/src/places_map.qdoc
new file mode 100644
index 00000000..61a4be17
--- /dev/null
+++ b/examples/location/places_map/doc/src/places_map.qdoc
@@ -0,0 +1,83 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** 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 The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/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$
+**
+****************************************************************************/
+
+/*!
+    \example places_map
+    \title Places Map (QML)
+    \ingroup qtlocation-examples
+
+    \brief The Places Map example demonstrates how to search for and display a list of places
+           on a map using a MapItemView
+    \image places_map.png
+
+    The example displays a map of the current location or, if no position is
+    available, it uses Brisbane/Australia. Subsequently a search for places
+    matching the term "pizza" is performed and each result shown on the map.
+
+    \include examples-run.qdocinc
+
+    \section1 Local Search
+
+    To write the QML application that will show places on a map, we start by
+    making the following import declarations.
+
+    \snippet places_map/places_map.qml Imports
+
+    Instantiate a \l Plugin instance.  The \l Plugin is effectively the backend
+    from where places are sourced from. Depending on the chosen plugin
+    some manadatory parameters may be needed. In this case the
+    \l {Qt Location Open Street Map Plugin}{OSM plugin} is selected which does not have any mandatory
+    parameters.
+
+    \snippet places_map/places_map.qml Initialize Plugin
+
+    Next we instantiate a \l PlaceSearchModel which we can use to specify
+    search parameters and perform a places search operation.  For illustrative
+    purposes, \l {PlaceSearchModel::update} {update()} is invoked once
+    construction of the model is complete.  Typically \l
+    {PlaceSearchModel::update} {update()} would be invoked in response to a
+    user action such as a button click.
+
+    \snippet places_map/places_map.qml PlaceSearchModel
+
+    The map is displayed by using the \l Map type and inside we declare the \l
+    MapItemView and supply the search model and a delegate.  An inline delegate
+    has been used and we have assumed that every search result is of \l {Search
+    Result Types} {type} \c PlaceSerachesult.  Consequently it is assumed that
+    we always have access to the \e place \l {PlaceSearchModel Roles} {role},
+    other search result types may not have a \e place \l {PlaceSearchModel
+    Roles} {role}.
+
+    \snippet places_map/places_map.qml Places MapItemView
+
+    Finally, a \c PositionSource is used to reset the map to the curent
+    location and find "pizza" places in the new area. The position information
+    is updated every 2 minutes and if the new position is more than 500 meters
+    away from the last pizza search area the place search is retriggered.
+
+    \snippet places_map/places_map.qml Current Location
+*/
diff --git a/examples/location/planespotter/doc/images/planespotter.png b/examples/location/planespotter/doc/images/planespotter.png
new file mode 100644
index 00000000..dcfd55fe
--- /dev/null
+++ b/examples/location/planespotter/doc/images/planespotter.png
diff --git a/examples/location/planespotter/doc/src/planespotter.qdoc b/examples/location/planespotter/doc/src/planespotter.qdoc
new file mode 100644
index 00000000..ed3a2b21
--- /dev/null
+++ b/examples/location/planespotter/doc/src/planespotter.qdoc
@@ -0,0 +1,143 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** 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 The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/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$
+**
+****************************************************************************/
+
+/*!
+    \example planespotter
+    \title Plane Spotter (QML)
+    \ingroup qtlocation-examples
+
+    \brief The \c {Plane Spotter} example demonstrates the tight integration of
+    location and positioning data types into QML
+
+    \image planespotter.png
+
+    The \c {Plane Spotter} example demonstrates how to integrate location and positioning
+    related C++ data types into QML and vice versa. This is useful when it is desirable to
+    run CPU intensive position calculations in native environments
+    but the results are supposed to be displayed using QML.
+
+    The example shows a map of Europe and airplanes on two routes across Europe.
+    The first airplane commutes between Oslo and Berlin and the second airplane
+    commutes between London and Berlin. The position tracking of each airplane
+    is implemented in C++. The Oslo-Berlin plane is piloted in QML and the London-Berlin
+    plane is commanded by a C++ pilot.
+
+    \include examples-run.qdocinc
+
+    \section1 Overview
+
+
+    This example makes use of the \l Q_GADGET feature as part of its position controller
+    implementation. It permits \l {Cpp_value_integration_positioning}{direct integration}
+    of non-QObject based C++ value types into QML.
+
+    The main purpose of the \c PlaneController class is to track the current
+    coordinates of the plane at a given time. It exposes the position
+    via its position property.
+
+    \snippet planespotter/main.cpp PlaneController1
+    \snippet planespotter/main.cpp PlaneController2
+
+    The example's \c main() function is responsible for the binding of the
+    \c PlaneController class instances into the QML context:
+
+    \snippet planespotter/main.cpp PlaneControllerMain
+
+    Similar to QObject derived classes, \l QGeoCoordinate can be integrated without
+    an additional QML wrapper.
+
+    \section1 Steering the Planes
+
+    As mentioned above, the primary purpose of \c PlaneController class is to track the current
+    positions of the two planes (Oslo-Berlin and London-Berlin) and advertise them as a property
+    to the QML layer. Its secondary purpose is to set and progress a plane along a given
+    flight path. In a sense it can act as a pilot. This is very much like
+    \l CoordinateAnimation which can animate the transition from one geo coordinate to another.
+    This example demonstrates how the \c {PlaneController}'s position property is modified
+    by C++ code using the PlaneController's own piloting abilities and by QML code using
+    \l CoordinateAnimation as pilot. The Oslo-Berlin plane is animated using QML code
+    and the London-Berlin plane is animated using C++ code.
+
+    No matter which pilot is used, the results to the pilot's
+    actions are visible in C++ and QML and thus the example demonstrates unhindered and direct
+    exchange of position data through the C++/QML boundary.
+
+    The visual representation of each \c Plane is done using
+    the \l MapQuickItem type which permits the embedding of arbitrary QtQuick items
+    into a map:
+
+    \snippet planespotter/Plane.qml PlaneMapQuick1
+    \snippet planespotter/Plane.qml PlaneMapQuick2
+
+    \section2 The C++ Pilot
+
+    The C++ plane is steered by C++. The \c from and \c to property of the controller
+    class set the origin and destination which the pilot uses to calculate the
+    bearing for the plane:
+
+    \snippet planespotter/main.cpp C++Pilot1
+
+    The pilot employs a \l QBasicTimer and \l {QTimerEvent}{QTimerEvents} to
+    constantly update the position. During each timer iteration
+    \c PlaneController::updatePosition() is called and a new position calculated.
+
+    \snippet planespotter/main.cpp C++Pilot3
+
+    Once the new position is calculated, \c setPosition() is called and
+    the subsequent change notification of the property pushes the new position
+    to the QML layer.
+
+    The C++ plane is started by clicking on the plane:
+
+    \snippet planespotter/planespotter.qml CppPlane1
+    \snippet planespotter/planespotter.qml CppPlane2
+
+    \l {azimuthTo}() calculates the bearing in degrees from one coordinate to another.
+    Note that the above code utilizes a QML animation to tie the rotation
+    and the position change into a single animation flow:
+
+    \snippet planespotter/planespotter.qml CppPlane3
+
+    First, \l NumberAnimation rotates the plane into the correct direction
+    and once that is done the \c startFlight() function takes care of
+    starting the plane's position change.
+
+    \snippet planespotter/main.cpp C++Pilot2
+
+    \section2 The QML Pilot
+
+    The \l CoordinateAnimation type is used to control the flight from Oslo
+    to Berlin and vice versa. It replaces the above \l ScriptAction.
+
+    \snippet planespotter/planespotter.qml QmlPlane1
+
+    The \l MouseArea of the QML plane implements the logic for the course setting
+    and starts the animation when required.
+
+    \snippet planespotter/planespotter.qml QmlPlane2
+
+*/