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
47QT_BEGIN_NAMESPACE
48
49QPlaceSearchRequestPrivate::QPlaceSearchRequestPrivate()
50: QSharedData(),
51 visibilityScope(QLocation::UnspecifiedVisibility),
52 relevanceHint(QPlaceSearchRequest::UnspecifiedHint),
53 limit(-1)
54{
55}
56
57QPlaceSearchRequestPrivate::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
72QPlaceSearchRequestPrivate::~QPlaceSearchRequestPrivate()
73{
74}
75
76QPlaceSearchRequestPrivate &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
94bool 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
108void 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
122const QPlaceSearchRequestPrivate *QPlaceSearchRequestPrivate::get(const QPlaceSearchRequest &request)
123{
124 return request.d_ptr.constData();
125}
126
127QPlaceSearchRequestPrivate *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*/
178QPlaceSearchRequest::QPlaceSearchRequest()
179 : d_ptr(new QPlaceSearchRequestPrivate())
180{
181}
182
183/*!
184 Constructs a copy of \a other.
185*/
186QPlaceSearchRequest::QPlaceSearchRequest(const QPlaceSearchRequest &other)
187 : d_ptr(other.d_ptr)
188{
189}
190
191/*!
192 Destroys the request object.
193*/
194QPlaceSearchRequest::~QPlaceSearchRequest()
195{
196}
197
198/*!
199 Assigns \a other to this search request and returns a reference
200 to this search request.
201*/
202QPlaceSearchRequest &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*/
215bool 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*/
225bool 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*/
234QString QPlaceSearchRequest::searchTerm() const
235{
236 Q_D(const QPlaceSearchRequest);
237 return d->searchTerm;
238}
239
240/*!
241 Sets the search \a term.
242*/
243void 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*/
254QList<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*/
265void 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*/
281void 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*/
291QGeoShape 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*/
300void 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*/
310QString 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*/
319void 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*/
330QVariant 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*/
351void 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*/
362QLocation::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*/
371void 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*/
383QPlaceSearchRequest::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*/
392void 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*/
404int 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*/
413void QPlaceSearchRequest::setLimit(int limit)
414{
415 Q_D(QPlaceSearchRequest);
416 d->limit = limit;
417}
418
419/*!
420 Clears the search request.
421*/
422void QPlaceSearchRequest::clear()
423{
424 Q_D(QPlaceSearchRequest);
425 d->clear();
426}
427
428inline QPlaceSearchRequestPrivate *QPlaceSearchRequest::d_func()
429{
430 return static_cast<QPlaceSearchRequestPrivate *>(d_ptr.data());
431}
432
433inline const QPlaceSearchRequestPrivate *QPlaceSearchRequest::d_func() const
434{
435 return static_cast<const QPlaceSearchRequestPrivate *>(d_ptr.constData());
436}
437
438QT_END_NAMESPACE
439

source code of qtlocation/src/location/places/qplacesearchrequest.cpp