1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2015 The Qt Company Ltd. |
4 | ** Contact: http://www.qt.io/licensing/ |
5 | ** |
6 | ** This file is part of the QtLocation module of the Qt Toolkit. |
7 | ** |
8 | ** $QT_BEGIN_LICENSE:LGPL3$ |
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 http://www.qt.io/terms-conditions. For further |
15 | ** information use the contact form at http://www.qt.io/contact-us. |
16 | ** |
17 | ** GNU Lesser General Public License Usage |
18 | ** Alternatively, this file may be used under the terms of the GNU Lesser |
19 | ** General Public License version 3 as published by the Free Software |
20 | ** Foundation and appearing in the file LICENSE.LGPLv3 included in the |
21 | ** packaging of this file. Please review the following information to |
22 | ** ensure the GNU Lesser General Public License version 3 requirements |
23 | ** will be met: https://www.gnu.org/licenses/lgpl.html. |
24 | ** |
25 | ** GNU General Public License Usage |
26 | ** Alternatively, this file may be used under the terms of the GNU |
27 | ** General Public License version 2.0 or later as published by the Free |
28 | ** Software Foundation and appearing in the file LICENSE.GPL included in |
29 | ** the packaging of this file. Please review the following information to |
30 | ** ensure the GNU General Public License version 2.0 requirements will be |
31 | ** met: http://www.gnu.org/licenses/gpl-2.0.html. |
32 | ** |
33 | ** $QT_END_LICENSE$ |
34 | ** |
35 | ****************************************************************************/ |
36 | |
37 | #include "qplacesearchrequest.h" |
38 | #include "qplacesearchrequest_p.h" |
39 | #include "qgeocoordinate.h" |
40 | #include "qgeoshape.h" |
41 | |
42 | #include <QtCore/QSharedData> |
43 | #include <QtCore/QList> |
44 | #include <QtCore/QVariant> |
45 | #include <QDebug> |
46 | |
47 | QT_BEGIN_NAMESPACE |
48 | |
49 | QPlaceSearchRequestPrivate::QPlaceSearchRequestPrivate() |
50 | : QSharedData(), |
51 | visibilityScope(QLocation::UnspecifiedVisibility), |
52 | relevanceHint(QPlaceSearchRequest::UnspecifiedHint), |
53 | limit(-1) |
54 | { |
55 | } |
56 | |
57 | QPlaceSearchRequestPrivate::QPlaceSearchRequestPrivate(const QPlaceSearchRequestPrivate &other) |
58 | : QSharedData(other), |
59 | searchTerm(other.searchTerm), |
60 | categories(other.categories), |
61 | searchArea(other.searchArea), |
62 | recommendationId(other.recommendationId), |
63 | visibilityScope(other.visibilityScope), |
64 | relevanceHint(other.relevanceHint), |
65 | limit(other.limit), |
66 | searchContext(other.searchContext), |
67 | related(other.related), |
68 | page(other.page) |
69 | { |
70 | } |
71 | |
72 | QPlaceSearchRequestPrivate::~QPlaceSearchRequestPrivate() |
73 | { |
74 | } |
75 | |
76 | QPlaceSearchRequestPrivate &QPlaceSearchRequestPrivate::operator=(const QPlaceSearchRequestPrivate &other) |
77 | { |
78 | if (this != &other) { |
79 | searchTerm = other.searchTerm; |
80 | categories = other.categories; |
81 | searchArea = other.searchArea; |
82 | recommendationId = other.recommendationId; |
83 | visibilityScope = other.visibilityScope; |
84 | relevanceHint = other.relevanceHint; |
85 | limit = other.limit; |
86 | searchContext = other.searchContext; |
87 | related = other.related; |
88 | page = other.page; |
89 | } |
90 | |
91 | return *this; |
92 | } |
93 | |
94 | bool QPlaceSearchRequestPrivate::operator==(const QPlaceSearchRequestPrivate &other) const |
95 | { |
96 | return searchTerm == other.searchTerm && |
97 | categories == other.categories && |
98 | searchArea == other.searchArea && |
99 | recommendationId == other.recommendationId && |
100 | visibilityScope == other.visibilityScope && |
101 | relevanceHint == other.relevanceHint && |
102 | limit == other.limit && |
103 | searchContext == other.searchContext; |
104 | |
105 | // deliberately not testing related and page. comparing only the content. |
106 | } |
107 | |
108 | void QPlaceSearchRequestPrivate::clear() |
109 | { |
110 | limit = -1; |
111 | searchTerm.clear(); |
112 | categories.clear(); |
113 | searchArea = QGeoShape(); |
114 | recommendationId.clear(); |
115 | visibilityScope = QLocation::UnspecifiedVisibility; |
116 | relevanceHint = QPlaceSearchRequest::UnspecifiedHint; |
117 | searchContext.clear(); |
118 | related = false; |
119 | page = 0; |
120 | } |
121 | |
122 | const QPlaceSearchRequestPrivate *QPlaceSearchRequestPrivate::get(const QPlaceSearchRequest &request) |
123 | { |
124 | return request.d_ptr.constData(); |
125 | } |
126 | |
127 | QPlaceSearchRequestPrivate *QPlaceSearchRequestPrivate::get(QPlaceSearchRequest &request) |
128 | { |
129 | return request.d_ptr.data(); |
130 | } |
131 | |
132 | /*! |
133 | \class QPlaceSearchRequest |
134 | \inmodule QtLocation |
135 | \ingroup QtLocation-places |
136 | \ingroup QtLocation-places-requests |
137 | \since 5.6 |
138 | |
139 | \brief The QPlaceSearchRequest class represents the set of parameters for a search request. |
140 | |
141 | A typical search request may look like the following: |
142 | \snippet places/requesthandler.h Search request |
143 | |
144 | Note that specifying a search center can be done by setting a circular search area that has |
145 | a center but no radius. The default radius is set to -1, which indicates an undefined radius. The provider will |
146 | interpret this as being free to choose its own default radius. |
147 | |
148 | The QPlaceSearchRequest is primarily used with the QPlaceManager to |
149 | \l {QPlaceManager::search()} {search for places}, however it is also |
150 | used to provide parameters for \l {QPlaceManager::searchSuggestions()}{generating search term suggestions}. |
151 | Note that in this context only some of the parameters may be relevant. For example, the search area |
152 | is useful in narrowing down relevant search suggestions, while other parameters such as relevance hint |
153 | are not so applicable. |
154 | |
155 | Also be aware that providers may vary by which parameters they support for example some providers may not support |
156 | paging while others do, some providers may honor relevance hints while others may completely ignore them, |
157 | see the \l {Qt Location#Plugin References and Parameters}{plugin documentation} for more |
158 | details. |
159 | */ |
160 | |
161 | /*! |
162 | \enum QPlaceSearchRequest::RelevanceHint |
163 | |
164 | Defines hints to help rank place results. |
165 | \value UnspecifiedHint |
166 | No explicit hint has been specified. |
167 | \value DistanceHint |
168 | Distance to a search center is relevant for the user. Closer places |
169 | are more highly weighted. This hint is only useful |
170 | if a circular search area is used in the query. |
171 | \value LexicalPlaceNameHint |
172 | Alphabetic ordering of places according to name is relevant to the user. |
173 | */ |
174 | |
175 | /*! |
176 | Default constructor. Constructs an new request object. |
177 | */ |
178 | QPlaceSearchRequest::QPlaceSearchRequest() |
179 | : d_ptr(new QPlaceSearchRequestPrivate()) |
180 | { |
181 | } |
182 | |
183 | /*! |
184 | Constructs a copy of \a other. |
185 | */ |
186 | QPlaceSearchRequest::QPlaceSearchRequest(const QPlaceSearchRequest &other) |
187 | : d_ptr(other.d_ptr) |
188 | { |
189 | } |
190 | |
191 | /*! |
192 | Destroys the request object. |
193 | */ |
194 | QPlaceSearchRequest::~QPlaceSearchRequest() |
195 | { |
196 | } |
197 | |
198 | /*! |
199 | Assigns \a other to this search request and returns a reference |
200 | to this search request. |
201 | */ |
202 | QPlaceSearchRequest &QPlaceSearchRequest::operator= (const QPlaceSearchRequest & other) |
203 | { |
204 | if (this == &other) |
205 | return *this; |
206 | |
207 | d_ptr = other.d_ptr; |
208 | return *this; |
209 | } |
210 | |
211 | /*! |
212 | Returns true if \a other is equal to this search request, |
213 | otherwise returns false. |
214 | */ |
215 | bool QPlaceSearchRequest::operator== (const QPlaceSearchRequest &other) const |
216 | { |
217 | Q_D(const QPlaceSearchRequest); |
218 | return *d == *other.d_func(); |
219 | } |
220 | |
221 | /*! |
222 | Returns true if \a other is not equal to this search request, |
223 | otherwise returns false. |
224 | */ |
225 | bool QPlaceSearchRequest::operator!= (const QPlaceSearchRequest &other) const |
226 | { |
227 | Q_D(const QPlaceSearchRequest); |
228 | return !(*d == *other.d_func()); |
229 | } |
230 | |
231 | /*! |
232 | Returns the search term. |
233 | */ |
234 | QString QPlaceSearchRequest::searchTerm() const |
235 | { |
236 | Q_D(const QPlaceSearchRequest); |
237 | return d->searchTerm; |
238 | } |
239 | |
240 | /*! |
241 | Sets the search \a term. |
242 | */ |
243 | void QPlaceSearchRequest::setSearchTerm(const QString &term) |
244 | { |
245 | Q_D(QPlaceSearchRequest); |
246 | d->searchTerm = term; |
247 | } |
248 | |
249 | /*! |
250 | Return the categories to be used in the search request. |
251 | Places need only to belong to one of the categories |
252 | to be considered a match by the request. |
253 | */ |
254 | QList<QPlaceCategory> QPlaceSearchRequest::categories() const |
255 | { |
256 | Q_D(const QPlaceSearchRequest); |
257 | return d->categories; |
258 | } |
259 | |
260 | /*! |
261 | Sets the search request to search by a single \a category |
262 | |
263 | \sa setCategories() |
264 | */ |
265 | void QPlaceSearchRequest::setCategory(const QPlaceCategory &category) |
266 | { |
267 | Q_D(QPlaceSearchRequest); |
268 | d->categories.clear(); |
269 | |
270 | if (!category.categoryId().isEmpty()) |
271 | d->categories.append(t: category); |
272 | } |
273 | |
274 | /*! |
275 | Sets the search request to search from the list of given \a categories. |
276 | Any places returned during the search will match at least one of the \a |
277 | categories. |
278 | |
279 | \sa setCategory() |
280 | */ |
281 | void QPlaceSearchRequest::setCategories(const QList<QPlaceCategory> &categories) |
282 | { |
283 | Q_D(QPlaceSearchRequest); |
284 | d->categories = categories; |
285 | } |
286 | |
287 | /*! |
288 | Returns the search area which will be used to limit search results. The default search area is |
289 | an invalid QGeoShape, indicating that no specific search area is defined. |
290 | */ |
291 | QGeoShape QPlaceSearchRequest::searchArea() const |
292 | { |
293 | Q_D(const QPlaceSearchRequest); |
294 | return d->searchArea; |
295 | } |
296 | |
297 | /*! |
298 | Sets the search request to search within the given \a area. |
299 | */ |
300 | void QPlaceSearchRequest::setSearchArea(const QGeoShape &area) |
301 | { |
302 | Q_D(QPlaceSearchRequest); |
303 | d->searchArea = area; |
304 | } |
305 | |
306 | /*! |
307 | Returns the place id which will be used to search for recommendations |
308 | for similar places. |
309 | */ |
310 | QString QPlaceSearchRequest::recommendationId() const |
311 | { |
312 | Q_D(const QPlaceSearchRequest); |
313 | return d->recommendationId; |
314 | } |
315 | |
316 | /*! |
317 | Sets the \a placeId which will be used to search for recommendations. |
318 | */ |
319 | void QPlaceSearchRequest::setRecommendationId(const QString &placeId) |
320 | { |
321 | Q_D(QPlaceSearchRequest); |
322 | d->recommendationId = placeId; |
323 | } |
324 | |
325 | /*! |
326 | Returns backend specific additional search context associated with this place search request. |
327 | The search context is typically set as part of a |
328 | \l {QPlaceSearchResult::ProposedSearchResult}{proposed search results}. |
329 | */ |
330 | QVariant QPlaceSearchRequest::searchContext() const |
331 | { |
332 | Q_D(const QPlaceSearchRequest); |
333 | return d->searchContext; |
334 | } |
335 | |
336 | /*! |
337 | Sets the search context to \a context. |
338 | |
339 | \note This method is intended to be used by geo service plugins when returning search results |
340 | of type \l QPlaceSearchResult::ProposedSearchResult. |
341 | |
342 | The search context is used by backends to store additional search context related to the search |
343 | request. Other relevant fields should also be filled in. For example, if the search context |
344 | encodes a text search the search term should also be set with \l setSearchTerm(). The search |
345 | context allows additional search context to be kept which is not directly accessible via the |
346 | Qt Location API. |
347 | |
348 | The search context can be of any type storable in a QVariant. The value of the search context |
349 | is not intended to be use directly by applications. |
350 | */ |
351 | void QPlaceSearchRequest::setSearchContext(const QVariant &context) |
352 | { |
353 | Q_D(QPlaceSearchRequest); |
354 | d->searchContext = context; |
355 | } |
356 | |
357 | /*! |
358 | Returns the visibility scope used when searching for places. The default value is |
359 | QLocation::UnspecifiedVisibility meaning that no explicit scope has been assigned. |
360 | Places of any scope may be returned during the search. |
361 | */ |
362 | QLocation::VisibilityScope QPlaceSearchRequest::visibilityScope() const |
363 | { |
364 | Q_D(const QPlaceSearchRequest); |
365 | return d->visibilityScope; |
366 | } |
367 | |
368 | /*! |
369 | Sets the visibility \a scope used when searching for places. |
370 | */ |
371 | void QPlaceSearchRequest::setVisibilityScope(QLocation::VisibilityScope scope) |
372 | { |
373 | Q_D(QPlaceSearchRequest); |
374 | d->visibilityScope = scope; |
375 | } |
376 | |
377 | /*! |
378 | Returns the relevance hint of the request. The hint is given to the provider |
379 | to help but not dictate the ranking of results. For example providing a distance hint |
380 | may give closer places a higher ranking but it doesn't necessarily mean |
381 | that he results will be ordered strictly according to distance. |
382 | */ |
383 | QPlaceSearchRequest::RelevanceHint QPlaceSearchRequest::relevanceHint() const |
384 | { |
385 | Q_D(const QPlaceSearchRequest); |
386 | return d->relevanceHint; |
387 | } |
388 | |
389 | /*! |
390 | Sets the relevance \a hint to be used when searching for a place. |
391 | */ |
392 | void QPlaceSearchRequest::setRelevanceHint(QPlaceSearchRequest::RelevanceHint hint) |
393 | { |
394 | Q_D(QPlaceSearchRequest); |
395 | d->relevanceHint = hint; |
396 | } |
397 | |
398 | /*! |
399 | Returns the maximum number of search results to retrieve. |
400 | |
401 | A negative value for limit means that it is undefined. It is left up to the backend |
402 | provider to choose an appropriate number of results to return. The default limit is -1. |
403 | */ |
404 | int QPlaceSearchRequest::limit() const |
405 | { |
406 | Q_D(const QPlaceSearchRequest); |
407 | return d->limit; |
408 | } |
409 | |
410 | /*! |
411 | Set the maximum number of search results to retrieve to \a limit. |
412 | */ |
413 | void QPlaceSearchRequest::setLimit(int limit) |
414 | { |
415 | Q_D(QPlaceSearchRequest); |
416 | d->limit = limit; |
417 | } |
418 | |
419 | /*! |
420 | Clears the search request. |
421 | */ |
422 | void QPlaceSearchRequest::clear() |
423 | { |
424 | Q_D(QPlaceSearchRequest); |
425 | d->clear(); |
426 | } |
427 | |
428 | inline QPlaceSearchRequestPrivate *QPlaceSearchRequest::d_func() |
429 | { |
430 | return static_cast<QPlaceSearchRequestPrivate *>(d_ptr.data()); |
431 | } |
432 | |
433 | inline const QPlaceSearchRequestPrivate *QPlaceSearchRequest::d_func() const |
434 | { |
435 | return static_cast<const QPlaceSearchRequestPrivate *>(d_ptr.constData()); |
436 | } |
437 | |
438 | QT_END_NAMESPACE |
439 | |