// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example places_list
    \title Places List (QML)
    \ingroup qtlocation-examples
    \examplecategory {Positioning & Location}
    \brief The Places List example demonstrates how to search for and display a list of places using a \l ListView.
    \image places_list.png {Numbered list of pizza places with addresses}

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