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
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page location-places.html
\title Places
\previouspage {qtlocation-cpp.html}{QtLocation}
\section1 Overview
The Places API allows users to discover places/points of interest
and view details about them such as address and contact information;
some places may even have rich content such as images and reviews.
The Places API also facilitates management of places and
categories, allowing users to save and remove them.
\section1 Place Definition
\input place-definition.qdocinc
\section1 Common Operations
\section2 Initializing a manager
All places functionality is facilitated by a QPlaceManager instance. One must specify
a QGeoServiceProvider in order to create the QPlaceManager
\snippet snippets/places/requesthandler.h Initialize Manager
\section2 Discovery/Search
In order to perform a search operation we simply create a QPlaceSearchRequest
and set the desired search parameters, such as a search term and search center.
\snippet snippets/places/requesthandler.h Search for places cpp
The request is an asynchronous operation so we need a slot to handle the
completion of the request. In the handler we check that there are no errors and that our search result
type is a place. If so we can then retrieve some of the core details of the
place. At the end of the slot, we delete the reply since they are for single use only.
\snippet snippets/places/requesthandler.h Search for places handler cpp
\bold {Note:} Depending upon the plugin backend that was chosen, the search results may contain places
which have further details that can be fetched on a place by place basis. To fetch these other details
see \l {Fetching Place Details}.
\section3 Paging
If the plugin supports paging, limit and offset parameters may be provided to the search request.
\snippet snippets/places/requesthandler.h Search paging
\section3 Corrections
Suggested search term corrections to user input may also be returned with the search results if desired.
A maximum number can be set in the search request.
\snippet snippets/places/requesthandler.h Corrections
\dots
\dots
\snippet snippets/places/requesthandler.h Corrections handling pt1
\dots
\snippet snippets/places/requesthandler.h Corrections handling pt2
\section2 Fetching Place Details
A place that has been returned from a search request may have more details
that can be fetched. The following demonstrates how to check if there
are further details and if so how to request them.
\snippet snippets/places/requesthandler.h Details check
\dots
\dots
\snippet snippets/places/requesthandler.h Details handler cpp
\section2 Fetching Rich Content
Rich content such as images and reviews is retrieved through the manager and then if required assigned to a place.
\snippet snippets/places/requesthandler.h Image request
We can handle the content request as shown below.
\snippet snippets/places/requesthandler.h Image handler
It is important to note that the results in the QPlaceContentReply,
is a QPlaceContent::Collection which is essentially a QMap<int, QPlaceContent>. The key \c {int} in this case is the
index of the content, and the value is the content itself. Due to the way Content is implemented
it is possible to convert a content type as follows
\code
QPlaceImage image = content; //provided that 'content' has a type QPlace::ImageType
\endcode
The usage of the QPlaceContent::Collection and the conversion between content and its subtypes means
that code for handling the mechanics of paging reviews, images and editorials can be easily shared.
\section2 Search Suggestions
The retrieval of search term suggestions is very similar to performing a place search. A QPlaceSearchRequest
is used just like a place search, the only difference being that the search term is set to a
partially completed string.
\snippet snippets/places/requesthandler.h Suggestion request
And when the request is done, we can use the reply to show the suggestions.
\snippet snippets/places/requesthandler.h Suggestion handler
\section2 Recommendations
Recommendations are suggestions for places that are similar to a specified place.
The retrieval of recommendations is very similar to retrieving search term suggestions or
performing a place search.
\snippet snippets/places/requesthandler.h Recommendation
\dots
\dots
\snippet snippets/places/requesthandler.h Recommendation handler
\target Saving a place cpp
\section2 Saving a place
The saving of a new place is performed as follows, we create a QPlace instance
and populate it with information such as a name, address and coordinate. Once
done we can invoke QPlaceManager::savePlace() to begin a save operation.
\snippet snippets/places/requesthandler.h Save place pt1
\dots
\snippet snippets/places/requesthandler.h Save place pt2
Once a place is saved the reply contains the new id for that place.
\snippet snippets/places/requesthandler.h Save place handler
Note that to save an already \e existing place, the QPlace::placeId() must
be filled in with the correct id. Otherwise a new place will be created if empty or the
wrong place overwritten if the id is incorrect.
When a place is saved, the QPlaceManager may emit QPlaceManager::placedAdded() or QPlaceManager::placeUpdated()
signals. However whether a manager does so or not is provider specific, managers accessing places
from a web service will typically not emit these signals while managers accessing places locally stored generally will.
\section3 Caveats
\input place-caveats.qdocinc
\section3 Saving between managers
When saving places between managers, there are a few things to be aware of.
Some fields of a place such as the id, categories and icons are manager specific entities
e.g. the categories in one manager may not be recognised in another.
Therefore trying to save a place directly from one manager to another is not possible.
The typical approach is to use the QPlaceManager::compatiblePlace() function,
it creates a copy of a place, but only copies data that the manager supports.
Manager specific data such as the place id is not copied over. The new
copy is now suitable for saving into the manager. If the manager supports matching by alternative
ids, an alternative id attribute is assigned to the copy (see \l {Matching places between managers})
\snippet snippets/places/requesthandler.h Save to different manager
\target Removing a place cpp
\section2 Removing a place
The removal of a place is performed as follows:
\snippet snippets/places/requesthandler.h Remove place
\dots
\dots
\snippet snippets/places/requesthandler.h Remove place handler
When a place is removed, the QPlaceManager may emit the QPlaceManager::placeRemoved() signal. Whether a
manager does so is provider specific. Managers accessing places from a web service will typically not emit
these signals, while managers accessing places stored locally generally will.
\section2 Using Categories
To use categories they must first be initialized.
\snippet snippets/places/requesthandler.h Initialize categories
\dots
\dots
\snippet snippets/places/requesthandler.h Initialize categories reply
After the categories have been initialized we can then use these category functions.
\list
\o QPlaceManager::childCategories()
\o QPlaceManager::category()
\o QPlaceManager::parentCategoryId()
\o QPlaceManager::childrenCategoryIds();
\endlist
To retrieve the top level categories
we use the QPlaceManager::childCategories() function but do not provide
a category id.
\snippet snippets/places/requesthandler.h Top level categories
If we did provide an id then we could retrieve a category's children.
\snippet snippets/places/requesthandler.h Child categories
\section2 Saving a category
The following shows how to save a category
\snippet snippets/places/requesthandler.h Save category
\dots
\dots
\snippet snippets/places/requesthandler.h Save category handler
When a category is saved, the QPlaceManager may emit QPlaceManager::categoryAdded() or QPlaceManager::categoryUpdated()
signals. However whether a manager does so or not is provider specific, managers accessing places
from a web service will typically not emit these signals while managers accessing places locally stored generally will.
\section2 Removing a category
Category removal is very similar to removing a place
\snippet snippets/places/requesthandler.h Remove category
\dots
\dots
\snippet snippets/places/requesthandler.h Remove category handler
When a category is removed, the QPlaceManager may emit the QPlaceManager::categoryRemoved() signal. Whether a
manager does so is provider specific. Managers accessing places from a web service will typically not emit
these signals, while managers accessing places stored locally generally will.
\section2 Matching places between managers
Sometimes you may want to cross reference whether places from one manager match those from another manager.
Such a situation may arise where one manager provides read-only access to places (origin manager) while another second r/w
manager (destination manager) is used to save selected favorites from the first. During a search
of the origin manager we may want to know which ones have been 'favorited' into the destination manager and perhaps display
a customized favorite name rather than the original name.
The matching mechanism can vary between managers, but is typically accomplished through an alternative id.
As part of the save process, the place id from the origin manager is saved as an alternative id attribute in the destination manager
(which can have it's own place id scheme). In the following example, the origin manager is from the 'nokia' QGeoServiceProider, therefore
as part of the saving process an alternative id attriubute, x_id_nokia, is set for the place saved into the destination manager
(when QPlaceManager::compatiblePlace() is called)
\input place-crossref.qdocinc
In order to perform the matching, we create a QPlaceMatchRequest and assign it the search results from the origin manager.
The QPlaceMatchRequest will be used on the destination manager to return corresponding places. We also specify
matching parameters which are key value pairs. As mentioned previously, this can vary depending on the manager but typically
the key is QPlaceMatchRequest::AlternativeId to indicate we are matching by alternative id, the value in this case would be
x_id_nokia which specifies which alternative id attribute we are using to do the matching.
\snippet snippets/places/requesthandler.h Match places
\dots
\dots
\snippet snippets/places/requesthandler.h Match places handler
\section1 Classes in Places
\section2 Data classes
\annotatedlist QtLocation-places-data
\section2 Request classes
\annotatedlist QtLocation-places-requests
\target Places Reply Classes
\section2 Reply classes
\annotatedlist QtLocation-places-replies
\section2 Manager classes
\annotatedlist QtLocation-places-manager
*/
|
