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 | |
46 | QT_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 | |
94 | QGalleryResultSet::QGalleryResultSet(QObject *parent) |
95 | : QGalleryAbstractResponse(*new QGalleryResultSetPrivate, parent) |
96 | { |
97 | } |
98 | |
99 | |
100 | /*! |
101 | \internal |
102 | */ |
103 | |
104 | QGalleryResultSet::QGalleryResultSet(QGalleryResultSetPrivate &dd, QObject *parent) |
105 | : QGalleryAbstractResponse(dd, parent) |
106 | { |
107 | } |
108 | |
109 | /*! |
110 | Destroys a result set. |
111 | */ |
112 | |
113 | QGalleryResultSet::~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 | |
150 | bool 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 | |
192 | QList<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 | |
243 | bool 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 | |
256 | bool 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 | |
268 | bool 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 | |
280 | bool 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 | |
327 | QT_END_NAMESPACE_DOCGALLERY |
328 | |