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 "qgalleryresultset_p.h"
43
44#include "qgalleryresource.h"
45
46QT_BEGIN_NAMESPACE_DOCGALLERY
47
48/*!
49 \class QGalleryResultSet
50
51 \ingroup gallery
52
53 \inmodule QtDocGallery
54
55 \brief The QGalleryResultSet class provides a gallery response which returns
56 the results of a query.
57
58 Implementations of QGalleryResultSet are used to return a result set in
59 response to a QGalleryAbstractRequest. A QGalleryResultSet provides
60 functions for accessing identifying information and meta-data of items
61 queried from a gallery.
62
63 Only one item in a result set can be accessed at a time, so before
64 information about an item can be accessed it must be selected using one of
65 the fetch() functions. When a new index is selected the result set will
66 emit the currentIndexChanged() signal, and when the currently selected item
67 changes the currentItemChanged() signal will be emitted. If the
68 currentIndex() contains a gallery item isValid() will return true, otherwise
69 it will return false. Information identifying the current item in a result
70 set can be accessed using the itemId(), itemUrl() and itemType() functions.
71
72 For each meta-data property that can be addressed by a result set it will
73 provide a unique key which queried by passing the property's name to the
74 propertyKey() function. Passing this key to the metaData() function will
75 return the current item's value for that property. Some result sets may
76 contain editable meta-data values which can be changed using the
77 setMetaData() function. The attributes of a meta-data property such as
78 whether it's writable can be queried from propertyAttributes() and the
79 type of value that will returned by metaData() can be queried using
80 propertyType().
81
82 Whenever items are added or removed from a result set the itemsInserted()
83 and itemsRemoved() signals will be emitted identifying where and how many
84 items were changed. If the meta-data of one or more items in a result set
85 changes the metaDataChanged() signal will be emitted.
86*/
87
88/*!
89 Constructs a new result set.
90
91 The \a parent is passed to QGalleryAbstractResponse.
92*/
93
94QGalleryResultSet::QGalleryResultSet(QObject *parent)
95 : QGalleryAbstractResponse(*new QGalleryResultSetPrivate, parent)
96{
97}
98
99
100/*!
101 \internal
102*/
103
104QGalleryResultSet::QGalleryResultSet(QGalleryResultSetPrivate &dd, QObject *parent)
105 : QGalleryAbstractResponse(dd, parent)
106{
107}
108
109/*!
110 Destroys a result set.
111*/
112
113QGalleryResultSet::~QGalleryResultSet()
114{
115
116}
117
118/*!
119 \fn QGalleryResultSet::propertyKey(const QString &property) const
120
121 Returns a positive integer key for a \a property name, or a negative
122 integer if the property name is invalid.
123*/
124
125/*!
126 \fn QGalleryResultSet::propertyAttributes(int key) const
127
128 Returns the attributes of the property identified by \a key.
129*/
130
131/*!
132 \fn QGalleryResultSet::propertyType(int key) const
133
134 Returns the type of the property identified by \a key.
135*/
136
137/*!
138 \fn QGalleryResultSet::itemCount() const
139
140 Returns the number of items in a result set.
141*/
142
143/*!
144 Returns true if a result set is currently positioned on a valid item;
145 otherwise returns false.
146
147 \sa currentIndex()
148*/
149
150bool QGalleryResultSet::isValid() const
151{
152 const int index = currentIndex();
153
154 return index >= 0 && index < itemCount();
155}
156
157/*!
158 \fn QGalleryResultSet::itemId() const
159
160 Returns the ID of the item a result set is currently positioned on.
161
162 \sa currentIndex()
163*/
164
165/*!
166 \fn QGalleryResultSet::itemUrl() const
167
168 Returns the URL of the item a result set is currently positioned on.
169
170 \sa currentIndex(), resources()
171*/
172
173/*!
174 \fn QGalleryResultSet::itemType() const
175
176 Returns the type of the item a result set is currently positioned on.
177
178 \sa currentIndex()
179*/
180
181/*!
182 Returns the resources of the item of a result set is currently positioned
183 on.
184
185 The default implementation returns a single resource with the URL of the
186 current item, or an empty list if the current item doesn't have a valid
187 URL.
188
189 \sa currentIndex(), itemUrl()
190*/
191
192QList<QGalleryResource> QGalleryResultSet::resources() const
193{
194 QList<QGalleryResource> resources;
195
196 const QUrl url = itemUrl();
197
198 if (!url.isEmpty())
199 resources.append(t: QGalleryResource(url));
200
201 return resources;
202}
203
204/*!
205 \fn QGalleryResultSet::metaData(int key) const
206
207 Returns the meta-data value of the current item for \a key.
208*/
209
210/*!
211 \fn QGalleryResultSet::setMetaData(int key, const QVariant &value)
212
213 Sets the meta-data \a value of the current item for \a key.
214
215 Returns true if the value was changed successfully; otherwise returns
216 false.
217*/
218
219/*!
220 \fn QGalleryResultSet::currentIndex() const
221
222 Returns the index of the item a result set currently positioned on.
223
224 \sa fetch()
225*/
226
227/*!
228 \fn QGalleryResultSet::fetch(int index)
229
230 Moves the current position of a result set to an arbitrary \a index.
231
232 Returns true if the result set is positioned on a valid item on return;
233 otherwise returns false.
234*/
235
236/*!
237 Moves the current position of the result set to the next item in the set.
238
239 Returns true if the result set is positioned on a valid item on return;
240 otherwise returns false.
241*/
242
243bool QGalleryResultSet::fetchNext()
244{
245 return fetch(index: currentIndex() + 1);
246}
247
248/*!
249 Moves the current position of the result set to the previous item in the
250 set.
251
252 Returns true if the result set is positioned on a valid item on return;
253 otherwise returns false.
254*/
255
256bool QGalleryResultSet::fetchPrevious()
257{
258 return fetch(index: currentIndex() - 1);
259}
260
261/*!
262 Moves the current position of the result set to the first item in the set.
263
264 Returns true if the result set is positioned on a valid item on return;
265 otherwise returns false.
266*/
267
268bool QGalleryResultSet::fetchFirst()
269{
270 return fetch(index: 0);
271}
272
273/*!
274 Moves the current position of the result set to the last item in the set.
275
276 Returns true if the result set is positioned on a valid item on return;
277 otherwise returns false.
278*/
279
280bool QGalleryResultSet::fetchLast()
281{
282 return fetch(index: itemCount() - 1);
283}
284
285/*!
286 \fn QGalleryResultSet::currentItemChanged()
287
288 Signals that the item the result set is positioned on has changed.
289*/
290
291/*!
292 \fn QGalleryResultSet::currentIndexChanged(int index)
293
294 Signals that a result set has been repositioned on a new \a index.
295*/
296
297/*!
298 \fn QGalleryResultSet::itemsInserted(int index, int count)
299
300 Signals that \a count items have been inserted into a result set at
301 \a index.
302*/
303
304/*!
305 \fn QGalleryResultSet::itemsRemoved(int index, int count)
306
307 Signals that \a count items have been removed from a result set at
308 \a index.
309*/
310
311/*!
312 \fn QGalleryResultSet::itemsMoved(int from, int to, int count)
313
314 Signals that \a count items have been moved \a from an existing index \a to
315 a new index.
316*/
317
318/*!
319 \fn QGalleryResultSet::metaDataChanged(int index, int count, const QList<int> &keys)
320
321 Signals that the meta-data identified by \a keys of \a count items starting
322 at \a index has changed.
323*/
324
325#include "moc_qgalleryresultset.cpp"
326
327QT_END_NAMESPACE_DOCGALLERY
328

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