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 QtOrganizer module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL21$
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 2.1 or version 3 as published by the Free
20** Software Foundation and appearing in the file LICENSE.LGPLv21 and
21** LICENSE.LGPLv3 included in the packaging of this file. Please review the
22** following information to ensure the GNU Lesser General Public License
23** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
24** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25**
26** As a special exception, The Qt Company gives you certain additional
27** rights. These rights are described in The Qt Company LGPL Exception
28** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29**
30** $QT_END_LICENSE$
31**
32****************************************************************************/
33
34#include "qorganizercollection.h"
35#include "qorganizercollection_p.h"
36
37#ifndef QT_NO_DATASTREAM
38#include <QtCore/qdatastream.h>
39#endif
40#ifndef QT_NO_DEBUG_STREAM
41#include <QtCore/qdebug.h>
42#endif
43
44QT_BEGIN_NAMESPACE_ORGANIZER
45
46/*!
47 \class QOrganizerCollection
48 \brief The QOrganizerCollection class represents a collection of items in a manager.
49 \inmodule QtOrganizer
50 \ingroup organizer-main
51
52 A collection has an ID and optionally some metadata, and contains zero or more items.
53 Each different manager will have different requirements before a collection may be saved
54 in it. Some managers do not allow collections to be saved at all, while others may require
55 a collection to have some minimal amount of meta data defined in it prior to save.
56 For example, most managers require a valid value for the QOrganizerCollection::KeyName
57 meta data key to be set prior to save.
58
59 Every QOrganizerItem is contained within a collection when stored in a manager.
60 To save an item in a collection, the client should call QOrganizerItem::setCollectionId()
61 on the item, passing in the ID of the destination collection as the argument, and then
62 save the item in the manager. To move an item from one collection to another, the client
63 must fetch the item from the manager, set the collection ID in the item to the ID of the
64 collection to which the client wishes the item to be moved, and then resave the item in the
65 manager. That is, the collection which an item is part of is treated as a property of the
66 item.
67 */
68
69/*!
70 \enum QOrganizerCollection::MetaDataKey
71
72 This enumeration describes the key of the organizer collection metadata.
73
74 \value KeyName This metadata describes the name of the collection.
75 \value KeyDescription This metadata gives a description of the collection.
76 \value KeyColor This metadata describes the color of the collection.
77 \value KeySecondaryColor This metadata describes the secondary color of the collection.
78 \value KeyImage This metadata describes the image of the collection.
79 \value KeyExtended This is an extened metadata, which is stored as a QVariantMap.
80 */
81
82/*!
83 Constructs a new collection.
84 */
85QOrganizerCollection::QOrganizerCollection()
86 : d(new QOrganizerCollectionData)
87{
88}
89
90/*!
91 Cleans up any memory in use by the collection.
92 */
93QOrganizerCollection::~QOrganizerCollection()
94{
95}
96
97/*!
98 Constructs a new copy of the \a other collection.
99 */
100QOrganizerCollection::QOrganizerCollection(const QOrganizerCollection &other)
101 : d(other.d)
102{
103}
104
105/*!
106 Assigns this collection to be equal to the \a other collection.
107 */
108QOrganizerCollection &QOrganizerCollection::operator=(const QOrganizerCollection &other)
109{
110 d = other.d;
111 return *this;
112}
113
114/*!
115 Returns true if the collection is the same as that of the \a other collection, false if either
116 the ID or any of the stored metadata are not the same.
117 */
118bool QOrganizerCollection::operator==(const QOrganizerCollection &other) const
119{
120 if (d == other.d)
121 return true;
122
123 if (d->m_id != other.d->m_id
124 || d->m_metaData.size() != other.d->m_metaData.size()) {
125 return false;
126 }
127
128 QMap<QOrganizerCollection::MetaDataKey, QVariant>::const_iterator i = d->m_metaData.constBegin();
129 while (i != d->m_metaData.constEnd()) {
130 if (i.value() != other.d->m_metaData.value(akey: i.key()))
131 return false;
132 ++i;
133 }
134
135 return true;
136}
137
138/*!
139 \fn QOrganizerCollection::operator!=(const QOrganizerCollection &other) const
140
141 Returns true if the collection is not the same as the \a other collection.
142 */
143
144/*!
145 Returns the ID of the collection.
146 */
147QOrganizerCollectionId QOrganizerCollection::id() const
148{
149 return d->m_id;
150}
151
152/*!
153 Sets the ID of the collection to \a id.
154
155 If the ID is set to a null (default-constructed) ID, saving the collection will cause the manager
156 to save the collection as a new collection.
157 */
158void QOrganizerCollection::setId(const QOrganizerCollectionId &id)
159{
160 d->m_id = id;
161}
162
163/*!
164 Sets the metadata of the collection to be \a metaData.
165 */
166void QOrganizerCollection::setMetaData(const QMap<QOrganizerCollection::MetaDataKey, QVariant> &metaData)
167{
168 d->m_metaData = metaData;
169}
170
171/*!
172 Returns the meta data of the collection.
173 */
174QMap<QOrganizerCollection::MetaDataKey, QVariant> QOrganizerCollection::metaData() const
175{
176 return d->m_metaData;
177}
178
179/*!
180 Sets the meta data of the collection for the given \a key to the given \a value.
181 */
182void QOrganizerCollection::setMetaData(MetaDataKey key, const QVariant &value)
183{
184 d->m_metaData.insert(akey: key, avalue: value);
185}
186
187/*!
188 Sets the value of the extended metadata with the given \a key to \a value.
189 */
190void QOrganizerCollection::setExtendedMetaData(const QString &key, const QVariant &value)
191{
192 QVariantMap variantMap = d->m_metaData.value(akey: QOrganizerCollection::KeyExtended).toMap();
193 variantMap.insert(akey: key, avalue: value);
194 d->m_metaData.insert(akey: QOrganizerCollection::KeyExtended, avalue: variantMap);
195}
196
197/*!
198 Returns the value of extended metadata with the given \a key.
199 */
200QVariant QOrganizerCollection::extendedMetaData(const QString &key) const
201{
202 return d->m_metaData.value(akey: QOrganizerCollection::KeyExtended).toMap().value(akey: key);
203}
204
205/*!
206 Returns the meta data of the collection for the given \a key.
207 */
208QVariant QOrganizerCollection::metaData(MetaDataKey key) const
209{
210 return d->m_metaData.value(akey: key);
211}
212
213/*!
214 \relates QOrganizerCollection
215 Returns the hash value for \a key.
216 */
217Q_ORGANIZER_EXPORT uint qHash(const QOrganizerCollection &key)
218{
219 uint hash = qHash(id: key.id());
220 QMap<QOrganizerCollection::MetaDataKey, QVariant>::const_iterator i = key.d->m_metaData.constBegin();
221 while (i != key.d->m_metaData.constEnd()) {
222 if (i.key() == QOrganizerCollection::KeyExtended) {
223 QVariantMap variantMap = i.value().toMap();
224 QVariantMap::const_iterator j = variantMap.constBegin();
225 while (j != variantMap.constEnd()) {
226 hash += QT_PREPEND_NAMESPACE(qHash)(key: j.key()) + QT_PREPEND_NAMESPACE(qHash)(key: j.value().toString());
227 ++j;
228 }
229 } else {
230 hash += QT_PREPEND_NAMESPACE(qHash)(key: i.key()) + QT_PREPEND_NAMESPACE(qHash)(key: i.value().toString());
231 }
232 ++i;
233 }
234 return hash;
235}
236
237#ifndef QT_NO_DEBUG_STREAM
238/*!
239 \relates QOrganizerCollection
240 Streams the \a collection to the given debug stream \a dbg, and returns the stream.
241 */
242QDebug operator<<(QDebug dbg, const QOrganizerCollection& collection)
243{
244 dbg.nospace() << "QOrganizerCollection(id=" << collection.id();
245
246 QMap<QOrganizerCollection::MetaDataKey, QVariant> metaData = collection.metaData();
247 QMap<QOrganizerCollection::MetaDataKey, QVariant>::const_iterator i = metaData.constBegin();
248 while (i != metaData.constEnd()) {
249 dbg.nospace() << ", " << i.key() << '=' << i.value();
250 ++i;
251 }
252 dbg.nospace() << ')';
253 return dbg.maybeSpace();
254}
255#endif // QT_NO_DEBUG_STREAM
256
257#ifndef QT_NO_DATASTREAM
258/*!
259 \relates QOrganizerCollection
260 Writes \a collection to the stream \a out.
261 */
262QDataStream &operator<<(QDataStream &out, const QOrganizerCollection &collection)
263{
264 quint8 formatVersion = 1;
265 return out << formatVersion
266 << collection.id().toString()
267 << collection.metaData();
268}
269
270/*!
271 \relates QOrganizerCollection
272 Reads an organizer collection from stream \a in into \a collection.
273 */
274QDataStream &operator>>(QDataStream &in, QOrganizerCollection &collection)
275{
276 quint8 formatVersion;
277 in >> formatVersion;
278 if (formatVersion == 1) {
279 QString idString;
280 QMap<int, QVariant> values;
281 in >> idString >> values;
282
283 collection = QOrganizerCollection();
284 collection.setId(QOrganizerCollectionId::fromString(idString));
285
286 QMap<int, QVariant>::const_iterator i = values.constBegin();
287 while (i != values.constEnd()) {
288 collection.setMetaData(key: static_cast<QOrganizerCollection::MetaDataKey>(i.key()), value: i.value());
289 ++i;
290 }
291 } else {
292 in.setStatus(QDataStream::ReadCorruptData);
293 }
294 return in;
295}
296#endif // QT_NO_DATASTREAM
297
298QT_END_NAMESPACE_ORGANIZER
299

source code of qtpim/src/organizer/qorganizercollection.cpp