1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
/****************************************************************************
**
** 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 declarative/places
\title Places (QML)
\ingroup qtlocation-examples
\brief The Places example demonstrates how to search for Places and access
related content.
\image qml-places.png
\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.
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.
Search results are available from the slide out tab on the left. 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. If the current Geo service provider supports it, buttons to
edit and remove a place will also be available.
The geo service provider can be changed by accessing the "Provider" menu at the bottom of the
window. Depending on the features supported by the provider, the "New" menu allows creating
new Places and Categories. To create a new place, select "Place" from the "New" menu and fill
in the fields. Click "Go!" to save the place. To create a new category, select "Category"
from the "New" menu and fill in the fields. Click "Go!" to save the category.
The Places example can work with any of the available geo services plugins. However, some
plugins may require additional \l {QtLocation::PluginParameter}{plugin parameters} in order to
function correctly. \l {QtLocation::PluginParameter}{Plugin parameters} can be passed on the
command line using the \c {--plugin} argument, which takes the form:
\code
--plugin.<parameter name> <parameter value>
\endcode
Refer to the documentation for each of the geo services plugins for details on what plugin
parameters they support. The Nokia services plugin supplied with Qt requires an \e app_id and
\e token pair. See "\l {Qt Location Nokia Plugin}" for details.
\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 declarative/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 to \e placesPlugin which is the \e identifier of the
\l Plugin object used for place search throughout the example.
Next we create a view to display the category model.
\snippet declarative/places/content/places/CategoryView.qml CategoryModel view 1
\codeline
\snippet declarative/places/content/places/CategoryView.qml CategoryModel view 2
\codeline
\snippet declarative/places/content/places/CategoryView.qml CategoryModel view 3
Because a hierarchical model is being used, a \l VisualDataModel is needed to provide
navigation functionality. If flat list model was being used the view could use the
\l CategoryModel directly.
The view contains a header item that is used as a back button to navigate up the category tree.
The \e onClicked handler sets the root index of the \l VisualDataModel to the parent of the
current index. Categories are displayed by the \e CategoryDelegate, which provides four
signals. The \e onArrowClicked handler sets the root index to the current index causing the
sub categories of the selected category to be displayed. The \e onClicked handler emits
the \b categoryClicked() signal with a category parameter indicating which specific category
has been chosen. The \e onCrossClicked handler will invoke the
categories \l {Category::remove()}{remove()} method. The \e onEditClicked handler invokes the
\b editClicked() signal of the root item, this is used to notify which particular category
is to be edited.
The \e CategoryDelegate displays the category name and emits the \e clicked signal when
the text is clicked:
\snippet declarative/places/content/places/CategoryDelegate.qml CategoryModel delegate text
The \e CategoryDelegate also displays icons for editing, removing and displaying child
categories. These icons are shown as desired when the \e showSave and \e showRemove
and \e showChildren properties are set and only then in cases where the function is
supported.
\snippet declarative/places/content/places/CategoryDelegate.qml CategoryModel delegate icon
\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 declarative/places/content/places/SearchBox.qml PlaceSearchSuggestionModel search text changed
The \e suggestionsEnabled property is used to temporarily disable search suggestions when a
suggestion is selected (selecting it updates the search term text). Suggestions are only
queried if the length of the search term is three or more characters, otherwise the search
boxes state is reset.
When the status of the \l PlaceSearchSuggestionModel changes, the state of the search box is
changed to display the search suggestions.
\snippet declarative/places/content/places/SearchBox.qml PlaceSearchSuggestionModel model
The main object in the "SuggestionsShown" state is the \l ListView showing the search
suggestions.
\snippet declarative/places/content/places/SearchBox.qml PlaceSearchSuggestionModel view 1
\codeline
\snippet declarative/places/content/places/SearchBox.qml PlaceSearchSuggestionModel view 2
A \l Text 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 declarative/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 GeoCircle with a center that is linked to the current
location displayed on the \l Map.
Finally, we define two helper functions \b searchForCategory() and \b {searchForText()},
which set either the \l {PlaceSearchModel::categories}{categories} or
\l {PlaceSearchModel::searchTerm}{searchTerm} properties and invokes the
\l {PlaceSearchModel::update()}{update()} method to start the place search. The search
results are displayed in a \l ListView.
\snippet declarative/places/content/places/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 declarative/places/content/places/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 declarative/places/content/places/PlaceEditorials.qml PlaceEditorialModel view
\section1 Place and Category Creation
Some backends may support creation and saving of new places and categories. Plugin support can
be checked an run-time with the \l Plugin::supportsPlaces() method.
To save a new place, first create a new \l Place object, using the
\l {Qt::createQmlObject()}{Qt.createQmlObject()} method. Assign the appropriate plugin and
place properties and invoke the \l {Place::save()}{save()} method.
\snippet declarative/places/content/places/PlaceDialog.qml Place save
Category creation is similar:
\snippet declarative/places/content/places/CategoryDialog.qml Category save
Support for place and category removal can be checked at run-time by using the
\l {Plugin::supportsPlaces} method, passing in a \l {Plugin::supportsPlaces}{Plugin::PlacesFeatures} flag and
getting back \e true if the feature is supported. For example one would invoke
\e {supportsPlaces(Plugin.RemovePlaceFeature)} to check if the \e Plugin.RemovePlaceFeature is supported.
To remove a place, invoke its \l {Place::remove()}{remove()} method. To remove a category,
invoke its \l {Category::remove()}{remove()} method.
\section1 Running the Example
The example detects which plugins are available and has an option to show them in the via
the Provider button.
*/
|
