1 files changed, 83 insertions, 0 deletions
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
+*/