1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). |
4 | ** Contact: http://www.qt-project.org/legal |
5 | ** |
6 | ** This file is part of the QtDocGallery module of the Qt Toolkit. |
7 | ** |
8 | ** $QT_BEGIN_LICENSE:LGPL$ |
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 Digia. For licensing terms and |
14 | ** conditions see http://qt.digia.com/licensing. For further information |
15 | ** use the contact form at http://qt.digia.com/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 2.1 as published by the Free Software |
20 | ** Foundation and appearing in the file LICENSE.LGPL included in the |
21 | ** packaging of this file. Please review the following information to |
22 | ** ensure the GNU Lesser General Public License version 2.1 requirements |
23 | ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
24 | ** |
25 | ** In addition, as a special exception, Digia gives you certain additional |
26 | ** rights. These rights are described in the Digia Qt LGPL Exception |
27 | ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
28 | ** |
29 | ** GNU General Public License Usage |
30 | ** Alternatively, this file may be used under the terms of the GNU |
31 | ** General Public License version 3.0 as published by the Free Software |
32 | ** Foundation and appearing in the file LICENSE.GPL included in the |
33 | ** packaging of this file. Please review the following information to |
34 | ** ensure the GNU General Public License version 3.0 requirements will be |
35 | ** met: http://www.gnu.org/copyleft/gpl.html. |
36 | ** |
37 | ** |
38 | ** $QT_END_LICENSE$ |
39 | ** |
40 | ****************************************************************************/ |
41 | |
42 | #include "qgalleryqueryrequest.h" |
43 | #include "qgalleryabstractrequest_p.h" |
44 | |
45 | #include "qgallerynullresultset_p.h" |
46 | #include "qgalleryresource.h" |
47 | |
48 | QT_BEGIN_NAMESPACE_DOCGALLERY |
49 | |
50 | class QGalleryQueryRequestPrivate : public QGalleryAbstractRequestPrivate |
51 | { |
52 | public: |
53 | QGalleryQueryRequestPrivate(QAbstractGallery *gallery) |
54 | : QGalleryAbstractRequestPrivate(gallery, QGalleryAbstractRequest::QueryRequest) |
55 | , offset(0) |
56 | , limit(0) |
57 | , scope(QGalleryQueryRequest::AllDescendants) |
58 | , autoUpdate(false) |
59 | , resultSet(0) |
60 | , internalResultSet(0) |
61 | { |
62 | internalResultSet = &nullResultSet; |
63 | } |
64 | |
65 | int offset; |
66 | int limit; |
67 | QGalleryQueryRequest::Scope scope; |
68 | bool autoUpdate; |
69 | QGalleryResultSet *resultSet; |
70 | QGalleryResultSet *internalResultSet; |
71 | QGalleryNullResultSet nullResultSet; |
72 | QStringList propertyNames; |
73 | QStringList sortPropertyNames; |
74 | QString rootType; |
75 | QVariant rootItem; |
76 | QGalleryFilter filter; |
77 | }; |
78 | |
79 | /*! |
80 | \class QGalleryQueryRequest |
81 | |
82 | \ingroup gallery |
83 | \ingroup gallery-requests |
84 | |
85 | \inmodule QtDocGallery |
86 | |
87 | \brief The QGalleryQueryRequest class provides a request for a set of |
88 | items from a gallery. |
89 | |
90 | QGalleryItemRequest executes a query which returns information about a set |
91 | gallery item of gallery items matching some query criteria. For each item |
92 | matching the query criteria the request will return an \l itemUrl, an |
93 | \l itemType, \l resources and \l {metaData()}{meta-data} values for the |
94 | properties listed in \l propertyNames. |
95 | |
96 | The \l rootType property identifies the type of gallery item the request |
97 | should return, if the root type has derivative types (i.e. an audio file is |
98 | just a special case of a regular file) these will also be included in the |
99 | result set. |
100 | |
101 | The \l rootItem property takes the ID of an item the query should only |
102 | return the children of. Depending on the \l scope of the query this may |
103 | be {AllDescendents}{all descendents} or just the {DirectDescendents} |
104 | {direct descendents} of the root item. |
105 | |
106 | The results of a query can be further limited by setting a \l filter on the |
107 | request. The request will evaluate the QGalleryFilter and only include |
108 | items with meta-data matching the expression. |
109 | |
110 | The order the results are returned in can be specified in the |
111 | sortPropertyNames property which takes an ordered list of property names. |
112 | By default properties are sorted in ascending order, but this can be |
113 | specified explicitly be prefixing the property name with a '+' character |
114 | for ascending order and a '-' character for descending order. |
115 | |
116 | If the \l autoUpdate property is true when the request is executed it will |
117 | enter an \l Idle state on finishing and will refresh the queried |
118 | information if the items matching the query change. If the gallery can't |
119 | provide updates it will instead go immediately to the \l Finished state. |
120 | Automatic updates can be canceled by calling cancel() on a idle request. |
121 | |
122 | Only one item in a query can be accessed at a time, so before |
123 | information about an item can be accessed it must be selected using one of |
124 | the fetch() functions. When a new index is selected the result set will |
125 | emit the currentIndexChanged() signal, and when the currently selected item |
126 | changes the currentItemChanged() signal will be emitted. If the |
127 | currentIndex() contains a gallery item isValid() will return true, otherwise |
128 | it will return false. Information identifying the current item in the |
129 | request can be accessed using the itemId(), itemUrl() and itemType() |
130 | functions. |
131 | |
132 | For each meta-data property returned by a query a unique key will be |
133 | provided, this cab be queried by passing the property's name to the |
134 | propertyKey() function. Passing this key to the metaData() function will |
135 | return the current item's value for that property. Some queries may return |
136 | items with editable meta-data values which can be changed using the |
137 | setMetaData() function. The attributes of a meta-data property such as |
138 | whether it's writable can be queried from propertyAttributes() and the |
139 | type of value that will returned by metaData() can be queried using |
140 | propertyType(). |
141 | |
142 | \sa QDocumentGallery, QGalleryQueryModel |
143 | */ |
144 | |
145 | /*! |
146 | \enum QGalleryQueryRequest::Scope |
147 | |
148 | Identifies the scope of query. |
149 | |
150 | \value AllDescendants The query will return all descendents of the scope |
151 | item. |
152 | \value DirectDescendants The query will return only direct descendents of |
153 | the scope item. |
154 | */ |
155 | |
156 | /*! |
157 | Constructs a new gallery query request. |
158 | |
159 | The \a parent is passed to QObject. |
160 | */ |
161 | |
162 | |
163 | QGalleryQueryRequest::QGalleryQueryRequest(QObject *parent) |
164 | : QGalleryAbstractRequest(*new QGalleryQueryRequestPrivate(0), parent) |
165 | { |
166 | } |
167 | /*! |
168 | Contructs a new query request for the given \a gallery. |
169 | |
170 | The \a parent is passed to QObject. |
171 | */ |
172 | |
173 | QGalleryQueryRequest::QGalleryQueryRequest(QAbstractGallery *gallery, QObject *parent) |
174 | : QGalleryAbstractRequest(*new QGalleryQueryRequestPrivate(gallery), parent) |
175 | { |
176 | } |
177 | |
178 | /*! |
179 | Destroys a gallery query request. |
180 | */ |
181 | |
182 | QGalleryQueryRequest::~QGalleryQueryRequest() |
183 | { |
184 | } |
185 | /*! |
186 | \property QGalleryQueryRequest::propertyNames |
187 | |
188 | \brief A list of names of meta-data properties a request should return values for. |
189 | */ |
190 | |
191 | |
192 | QStringList QGalleryQueryRequest::propertyNames() const |
193 | { |
194 | return d_func()->propertyNames; |
195 | } |
196 | |
197 | void QGalleryQueryRequest::setPropertyNames(const QStringList &names) |
198 | { |
199 | if (d_func()->propertyNames != names) { |
200 | d_func()->propertyNames = names; |
201 | |
202 | emit propertyNamesChanged(); |
203 | } |
204 | } |
205 | |
206 | /*! |
207 | \fn QGalleryQueryRequest::propertyNamesChanged(); |
208 | |
209 | Signals that the value of \l propertyNames has changed. |
210 | */ |
211 | |
212 | /*! |
213 | \property QGalleryQueryRequest::sortPropertyNames |
214 | |
215 | \brief A list of names of meta-data properties a request should sort its |
216 | results on. |
217 | |
218 | Prefixing a property name with the '+' character indicates it should be sorted |
219 | in ascending order, and a '-' character prefix indicates a descending order. |
220 | If there is no prefix ascending order is assumed. |
221 | */ |
222 | |
223 | QStringList QGalleryQueryRequest::sortPropertyNames() const |
224 | { |
225 | return d_func()->sortPropertyNames; |
226 | } |
227 | |
228 | void QGalleryQueryRequest::setSortPropertyNames(const QStringList &names) |
229 | { |
230 | if (d_func()->sortPropertyNames != names) { |
231 | d_func()->sortPropertyNames = names; |
232 | |
233 | emit sortPropertyNamesChanged(); |
234 | } |
235 | } |
236 | |
237 | /*! |
238 | \fn QGalleryQueryRequest::sortPropertyNamesChanged() |
239 | |
240 | Signals that the value of \l sortPropertyNames has changed. |
241 | */ |
242 | |
243 | /*! |
244 | \property QGalleryQueryRequest::autoUpdate |
245 | |
246 | \brief Whether a the results of a request should be updated after a request |
247 | has finished. |
248 | |
249 | If this is true the request will go into the Idle state when the request has |
250 | finished rather than returning to Inactive. |
251 | */ |
252 | |
253 | |
254 | bool QGalleryQueryRequest::autoUpdate() const |
255 | { |
256 | return d_func()->autoUpdate; |
257 | } |
258 | |
259 | void QGalleryQueryRequest::setAutoUpdate(bool enabled) |
260 | { |
261 | if (d_func()->autoUpdate != enabled) { |
262 | d_func()->autoUpdate = enabled; |
263 | |
264 | emit autoUpdateChanged(); |
265 | } |
266 | } |
267 | |
268 | /*! |
269 | \fn QGalleryQueryRequest::autoUpdateChanged() |
270 | |
271 | Signals that the value of \l autoUpdate has changed. |
272 | */ |
273 | |
274 | /*! |
275 | \property QGalleryQueryRequest::offset |
276 | |
277 | \brief the offset of the first item a query should return. |
278 | */ |
279 | |
280 | int QGalleryQueryRequest::offset() const |
281 | { |
282 | return d_func()->offset; |
283 | } |
284 | |
285 | void QGalleryQueryRequest::setOffset(int offset) |
286 | { |
287 | const int boundedOffset = qMax(a: 0, b: offset); |
288 | if (d_func()->offset != boundedOffset) { |
289 | d_func()->offset = boundedOffset; |
290 | |
291 | emit offsetChanged(); |
292 | } |
293 | } |
294 | |
295 | /*! |
296 | \fn QGalleryQueryRequest::offsetChanged() |
297 | |
298 | Signals that the value of offset has changed. |
299 | */ |
300 | |
301 | /*! |
302 | \property QGalleryQueryRequest::limit |
303 | |
304 | \brief the maximum number of items a query should return. |
305 | */ |
306 | |
307 | int QGalleryQueryRequest::limit() const |
308 | { |
309 | return d_func()->limit; |
310 | } |
311 | |
312 | void QGalleryQueryRequest::setLimit(int limit) |
313 | { |
314 | const int boundedLimit = qMax(a: 0, b: limit); |
315 | if (d_func()->limit != boundedLimit) { |
316 | d_func()->limit = boundedLimit; |
317 | |
318 | emit limitChanged(); |
319 | } |
320 | } |
321 | |
322 | /*! |
323 | \fn QGalleryQueryRequest::limitChanged() |
324 | |
325 | Signals that the value of \l limit has changed. |
326 | */ |
327 | |
328 | /*! |
329 | \property QGalleryQueryRequest::rootType |
330 | |
331 | \brief the root item type the results of a query should be restricted to. |
332 | */ |
333 | |
334 | QString QGalleryQueryRequest::rootType() const |
335 | { |
336 | return d_func()->rootType; |
337 | } |
338 | |
339 | void QGalleryQueryRequest::setRootType(const QString &itemType) |
340 | { |
341 | if (d_func()->rootType != itemType) { |
342 | d_func()->rootType = itemType; |
343 | |
344 | emit rootTypeChanged(); |
345 | } |
346 | } |
347 | |
348 | /*! |
349 | \fn QGalleryQueryRequest::rootTypeChanged() |
350 | |
351 | Signals that the value of \l rootType has changed. |
352 | */ |
353 | |
354 | /*! |
355 | \property QGalleryQueryRequest::rootItem |
356 | |
357 | \brief the ID of an item the query should return the descendents of. |
358 | */ |
359 | |
360 | QVariant QGalleryQueryRequest::rootItem() const |
361 | { |
362 | return d_func()->rootItem; |
363 | } |
364 | |
365 | void QGalleryQueryRequest::setRootItem(const QVariant &itemId) |
366 | { |
367 | if (d_func()->rootItem != itemId) { |
368 | d_func()->rootItem = itemId; |
369 | |
370 | emit rootItemChanged(); |
371 | } |
372 | } |
373 | |
374 | /*! |
375 | \fn QGalleryQueryRequest::rootItemChanged() |
376 | |
377 | Signals that the value of \l rootItem has changed. |
378 | */ |
379 | |
380 | /*! |
381 | \property QGalleryQueryRequest::scope |
382 | |
383 | \brief whether all descendants of the \l rootItem should be returned by |
384 | a request or just the direct descendants. |
385 | */ |
386 | |
387 | QGalleryQueryRequest::Scope QGalleryQueryRequest::scope() const |
388 | { |
389 | return d_func()->scope; |
390 | } |
391 | |
392 | void QGalleryQueryRequest::setScope(QGalleryQueryRequest::Scope scope) |
393 | { |
394 | if (d_func()->scope != scope) { |
395 | d_func()->scope = scope; |
396 | |
397 | emit scopeChanged(); |
398 | } |
399 | } |
400 | |
401 | /*! |
402 | \fn QGalleryQueryRequest::scopeChanged() |
403 | |
404 | Signals that the value of \l scope has changed. |
405 | */ |
406 | |
407 | /*! |
408 | \property QGalleryQueryRequest::filter |
409 | |
410 | \brief A filter identifying the items a request should return. |
411 | |
412 | If no filter is set the results of the request will be determined |
413 | by the \l rootType and \l rootItem properties. |
414 | */ |
415 | |
416 | QGalleryFilter QGalleryQueryRequest::filter() const |
417 | { |
418 | return d_func()->filter; |
419 | } |
420 | |
421 | void QGalleryQueryRequest::setFilter(const QGalleryFilter &filter) |
422 | { |
423 | if (d_func()->filter != filter) { |
424 | d_func()->filter = filter; |
425 | |
426 | emit filterChanged(); |
427 | } |
428 | } |
429 | |
430 | /*! |
431 | \fn QGalleryQueryRequest::filterChanged() |
432 | |
433 | Signals that the value of \l filter has changed. |
434 | */ |
435 | |
436 | |
437 | /*! |
438 | Returns the result set containing the results of a query. |
439 | */ |
440 | |
441 | QGalleryResultSet *QGalleryQueryRequest::resultSet() const |
442 | { |
443 | return d_func()->resultSet; |
444 | } |
445 | |
446 | /*! |
447 | \fn QGalleryQueryRequest::resultSetChanged(QGalleryResultSet *resultSet) |
448 | |
449 | Signals that the \a resultSet containing the results of a query have |
450 | changed. |
451 | */ |
452 | |
453 | /*! |
454 | Returns the key of \a property. |
455 | */ |
456 | |
457 | int QGalleryQueryRequest::propertyKey(const QString &property) const |
458 | { |
459 | return d_func()->internalResultSet->propertyKey(property); |
460 | } |
461 | |
462 | /*! |
463 | Returns the attributes of the property identified by \a key. |
464 | */ |
465 | |
466 | QGalleryProperty::Attributes QGalleryQueryRequest::propertyAttributes(int key) const |
467 | { |
468 | return d_func()->internalResultSet->propertyAttributes(key); |
469 | } |
470 | |
471 | /*! |
472 | Returns the type of the property identified by \a key. |
473 | */ |
474 | |
475 | QVariant::Type QGalleryQueryRequest::propertyType(int key) const |
476 | { |
477 | return d_func()->internalResultSet->propertyType(key); |
478 | } |
479 | |
480 | /*! |
481 | Returns the number of items returned by a query. |
482 | */ |
483 | |
484 | int QGalleryQueryRequest::itemCount() const |
485 | { |
486 | return d_func()->internalResultSet->itemCount(); |
487 | } |
488 | |
489 | /*! |
490 | \property QGalleryQueryRequest::itemId |
491 | |
492 | \brief The ID of the current item. |
493 | */ |
494 | |
495 | QVariant QGalleryQueryRequest::itemId() const |
496 | { |
497 | return d_func()->internalResultSet->itemId(); |
498 | } |
499 | |
500 | /*! |
501 | \property QGalleryQueryRequest::itemUrl |
502 | |
503 | \brief The URL of the current item. |
504 | */ |
505 | |
506 | QUrl QGalleryQueryRequest::itemUrl() const |
507 | { |
508 | return d_func()->internalResultSet->itemUrl(); |
509 | } |
510 | |
511 | /*! |
512 | \property QGalleryQueryRequest::itemType |
513 | |
514 | \brief he type of the current item. |
515 | */ |
516 | |
517 | QString QGalleryQueryRequest::itemType() const |
518 | { |
519 | return d_func()->internalResultSet->itemType(); |
520 | } |
521 | |
522 | /*! |
523 | \property QGalleryQueryRequest::resources |
524 | |
525 | \brief The resources of the current item. |
526 | */ |
527 | |
528 | QList<QGalleryResource> QGalleryQueryRequest::resources() const |
529 | { |
530 | return d_func()->internalResultSet->resources(); |
531 | } |
532 | |
533 | /*! |
534 | Returns the value of a meta-data property identified by \a key for the |
535 | current item. |
536 | */ |
537 | |
538 | |
539 | QVariant QGalleryQueryRequest::metaData(int key) const |
540 | { |
541 | return d_func()->internalResultSet->metaData(key); |
542 | } |
543 | |
544 | /*! |
545 | Sets the \a value of a meta-data property identified by \a key for the |
546 | current item. |
547 | |
548 | Returns true if the value was changed; otherwise returns false. |
549 | */ |
550 | |
551 | bool QGalleryQueryRequest::setMetaData(int key, const QVariant &value) |
552 | { |
553 | return d_func()->internalResultSet->setMetaData(key, value); |
554 | } |
555 | |
556 | /*! |
557 | Returns the value of a meta-data \a property for the current item. |
558 | */ |
559 | |
560 | |
561 | QVariant QGalleryQueryRequest::metaData(const QString &property) const |
562 | { |
563 | return d_func()->internalResultSet->metaData( |
564 | key: d_func()->internalResultSet->propertyKey(property)); |
565 | } |
566 | |
567 | /*! |
568 | Sets the \value of a meta-data \a property for the current item. |
569 | |
570 | Returns true if the value was changed; otherwise returns false. |
571 | */ |
572 | |
573 | bool QGalleryQueryRequest::setMetaData(const QString &property, const QVariant &value) |
574 | { |
575 | return d_func()->internalResultSet->setMetaData( |
576 | key: d_func()->internalResultSet->propertyKey(property), value); |
577 | } |
578 | |
579 | /*! |
580 | \property QGalleryQueryRequest::currentIndex |
581 | |
582 | \brief The index of current item. |
583 | */ |
584 | |
585 | int QGalleryQueryRequest::currentIndex() const |
586 | { |
587 | return d_func()->internalResultSet->currentIndex(); |
588 | } |
589 | |
590 | /*! |
591 | \fn QGalleryQueryRequest::currentItemChanged() |
592 | |
593 | Signals that the item the result set is positioned on has changed. |
594 | */ |
595 | |
596 | /*! |
597 | Seeks to the item at \a index. |
598 | |
599 | If \a relative is true the seek is peformed relative to the current index. |
600 | |
601 | Returns true if the position of the result set is valid after the seek; and |
602 | false otherwise. |
603 | */ |
604 | |
605 | bool QGalleryQueryRequest::seek(int index, bool relative) |
606 | { |
607 | return d_func()->internalResultSet->fetch(index: relative |
608 | ? d_func()->internalResultSet->currentIndex() + index |
609 | : index); |
610 | } |
611 | |
612 | /*! |
613 | Seeks to the next item in the result set. |
614 | |
615 | Returns true if the position of the result set is valid after the seek; and |
616 | false otherwise. |
617 | */ |
618 | |
619 | bool QGalleryQueryRequest::next() |
620 | { |
621 | return d_func()->internalResultSet->fetchNext(); |
622 | } |
623 | |
624 | /*! |
625 | Seeks to the previous item in the result set. |
626 | |
627 | Returns true if the position of the result set is valid after the seek; and |
628 | false otherwise. |
629 | */ |
630 | |
631 | bool QGalleryQueryRequest::previous() |
632 | { |
633 | return d_func()->internalResultSet->fetchPrevious(); |
634 | } |
635 | |
636 | /*! |
637 | Seeks to the first item in the result set. |
638 | |
639 | Returns true if the position of the result set is valid after the seek; and |
640 | false otherwise. |
641 | */ |
642 | |
643 | bool QGalleryQueryRequest::first() |
644 | { |
645 | return d_func()->internalResultSet->fetchFirst(); |
646 | } |
647 | |
648 | /*! |
649 | Seeks to the last item in the result set. |
650 | |
651 | Returns true if the position of the result set is valid after the seek; and |
652 | false otherwise. |
653 | */ |
654 | |
655 | bool QGalleryQueryRequest::last() |
656 | { |
657 | return d_func()->internalResultSet->fetchLast(); |
658 | } |
659 | |
660 | /*! |
661 | \property QGalleryQueryRequest::valid |
662 | |
663 | \brief Whether the result set is currently positioned on a valid item. |
664 | */ |
665 | |
666 | bool QGalleryQueryRequest::isValid() const |
667 | { |
668 | return d_func()->internalResultSet->isValid(); |
669 | } |
670 | |
671 | /*! |
672 | \reimp |
673 | */ |
674 | |
675 | void QGalleryQueryRequest::setResponse(QGalleryAbstractResponse *response) |
676 | { |
677 | Q_D(QGalleryQueryRequest); |
678 | |
679 | d->resultSet = qobject_cast<QGalleryResultSet *>(object: response); |
680 | |
681 | if (d->resultSet) { |
682 | d->internalResultSet = d->resultSet; |
683 | |
684 | connect(sender: d->resultSet, SIGNAL(currentItemChanged()), receiver: this, SIGNAL(currentItemChanged())); |
685 | } else { |
686 | d->internalResultSet = &d->nullResultSet; |
687 | } |
688 | |
689 | emit resultSetChanged(resultSet: d->resultSet); |
690 | } |
691 | |
692 | #include "moc_qgalleryqueryrequest.cpp" |
693 | |
694 | QT_END_NAMESPACE_DOCGALLERY |
695 | |