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