/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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

    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.  Because the \c nokia plugin has been
    specified, some mandatory parameters need to be filled in, see the \l
    {Mandatory Parameters} {Nokia Plugin} documentation for details:

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