/****************************************************************************
**
** 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
*/