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

Change-Id: I18bb1c341e7d87cd1d649f2c3fc9c50141c6a1a9

17 files changed, 1001 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
+
+*/
diff --git a/examples/positioning/geoflickr/doc/images/qml-flickr-1.jpg b/examples/positioning/geoflickr/doc/images/qml-flickr-1.jpg
new file mode 100644
index 00000000..42514ff0
--- /dev/null
+++ b/examples/positioning/geoflickr/doc/images/qml-flickr-1.jpg
diff --git a/examples/positioning/geoflickr/doc/src/geoflickr.qdoc b/examples/positioning/geoflickr/doc/src/geoflickr.qdoc
new file mode 100644
index 00000000..6d043d4d
--- /dev/null
+++ b/examples/positioning/geoflickr/doc/src/geoflickr.qdoc
@@ -0,0 +1,87 @@
+/****************************************************************************
+**
+** 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 geoflickr
+    \title GeoFlickr (QML)
+    \ingroup qtpositioning-examples
+
+    \brief The GeoFlickr example shows how to use the user's current position to
+           fetch local content from a web service.
+
+    This is a small example, illustrating one of the very core parts of the
+    \l{Qt Positioning} API: the ability to retrieve and use the user's current
+    geographic position.
+
+    Key QML types shown in this example:
+    \list
+        \li \l{QtPositioning::PositionSource}{PositionSource}
+        \li \l{XmlListModel}{XmlListModel}
+    \endlist
+
+    \image  qml-flickr-1.jpg
+
+    \include examples-run.qdocinc
+
+    \section1 Retrieving the Current Position
+
+    Retrieving the user's current position is achieved using the PositionSource
+    type. In this example, we instantiate the PositionSource as part of the
+    GeoTab component (the floating "window" describing current position and
+    status).
+
+    \snippet geoflickr/flickrmobile/GeoTab.qml possrc
+
+    When the "Locate and update" button is pressed, we first interrogate the
+    PositionSource to check if it has an available backend for positioning
+    data. If it does not, we fall back to using a pre-recorded NMEA log
+    for demonstration. We then instruct the PositionSource to update.
+
+    \snippet geoflickr/flickrmobile/GeoTab.qml locatebutton-top
+    \snippet geoflickr/flickrmobile/GeoTab.qml locatebutton-clicked
+
+    To share the new position data with the rest of the application, we use
+    properties that we have created on the GeoTab component:
+
+    \snippet geoflickr/flickrmobile/GeoTab.qml props
+
+    \section1 Using the Current Position
+
+    The longitude and latitude values retrieved here are eventually set on
+    in properties on the RestModel component. The RestModel is an XmlListModel,
+    which retrieves XML data from a URL and creates a data model by performing
+    XPath queries on it.
+
+    In this case, it retrieves data from the Flickr REST API online, based on
+    our current position
+
+    \snippet geoflickr/flickrcommon/RestModel.qml restmodel
+
+    This model data is then shown in a variety of Qt Quick views to produce
+    the example application.
+
+*/
diff --git a/examples/positioning/logfilepositionsource/doc/src/logfilepositionsource.qdoc b/examples/positioning/logfilepositionsource/doc/src/logfilepositionsource.qdoc
new file mode 100644
index 00000000..6b008af6
--- /dev/null
+++ b/examples/positioning/logfilepositionsource/doc/src/logfilepositionsource.qdoc
@@ -0,0 +1,87 @@
+/****************************************************************************
+**
+** 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 logfilepositionsource
+\title Log File Position Source (C++)
+\ingroup qtpositioning-examples
+
+\brief The Logfile Position Source shows how to create and work with a custom NMEA position source,
+       for platforms without GPS.
+
+The data is read from a file which has positional data in NMEA format. The resulting time and
+position information is then displayed to the screen as simple text in date/time and
+latitude/longitude format.
+
+This example class reads position data from a text file, \e log.txt. The file specifies position
+data using a simple text format: it contains one position update per line, where each line contains
+a date/time, a latitude and a longitude, separated by spaces. The date/time is in ISO 8601 format
+and the latitude and longitude are in degrees decimal format. Here is an excerpt from \e log.txt:
+
+\code
+2009-08-24T22:25:01 -27.576082 153.092415
+2009-08-24T22:25:02 -27.576223 153.092530
+2009-08-24T22:25:03 -27.576364 153.092648
+\endcode
+
+The class reads this data and distributes it via the
+\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal.
+
+Here is the definition of the \c LogFilePositionSource class:
+
+\quotefromfile logfilepositionsource/logfilepositionsource.h
+\skipto class LogFilePositionSource
+\printuntil };
+
+The main methods overrided by the subclass are:
+
+\list
+    \li \l{QGeoPositionInfoSource::startUpdates()}{startUpdates()}: called by client applications
+        to start regular position updates.
+    \li \l{QGeoPositionInfoSource::stopUpdates()}{stopUpdates()}: called by client applications to
+        stop regular position updates.
+    \li \l{QGeoPositionInfoSource::requestUpdate()}{requestUpdate()}: called by client applications
+        to request a single update, with a specified timeout.
+\endlist
+
+When a position update is available, the subclass emits the
+\l{QGeoPositionInfoSource::positionUpdated()}{positionUpdated()} signal.
+
+Here are the key methods in the class implementation:
+
+\quotefromfile logfilepositionsource/logfilepositionsource.cpp
+\skipto LogFilePositionSource::LogFilePositionSource
+\printuntil /^\}/
+\skipto LogFilePositionSource::startUpdates
+\printuntil /^\}/
+\skipto LogFilePositionSource::stopUpdates
+\printuntil /^\}/
+\skipto LogFilePositionSource::requestUpdate
+\printuntil /^\}/
+\printuntil LogFilePositionSource::readNextPosition
+\printuntil /^\}/
+*/
diff --git a/examples/positioning/satelliteinfo/doc/images/example-satelliteinfo.png b/examples/positioning/satelliteinfo/doc/images/example-satelliteinfo.png
new file mode 100644
index 00000000..aa9a217c
--- /dev/null
+++ b/examples/positioning/satelliteinfo/doc/images/example-satelliteinfo.png
diff --git a/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc b/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc
new file mode 100644
index 00000000..51e40867
--- /dev/null
+++ b/examples/positioning/satelliteinfo/doc/src/satelliteinfo.qdoc
@@ -0,0 +1,75 @@
+/****************************************************************************
+**
+** 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 satelliteinfo
+    \title SatelliteInfo (C++/QML)
+
+    \brief The SatelliteInfo example shows how the available satellites
+    at the user's current position and marks the satellites
+    currently contributing to the GPS fix as pink.
+
+    \ingroup qtpositioning-examples
+
+    Key \l{Qt Positioning} classes used in this example:
+
+    \list
+    \li \l{QGeoSatelliteInfo}
+    \li \l{QGeoSatelliteInfoSource}
+    \endlist
+
+    \image ../images/example-satelliteinfo.png
+
+    The example displays the signal strength of all satellites in view. Any satellite
+    that is currently used to calculate the GPS fix has been marked pink. The number at
+    the bottom of each signal bar is the individual satellite identifier.
+
+    The application operates in three different modes:
+
+    \table
+        \header
+            \li Application mode
+            \li Description
+        \row
+            \li running
+            \li The application continuously queries the system for satellite updates. When new data
+                is available it will be displayed.
+        \row
+            \li stopped
+            \li The application stops updating the satellite information.
+        \row
+            \li single
+            \li The application makes a single update request with a timeout of 10s. The display
+                remains empty until the request was answered by the system.
+    \endtable
+
+    If the platform does not provide satellite information the application automatically
+    switches into a demo mode whereby it continuously switches between predefined
+    sets of satellite data.
+
+    \include examples-run.qdocinc
+*/
diff --git a/examples/positioning/weatherinfo/doc/images/example-weatherinfo.png b/examples/positioning/weatherinfo/doc/images/example-weatherinfo.png
new file mode 100644
index 00000000..6557b57b
--- /dev/null
+++ b/examples/positioning/weatherinfo/doc/images/example-weatherinfo.png
diff --git a/examples/positioning/weatherinfo/doc/src/weatherinfo.qdoc b/examples/positioning/weatherinfo/doc/src/weatherinfo.qdoc
new file mode 100644
index 00000000..3db6fcbf
--- /dev/null
+++ b/examples/positioning/weatherinfo/doc/src/weatherinfo.qdoc
@@ -0,0 +1,113 @@
+/****************************************************************************
+**
+** 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 weatherinfo
+    \title Weather Info (C++/QML)
+
+    \brief The Weather Info example shows how to use the user's current position
+           to retrieve local content from a web service in a C++ plugin for QML.
+
+    \ingroup qtpositioning-examples
+
+    Key \l{Qt Positioning} classes used in this example:
+
+    \list
+    \li \l{QGeoPositionInfo}
+    \li \l{QGeoPositionInfoSource}
+    \endlist
+
+    \image ../images/example-weatherinfo.png
+
+    \include examples-run.qdocinc
+
+    The example uses weather data provided by \l http://www.openweathermap.org.
+
+    The key part of this example is the application's data model, contained
+    in the WeatherData and AppModel classes. WeatherData represents the weather
+    information taken from the HTTP service. It is a simple data class, but we
+    give it Q_PROPERTies to expose it nicely to QML, later.
+
+    \snippet weatherinfo/appmodel.h 0
+    \snippet weatherinfo/appmodel.h 1
+
+    AppModel models the state of the entire application. At startup, the
+    application first begins by waiting for network connectivity. We do
+    this using the QNetworkConfigurationManager and QNetworkSession family
+    of C++ APIs.
+
+    \snippet weatherinfo/appmodel.cpp 0
+    \snippet weatherinfo/appmodel.cpp 1
+
+    Once the network session is open, we proceed to get the platform's
+    default position source using QGeoPositionInfo::createDefaultSource()
+
+    \snippet weatherinfo/appmodel.cpp 2
+
+    If no default source is available, we take a static position and fetch
+    weather for that. If, however, we do have a position source, we connect
+    its positionUpdated() signal to a slot on the AppModel and call
+    startUpdates(), which begins regular updates of device position.
+
+    When a position update is received, we use the longitude and latitude
+    of the returned coordinate to retrieve the current "city" name for use
+    in the weather lookup.
+
+    \snippet weatherinfo/appmodel.cpp 3
+
+    To inform the UI about this process, the cityChanged() signal is emitted
+    when a new city is used, and the weatherChanged() signal whenever a
+    weather update occurs.
+
+    \snippet weatherinfo/appmodel.h 2
+    \snippet weatherinfo/appmodel.h 3
+    \snippet weatherinfo/appmodel.h 4
+
+    We use a QQmlListProperty for the weather forecast information,
+    which contains the next 4 days of forecast weather. This makes it
+    easy to access from QML.
+
+    To expose these to the QML UI layer, we use the qmlRegisterType()
+    function. We call this once for each type we wish to register, before
+    loading the actual QML file.
+
+    \snippet weatherinfo/main.cpp 0
+    \snippet weatherinfo/main.cpp 1
+
+    Finally, in the actual QML, we instantiate the AppModel.
+
+    \snippet weatherinfo/weatherinfo.qml 0
+    \snippet weatherinfo/weatherinfo.qml 1
+    \snippet weatherinfo/weatherinfo.qml 2
+
+    Once instantiated like this, we can use its properties elsewhere in the
+    QML document:
+
+    \snippet weatherinfo/weatherinfo.qml 3
+    \snippet weatherinfo/weatherinfo.qml 4
+
+*/