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