49 |
49 |
50 /*! |
50 /*! |
51 \class QVersitDocument |
51 \class QVersitDocument |
52 \brief The QVersitDocument class is a container for a list of versit properties. |
52 \brief The QVersitDocument class is a container for a list of versit properties. |
53 \ingroup versit |
53 \ingroup versit |
|
54 \inmodule QtVersit |
54 |
55 |
55 A vCard is represented in abstract form as a QVersitDocument that consists of a number of |
56 A vCard is represented in abstract form as a QVersitDocument that consists of a number of |
56 properties such as a name (N), a telephone number (TEL) and an email address (EMAIL), for |
57 properties such as a name (N), a telephone number (TEL) and an email address (EMAIL), for |
57 instance. Each of these properties is stored as an instance of a QVersitProperty in a |
58 instance. Each of these properties is stored as an instance of a QVersitProperty in a |
58 QVersitDocument. |
59 QVersitDocument. |
59 |
60 |
60 In addition to the list of properties, QVersitDocument also records the type of the Versit |
61 In addition to the list of properties, QVersitDocument also records the type of the Versit |
61 document via the VersitType field. This enum describes the format in which the document is to be |
62 document in two ways. The VersitType enum describes the format in which the document is to be |
62 serialized by QVersitWriter (or the format from which it was read by QVersitReader), and should |
63 serialized by QVersitWriter (or the format from which it was read by QVersitReader), and should |
63 not be used to infer any semantics about the document data. |
64 not be used to infer any semantics about the document data. The componentType field is a string |
|
65 corresponding directly to the value of the BEGIN line in a document. For example, for a vCard, |
|
66 this will always be the string "VCARD"; for an iCalendar, it could be "VCALENDAR", "VEVENT", |
|
67 "VTODO", "VJOURNAL", "VALARM" or "VTIMEZONE". |
|
68 |
|
69 As well as properties, a QVersitDocument can hold other documents. For iCalendar, this is how |
|
70 a single VCALENDAR document can compose documents of type VEVENT, VTODO, etc. |
|
71 |
|
72 For example, for the following iCalendar: |
|
73 \code |
|
74 BEGIN:VCALENDAR |
|
75 VERSION:2.0 |
|
76 BEGIN:VEVENT |
|
77 SUMMARY:Christmas |
|
78 DTSTART:20001225 |
|
79 END:VEVENT |
|
80 END:VCALENDAR |
|
81 \endcode |
|
82 |
|
83 This can be represented as a QVersitDocument of with componentType VCALENDAR and versitType |
|
84 ICalendar20Type. It contains no properties (note: the VERSION property is not stored explicitly |
|
85 as a property) and one sub-document. The sub-document has componentType VEVENT and versitType |
|
86 ICalendar20Type, and contains two properties. |
64 |
87 |
65 QVersitDocument supports implicit sharing. |
88 QVersitDocument supports implicit sharing. |
66 |
89 |
67 \sa QVersitProperty |
90 \sa QVersitProperty |
68 */ |
91 */ |
69 |
92 |
70 /*! |
93 /*! |
71 \enum QVersitDocument::VersitType |
94 \enum QVersitDocument::VersitType |
72 This enum describes a versit document type and version. |
95 This enum describes a Versit document serialization format and version. |
73 \value InvalidType No type specified or a document with an invalid type was parsed |
96 \value InvalidType No type specified or a document with an invalid type was parsed |
74 \value VCard21Type vCard version 2.1 |
97 \value VCard21Type vCard version 2.1 |
75 \value VCard30Type vCard version 3.0 |
98 \value VCard30Type vCard version 3.0 |
|
99 \value VCard40Type vCard version 4.0 |
|
100 \value ICalendar20Type iCalendar version 2.0 |
76 */ |
101 */ |
77 |
102 |
78 /*! Constructs a new empty document */ |
103 /*! Constructs a new empty document */ |
79 QVersitDocument::QVersitDocument() : d(new QVersitDocumentPrivate()) |
104 QVersitDocument::QVersitDocument() : d(new QVersitDocumentPrivate()) |
80 { |
105 { |
107 |
132 |
108 /*! Returns true if this is equal to \a other; false otherwise. */ |
133 /*! Returns true if this is equal to \a other; false otherwise. */ |
109 bool QVersitDocument::operator==(const QVersitDocument& other) const |
134 bool QVersitDocument::operator==(const QVersitDocument& other) const |
110 { |
135 { |
111 return d->mVersitType == other.d->mVersitType && |
136 return d->mVersitType == other.d->mVersitType && |
112 d->mProperties == other.d->mProperties; |
137 d->mProperties == other.d->mProperties && |
|
138 d->mSubDocuments == other.d->mSubDocuments && |
|
139 d->mComponentType == other.d->mComponentType; |
113 } |
140 } |
114 |
141 |
115 /*! Returns true if this is not equal to \a other; false otherwise. */ |
142 /*! Returns true if this is not equal to \a other; false otherwise. */ |
116 bool QVersitDocument::operator!=(const QVersitDocument& other) const |
143 bool QVersitDocument::operator!=(const QVersitDocument& other) const |
117 { |
144 { |
120 |
147 |
121 /*! Returns the hash value for \a key. */ |
148 /*! Returns the hash value for \a key. */ |
122 uint qHash(const QVersitDocument &key) |
149 uint qHash(const QVersitDocument &key) |
123 { |
150 { |
124 int hash = QT_PREPEND_NAMESPACE(qHash)(key.type()); |
151 int hash = QT_PREPEND_NAMESPACE(qHash)(key.type()); |
|
152 hash += QT_PREPEND_NAMESPACE(qHash)(key.componentType()); |
125 foreach (const QVersitProperty& property, key.properties()) { |
153 foreach (const QVersitProperty& property, key.properties()) { |
126 hash += qHash(property); |
154 hash += qHash(property); |
127 } |
155 } |
|
156 foreach (const QVersitDocument& nested, key.subDocuments()) { |
|
157 hash += qHash(nested); |
|
158 } |
128 return hash; |
159 return hash; |
129 } |
160 } |
130 |
161 |
131 #ifndef QT_NO_DEBUG_STREAM |
162 #ifndef QT_NO_DEBUG_STREAM |
132 QDebug operator<<(QDebug dbg, const QVersitDocument& document) |
163 QDebug operator<<(QDebug dbg, const QVersitDocument& document) |
133 { |
164 { |
134 dbg.nospace() << "QVersitDocument(" << document.type() << ')'; |
165 dbg.nospace() << "QVersitDocument(" << document.type() << ", " << document.componentType() << ')'; |
135 foreach (const QVersitProperty& property, document.properties()) { |
166 foreach (const QVersitProperty& property, document.properties()) { |
136 dbg.space() << '\n' << property; |
167 dbg.space() << '\n' << property; |
137 } |
168 } |
|
169 foreach (const QVersitDocument& nested, document.subDocuments()) { |
|
170 dbg.space() << '\n' << nested; |
|
171 } |
138 return dbg.maybeSpace(); |
172 return dbg.maybeSpace(); |
139 } |
173 } |
140 #endif |
174 #endif |
141 |
175 |
142 /*! |
176 /*! |
143 * Sets the versit document type to \a type. |
177 * Sets the versit document type to \a type. This determines the format in which the document is |
|
178 * to be serialized. |
144 */ |
179 */ |
145 void QVersitDocument::setType(VersitType type) |
180 void QVersitDocument::setType(VersitType type) |
146 { |
181 { |
147 d->mVersitType = type; |
182 d->mVersitType = type; |
148 } |
183 } |
151 * Gets the versit document type. |
186 * Gets the versit document type. |
152 */ |
187 */ |
153 QVersitDocument::VersitType QVersitDocument::type() const |
188 QVersitDocument::VersitType QVersitDocument::type() const |
154 { |
189 { |
155 return d->mVersitType; |
190 return d->mVersitType; |
|
191 } |
|
192 |
|
193 /*! |
|
194 * Sets the versit component type to \a componentType (eg. VCARD, VCALENDAR, VEVENT, etc.) |
|
195 */ |
|
196 void QVersitDocument::setComponentType(QString componentType) |
|
197 { |
|
198 d->mComponentType = componentType; |
|
199 } |
|
200 |
|
201 /*! |
|
202 * Gets the versit component type |
|
203 */ |
|
204 QString QVersitDocument::componentType() const |
|
205 { |
|
206 return d->mComponentType; |
156 } |
207 } |
157 |
208 |
158 /*! |
209 /*! |
159 * Add \a property to the list of contained versit properties. |
210 * Add \a property to the list of contained versit properties. |
160 * The property is appended as the last property of the list. |
211 * The property is appended as the last property of the list. |
189 * and resetting the codec to the default. |
240 * and resetting the codec to the default. |
190 */ |
241 */ |
191 void QVersitDocument::clear() |
242 void QVersitDocument::clear() |
192 { |
243 { |
193 d->mProperties.clear(); |
244 d->mProperties.clear(); |
|
245 d->mSubDocuments.clear(); |
194 d->mVersitType = QVersitDocument::InvalidType; |
246 d->mVersitType = QVersitDocument::InvalidType; |
|
247 } |
|
248 |
|
249 /*! |
|
250 * Adds \a subdocument to the Versit document. |
|
251 */ |
|
252 void QVersitDocument::addSubDocument(const QVersitDocument& subdocument) |
|
253 { |
|
254 d->mSubDocuments.append(subdocument); |
|
255 } |
|
256 |
|
257 /*! |
|
258 * Sets the list of subdocuments to \a documents. |
|
259 */ |
|
260 void QVersitDocument::setSubDocuments(const QList<QVersitDocument>& documents) |
|
261 { |
|
262 d->mSubDocuments = documents; |
|
263 } |
|
264 |
|
265 /*! |
|
266 * Returns the list of subdocuments contained within this Versit document. |
|
267 */ |
|
268 QList<QVersitDocument> QVersitDocument::subDocuments() const |
|
269 { |
|
270 return d->mSubDocuments; |
195 } |
271 } |
196 |
272 |
197 /*! |
273 /*! |
198 * Gets the list of the contained versit properties. |
274 * Gets the list of the contained versit properties. |
199 * Note that the actual properties cannot be modified using the copy. |
275 * Note that the actual properties cannot be modified using the copy. |