1/****************************************************************************
2**
3** Copyright (C) 2017 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file. Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29    \example places
30    \title Places (QML)
31    \ingroup qtlocation-examples
32
33    \brief The Places example demonstrates how to search for Places and access
34           related content.
35
36    \image places.png
37
38    The Places example demonstrates how to search for Places. In particular it shows
39    how further information such as reviews, images and related content can be retrieved.
40
41    \include examples-run.qdocinc
42
43    \include example-parameters.qdocinc
44
45    \section1 Overview
46
47    The Places example presents an application window displaying a map.  At the top of the window
48    is a search box, which is used to enter a place search query.  To search for a place enter a
49    search term into the text box and click the magnifying glass icon.  To search for a place by
50    category, click the category icon to display the list of available categories and select the
51    desired category.  The place search query will be for places that are near the current location
52    shown on the map.
53
54    For some plugins like \l {Qt Location HERE Plugin} the search box provides search term
55    suggestions when three or more characters are entered. Selecting one of the suggestions will
56    cause a place search to be performed with the selected search text.
57
58    Clicking on a search result will display details about the place. If a places has rich content
59    (editorials, reviews and images), these can be accessed by the buttons on the details page.
60    To find similar places click the "Find similar" button.
61
62    The geo service provider can be changed by accessing the "Provider" menu.
63
64    \section1 Displaying Categories
65
66    Before search by category can be performed, the list of available categories needs to be
67    retrieved.  This is achieved by creating a \l CategoryModel.
68
69    \snippet places/places.qml CategoryModel model
70
71    The \l CategoryModel type provides a model of the available categories.  It can provide
72    either a flat list or a hierarchical tree model.  In this example, we use a hierarchical tree
73    model, by setting the \l {CategoryModel::hierarchical}{hierarchical} property to \e true.  The
74    \l {CategoryModel::plugin}{plugin} property is set during example intalization.
75
76    Next we create a \l {ListView} to display the category model.
77
78    \snippet places/views/CategoryView.qml CategoryModel view
79
80    Because a hierarchical model is being used, a \l DelegateModel is needed to provide
81    navigation functionality.  If flat list model was being used the view could use the
82    \l CategoryModel directly.
83
84    The \e rootIndex property sets the root index of the \l DelegateModel. Categories are
85    displayed by the \e CategoryDelegate, which provides two signals. The \e onShowSubcategories
86    emits the \b showSubcategories() signal with root index to the current index causing the
87    sub categories of the selected category to be displayed.  The \e onSearchCategory handler emits
88    the \b searchCategory() signal with a category parameter indicating which specific category
89    has been chosen.
90
91    The \e CategoryDelegate displays the category name and emits the \b searchCategory() signal when
92    the \l {Label} is clicked:
93
94    \snippet places/views/CategoryDelegate.qml CategoryModel delegate text
95
96    The \e CategoryDelegate also displays \e arrow \l {ToolButton} when \e hasModelChildren property is set.
97
98    \snippet places/views/CategoryDelegate.qml CategoryModel delegate arrow
99
100
101    \target Presenting-Search-Suggestions
102    \section1 Presenting Search Suggestions
103
104    The \l PlaceSearchSuggestionModel type is used to fetch suggested search terms based on a
105    partially entered search term.
106
107    A new suggestion search is triggered whenever the entered search term is changed.
108
109    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 1
110    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 2
111    \snippet places/places.qml PlaceSearchSuggestionModel search text changed 3
112
113    Suggestions are only queried if the length of the search term is three or more characters.
114
115    When the status of the \l PlaceSearchSuggestionModel changes, search suggestions are displayed.
116
117    \snippet places/places.qml PlaceSearchSuggestionModel model
118
119    The main object in the "SuggestionsShown" state is the \l ListView showing the search
120    suggestions.
121
122    \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 1
123    \codeline
124    \snippet places/views/SuggestionView.qml PlaceSearchSuggestionModel view 2
125
126    A \l {Label} object is used as the delegate to display the suggestion text.  Clicking on the
127    suggested search term updates the search term and triggers a place search using the search
128    suggestion.
129
130
131    \section1 Searching for Places
132
133    The \l PlaceSearchModel type is used to search for places.
134
135    \snippet places/places.qml PlaceSearchModel model
136
137    First some of the model's properties are set, which will be used to form the search request.
138    The \l {PlaceSearchModel::searchArea}{searchArea} property is set to the
139    \e searchRegion object which is a \l [QML]{geocircle} with a center that is linked to the current
140    location displayed on the \l Map.
141
142    Finally, we define three helper functions \b searchForCategory(), \b {searchForText()} and
143    \b searchForRecommendations() which set either the \l {PlaceSearchModel::categories}{categories} or
144    \l {PlaceSearchModel::searchTerm}{searchTerm} or \l {PlaceSearchModel::recommendationId}{recommendationId}
145    properties and invokes the \l {PlaceSearchModel::update()}{update()} method to start the
146    place search.  The search results are displayed in a \l ListView.
147
148    \snippet places/views/SearchResultView.qml PlaceSearchModel place list
149
150    The delegate used in the \l ListView, \e SearchResultDelegate, is designed to handle multiple
151    search result types via a \l Loader object.  For results of type \e PlaceResult the delegate
152    is:
153
154    \snippet places/views/SearchResultDelegate.qml PlaceSearchModel place delegate
155
156    \section1 Displaying Place Content
157
158    Places can have additional rich content, including editorials, reviews and images.  Rich
159    content is accessed via a set of models.  Content models are generally not created directly by
160    the application developer, instead models are obtained from the
161    \l {Place::editorialModel}{editorialModel}, \l {Place::reviewModel}{reviewModel} and
162    \l {Place::imageModel}{imageModel} properties of the \l Place type.
163
164    \snippet places/views/EditorialView.qml PlaceEditorialModel view
165
166*/
167