/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://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 https://www.qt.io/terms-conditions. For further
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example places
    \title Places (QML)
    \ingroup qtlocation-examples

    \brief The Places example demonstrates how to search for Places and access
           related content.

    \image places.png

    The Places example demonstrates how to search for Places. In particular it shows
    how further information such as reviews, images and related content can be retrieved.

    \include examples-run.qdocinc

    \include example-parameters.qdocinc

    \section1 Overview

    The Places example presents an application window displaying a map.  At the top of the window
    is a search box, which is used to enter a place search query.  To search for a place enter a
    search term into the text box and click the magnifying glass icon.  To search for a place by
    category, click the category icon to display the list of available categories and select the
    desired category.  The place search query will be for places that are near the current location
    shown on the map.

    For some plugins like \l {Qt Location HERE Plugin} the search box provides search term
    suggestions when three or more characters are entered. Selecting one of the suggestions will
    cause a place search to be performed with the selected search text.

    Clicking on a search result will display details about the place. If a places has rich content
    (editorials, reviews and images), these can be accessed by the buttons on the details page.
    To find similar places click the "Find similar" button.

    The geo service provider can be changed by accessing the "Provider" menu.

    \section1 Displaying Categories

    Before search by category can be performed, the list of available categories needs to be
    retrieved.  This is achieved by creating a \l CategoryModel.

    \snippet places/places.qml CategoryModel model

    The \l CategoryModel type provides a model of the available categories.  It can provide
    either a flat list or a hierarchical tree model.  In this example, we use a hierarchical tree
    model, by setting the \l {CategoryModel::hierarchical}{hierarchical} property to \e true.  The
    \l {CategoryModel::plugin}{plugin} property is set during example intalization.

    Next we create a \l {ListView} to display the category model.

    \snippet places/views/CategoryView.qml CategoryModel view

    Because a hierarchical model is being used, a \l DelegateModel is needed to provide
    navigation functionality.  If flat list model was being used the view could use the
    \l CategoryModel directly.

    The \e rootIndex property sets the root index of the \l DelegateModel. Categories are
    displayed by the \e CategoryDelegate, which provides two signals. The \e onShowSubcategories
    emits the \b showSubcategories() signal with root index to the current index causing the
    sub categories of the selected category to be displayed.  The \e onSearchCategory handler emits
    the \b searchCategory() signal with a category parameter indicating which specific category
    has been chosen.

    The \e CategoryDelegate displays the category name and emits the \b searchCategory() signal when
    the \l {Label} is clicked:

    \snippet places/views/CategoryDelegate.qml CategoryModel delegate text

    The \e CategoryDelegate also displays \e arrow \l {ToolButton} when \e hasModelChildren property is set.

    \snippet places/views/CategoryDelegate.qml CategoryModel delegate arrow


    \target Presenting-Search-Suggestions
    \section1 Presenting Search Suggestions

    The \l PlaceSearchSuggestionModel type is used to fetch suggested search terms based on a
    partially entered search term.

    A new suggestion search is triggered whenever the entered search term is changed.

    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 1
    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 2
    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 3

    Suggestions are only queried if the length of the search term is three or more characters.

    When the status of the \l PlaceSearchSuggestionModel changes, search suggestions are displayed.

    \snippet places/places.qml PlaceSearchSuggestionModel model

    The main object in the "SuggestionsShown" state is the \l ListView showing the search
    suggestions.

    \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 1
    \codeline
    \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 2

    A \l {Label} object is used as the delegate to display the suggestion text.  Clicking on the
    suggested search term updates the search term and triggers a place search using the search
    suggestion.


    \section1 Searching for Places

    The \l PlaceSearchModel type is used to search for places.

    \snippet places/places.qml PlaceSearchModel model

    First some of the model's properties are set, which will be used to form the search request.
    The \l {PlaceSearchModel::searchArea}{searchArea} property is set to the
    \e searchRegion object which is a \l [QML]{geocircle} with a center that is linked to the current
    location displayed on the \l Map.

    Finally, we define three helper functions \b searchForCategory(), \b {searchForText()} and
    \b searchForRecommendations() which set either the \l {PlaceSearchModel::categories}{categories} or
    \l {PlaceSearchModel::searchTerm}{searchTerm} or \l {PlaceSearchModel::recommendationId}{recommendationId}
    properties and invokes the \l {PlaceSearchModel::update()}{update()} method to start the
    place search.  The search results are displayed in a \l ListView.

    \snippet places/views/SearchResultView.qml PlaceSearchModel place list

    The delegate used in the \l ListView, \e SearchResultDelegate, is designed to handle multiple
    search result types via a \l Loader object.  For results of type \e PlaceResult the delegate
    is:

    \snippet places/views/SearchResultDelegate.qml PlaceSearchModel place delegate

    \section1 Displaying Place Content

    Places can have additional rich content, including editorials, reviews and images.  Rich
    content is accessed via a set of models.  Content models are generally not created directly by
    the application developer, instead models are obtained from the
    \l {Place::editorialModel}{editorialModel}, \l {Place::reviewModel}{reviewModel} and
    \l {Place::imageModel}{imageModel} properties of the \l Place type.

    \snippet places/views/EditorialView.qml PlaceEditorialModel view

*/