Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qdeclarativesearchsuggestionmodel.cpp
Go to the documentation of this file.
1// Copyright (C) 2015 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
6
7#include <QtQml/QQmlInfo>
8#include <QtLocation/QGeoServiceProvider>
9
10#include <qplacemanager.h>
11#include <qplacesearchrequest.h>
12#include <qplacesearchsuggestionreply.h>
13
15
16/*!
17 \qmltype PlaceSearchSuggestionModel
18 \nativetype QDeclarativeSearchSuggestionModel
19 \inqmlmodule QtLocation
20 \ingroup qml-QtLocation5-places
21 \ingroup qml-QtLocation5-places-models
22 \since QtLocation 5.5
23
24 \brief Provides access to search term suggestions.
25
26 The PlaceSearchSuggestionModel can be used to provide search term suggestions as the user enters their
27 search term. The properties of this model should match that of the \l PlaceSearchModel, which
28 will be used to perform the actual search query, to ensure that the search suggestion results are
29 relevant.
30
31 There are two ways of accessing the data provided by this model, either through the
32 \l suggestions property or through views and delegates. The latter is the preferred
33 method.
34
35 The \l offset and \l limit properties can be used to access paged suggestions. When the
36 \l offset and \l limit properties are set the suggestions between \l offset and
37 (\l offset + \l limit - 1) will be returned. Support for paging may vary
38 from plugin to plugin.
39
40 The model returns data for the following roles:
41
42 \table
43 \header
44 \li Role
45 \li Type
46 \li Description
47 \row
48 \li suggestion
49 \li string
50 \li Suggested search term.
51 \endtable
52
53 The following example shows how to use the PlaceSearchSuggestionModel to get suggested search terms
54 from a partial search term. The \l searchArea is set to match what would be used to perform the
55 actual place search with \l PlaceSearchModel.
56
57 \snippet declarative/places.qml QtQuick import
58 \snippet declarative/maps.qml QtLocation import
59 \codeline
60 \snippet declarative/places.qml SearchSuggestionModel
61
62 \sa PlaceSearchModel, {QPlaceManager}
63*/
64
65/*!
66 \qmlproperty Plugin PlaceSearchSuggestionModel::plugin
67
68 This property holds the provider \l Plugin which will be used to perform the search.
69*/
70
71/*!
72 \qmlproperty geoshape PlaceSearchSuggestionModel::searchArea
73
74 This property holds the search area. Search suggestion results returned by the model will be
75 relevant to the given search area.
76
77 If this property is set to a \l {geocircle} its
78 \l {geocircle}{radius} property may be left unset, in which case the \l Plugin
79 will choose an appropriate radius for the search.
80*/
81
82/*!
83 \qmlproperty int PlaceSearchSuggestionModel::offset
84
85 This property holds the index of the first item in the model.
86
87 \sa limit
88*/
89
90/*!
91 \qmlproperty int PlaceSearchSuggestionModel::limit
92
93 This property holds the limit of the number of items that will be returned.
94
95 \sa offset
96*/
97
98/*!
99 \qmlproperty enum PlaceSearchSuggestionModel::status
100
101 This property holds the status of the model. It can be one of:
102
103 \table
104 \row
105 \li PlaceSearchSuggestionModel.Null
106 \li No search query has been executed. The model is empty.
107 \row
108 \li PlaceSearchSuggestionModel.Ready
109 \li The search query has completed, and the results are available.
110 \row
111 \li PlaceSearchSuggestionModel.Loading
112 \li A search query is currently being executed.
113 \row
114 \li PlaceSearchSuggestionModel.Error
115 \li An error occurred when executing the previous search query.
116 \endtable
117*/
118
119/*!
120 \qmlmethod void PlaceSearchSuggestionModel::update()
121
122 Updates the model based on the provided query parameters. The model will be populated with a
123 list of search suggestions for the partial \l searchTerm and \l searchArea. If the \l plugin
124 supports it, other parameters such as \l limit and \l offset may be specified. \c update()
125 submits the set of parameters to the \l plugin to process.
126
127
128 While the model is updating the \l status of the model is set to
129 \c PlaceSearchSuggestionModel.Loading. If the model is successfully updated, the \l status is
130 set to \c PlaceSearchSuggestionModel.Ready, while if it unsuccessfully completes, the \l status
131 is set to \c PlaceSearchSuggestionModel.Error and the model cleared.
132
133 This example shows use of the model
134 \code
135 PlaceSeachSuggestionModel {
136 id: model
137 plugin: backendPlugin
138 searchArea: QtPositioning.circle(QtPositioning.coordinate(10, 10))
139 ...
140 }
141
142 MouseArea {
143 ...
144 onClicked: {
145 model.searchTerm = "piz"
146 model.searchArea.center.latitude = -27.5;
147 model.searchArea.cetner.longitude = 153;
148 model.update();
149 }
150 }
151 \endcode
152
153 A more detailed example can be found in the in
154 \l {Places (QML)#Presenting-Search-Suggestions}{Places (QML)} example.
155
156 \sa cancel(), status
157*/
158
159/*!
160 \qmlmethod void PlaceSearchSuggestionModel::cancel()
161
162 Cancels an ongoing search suggestion operation immediately and sets the model
163 status to PlaceSearchSuggestionModel.Ready. The model retains any search
164 suggestions it had before the operation was started.
165
166 If an operation is not ongoing, invoking cancel() has no effect.
167
168 \sa update(), status
169*/
170
171/*!
172 \qmlmethod void PlaceSearchSuggestionModel::reset()
173
174 Resets the model. All search suggestions are cleared, any outstanding requests are aborted and
175 possible errors are cleared. Model status will be set to PlaceSearchSuggestionModel.Null.
176*/
177
178
179/*!
180 \qmlmethod string QtLocation::PlaceSearchSuggestionModel::errorString() const
181
182 This read-only property holds the textual presentation of the latest search suggestion model error.
183 If no error has occurred, or if the model was cleared, an empty string is returned.
184
185 An empty string may also be returned if an error occurred which has no associated
186 textual representation.
187*/
188
189QDeclarativeSearchSuggestionModel::QDeclarativeSearchSuggestionModel(QObject *parent)
190: QDeclarativeSearchModelBase(parent)
191{
192}
193
194QDeclarativeSearchSuggestionModel::~QDeclarativeSearchSuggestionModel()
195{
196}
197
198/*!
199 \qmlproperty string PlaceSearchSuggestionModel::searchTerm
200
201 This property holds the partial search term used in query.
202*/
203QString QDeclarativeSearchSuggestionModel::searchTerm() const
204{
205 return m_request.searchTerm();
206}
207
208void QDeclarativeSearchSuggestionModel::setSearchTerm(const QString &searchTerm)
209{
210 if (m_request.searchTerm() == searchTerm)
211 return;
212
213 m_request.setSearchTerm(searchTerm);
214 emit searchTermChanged();
215}
216
217/*!
218 \qmlproperty stringlist PlaceSearchSuggestionModel::suggestions
219
220 This property holds the list of predicted search terms that the model currently has.
221*/
222QStringList QDeclarativeSearchSuggestionModel::suggestions() const
223{
224 return m_suggestions;
225}
226
227/*!
228 \internal
229*/
230void QDeclarativeSearchSuggestionModel::clearData(bool suppressSignal)
231{
232 QDeclarativeSearchModelBase::clearData(suppressSignal);
233
234 if (!m_suggestions.isEmpty()) {
235 m_suggestions.clear();
236
237 if (!suppressSignal)
238 emit suggestionsChanged();
239 }
240}
241
242/*!
243 \internal
244*/
245int QDeclarativeSearchSuggestionModel::rowCount(const QModelIndex &parent) const
246{
247 Q_UNUSED(parent);
248
249 return m_suggestions.count();
250}
251
252/*!
253 \internal
254*/
255QVariant QDeclarativeSearchSuggestionModel::data(const QModelIndex &index, int role) const
256{
257 if (!index.isValid())
258 return QVariant();
259
260 if (index.row() >= rowCount(index.parent()) || index.row() < 0)
261 return QVariant();
262
263 switch (role) {
264 case Qt::DisplayRole:
265 case SearchSuggestionRole:
266 return m_suggestions.at(index.row());
267 }
268
269 return QVariant();
270}
271
272QHash<int, QByteArray> QDeclarativeSearchSuggestionModel::roleNames() const
273{
274 QHash<int, QByteArray> roleNames = QDeclarativeSearchModelBase::roleNames();
275 roleNames.insert(SearchSuggestionRole, "suggestion");
276 return roleNames;
277}
278
279/*!
280 \internal
281*/
282void QDeclarativeSearchSuggestionModel::queryFinished()
283{
284 if (!m_reply)
285 return;
286
287 QPlaceReply *reply = m_reply;
288 m_reply = nullptr;
289
290 int initialCount = m_suggestions.count();
291 beginResetModel();
292
293 clearData(true);
294
295 QPlaceSearchSuggestionReply *suggestionReply = qobject_cast<QPlaceSearchSuggestionReply *>(reply);
296 m_suggestions = suggestionReply->suggestions();
297
298 if (initialCount != m_suggestions.count())
299 emit suggestionsChanged();
300
301 endResetModel();
302
303 if (suggestionReply->error() != QPlaceReply::NoError)
304 setStatus(Error, suggestionReply->errorString());
305 else
306 setStatus(Ready);
307
308
309 reply->deleteLater();
310}
311
312/*!
313 \internal
314*/
315QPlaceReply *QDeclarativeSearchSuggestionModel::sendQuery(QPlaceManager *manager,
316 const QPlaceSearchRequest &request)
317{
318 return manager->searchSuggestions(request);
319}
320
321QT_END_NAMESPACE