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
|
/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** 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 either clear the id, categories and icon
or alternatively assign them with appropriate values of the new manager.
The visibility scope may also need to be modified.
\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.
\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
*/
|
