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
48QT_BEGIN_NAMESPACE_DOCGALLERY
49
50class QGalleryQueryRequestPrivate : public QGalleryAbstractRequestPrivate
51{
52public:
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
163QGalleryQueryRequest::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
173QGalleryQueryRequest::QGalleryQueryRequest(QAbstractGallery *gallery, QObject *parent)
174 : QGalleryAbstractRequest(*new QGalleryQueryRequestPrivate(gallery), parent)
175{
176}
177
178/*!
179 Destroys a gallery query request.
180*/
181
182QGalleryQueryRequest::~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
192QStringList QGalleryQueryRequest::propertyNames() const
193{
194 return d_func()->propertyNames;
195}
196
197void 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
223QStringList QGalleryQueryRequest::sortPropertyNames() const
224{
225 return d_func()->sortPropertyNames;
226}
227
228void 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
254bool QGalleryQueryRequest::autoUpdate() const
255{
256 return d_func()->autoUpdate;
257}
258
259void 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
280int QGalleryQueryRequest::offset() const
281{
282 return d_func()->offset;
283}
284
285void 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
307int QGalleryQueryRequest::limit() const
308{
309 return d_func()->limit;
310}
311
312void 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
334QString QGalleryQueryRequest::rootType() const
335{
336 return d_func()->rootType;
337}
338
339void 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
360QVariant QGalleryQueryRequest::rootItem() const
361{
362 return d_func()->rootItem;
363}
364
365void 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
387QGalleryQueryRequest::Scope QGalleryQueryRequest::scope() const
388{
389 return d_func()->scope;
390}
391
392void 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
416QGalleryFilter QGalleryQueryRequest::filter() const
417{
418 return d_func()->filter;
419}
420
421void 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
441QGalleryResultSet *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
457int 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
466QGalleryProperty::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
475QVariant::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
484int 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
495QVariant 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
506QUrl 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
517QString 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
528QList<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
539QVariant 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
551bool 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
561QVariant 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
573bool 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
585int 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
605bool 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
619bool 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
631bool 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
643bool 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
655bool 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
666bool QGalleryQueryRequest::isValid() const
667{
668 return d_func()->internalResultSet->isValid();
669}
670
671/*!
672 \reimp
673*/
674
675void 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
694QT_END_NAMESPACE_DOCGALLERY
695

source code of qtdocgallery/src/gallery/qgalleryqueryrequest.cpp