1 | /* |
2 | This file is part of the kcalcore library. |
3 | |
4 | Copyright (c) 2002,2006,2010 David Jarvie <djarvie@kde.org> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | /** |
22 | @file |
23 | This file is part of the API for handling calendar data and |
24 | defines the CustomProperties class. |
25 | |
26 | @author David Jarvie \<djarvie@kde.org\> |
27 | */ |
28 | |
29 | #ifndef KCALCORE_CUSTOMPROPERTIES_H |
30 | #define KCALCORE_CUSTOMPROPERTIES_H |
31 | |
32 | #include "kcalcore_export.h" |
33 | |
34 | #include <QtCore/QMap> |
35 | #include <QtCore/QString> |
36 | |
37 | namespace KCalCore { |
38 | |
39 | /** |
40 | @brief |
41 | A class to manage custom calendar properties. |
42 | |
43 | This class represents custom calendar properties. |
44 | It is used as a base class for classes which represent calendar components. |
45 | A custom property name written by the kcalcore library has the form X-KDE-APP-KEY |
46 | where APP represents the application name, and KEY distinguishes individual |
47 | properties for the application. |
48 | In keeping with RFC2445, property names must be composed only of the |
49 | characters A-Z, a-z, 0-9 and '-'. |
50 | */ |
51 | class KCALCORE_EXPORT CustomProperties |
52 | { |
53 | friend KCALCORE_EXPORT QDataStream &operator<<(QDataStream &s, |
54 | const KCalCore::CustomProperties &properties); |
55 | friend KCALCORE_EXPORT QDataStream &operator>>(QDataStream &s, |
56 | KCalCore::CustomProperties &properties); |
57 | public: |
58 | /** |
59 | Constructs an empty custom properties instance. |
60 | */ |
61 | CustomProperties(); |
62 | |
63 | /** |
64 | Copy constructor. |
65 | @param other is the one to copy. |
66 | */ |
67 | CustomProperties(const CustomProperties &other); |
68 | |
69 | /** |
70 | Destructor. |
71 | */ |
72 | virtual ~CustomProperties(); |
73 | |
74 | /** |
75 | Compare this with @p properties for equality. |
76 | @param properties is the one to compare. |
77 | @warning The comparison is not polymorphic. |
78 | */ |
79 | bool operator==(const CustomProperties &properties) const; |
80 | |
81 | /** |
82 | Create or modify a custom calendar property. |
83 | |
84 | @param app Application name as it appears in the custom property name. |
85 | @param key Property identifier specific to the application. |
86 | @param value The property's value. A call with a value of QString() |
87 | will be ignored. |
88 | @see removeCustomProperty(). |
89 | */ |
90 | void setCustomProperty(const QByteArray &app, const QByteArray &key, |
91 | const QString &value); |
92 | |
93 | /** |
94 | Delete a custom calendar property. |
95 | |
96 | @param app Application name as it appears in the custom property name. |
97 | @param key Property identifier specific to the application. |
98 | @see setCustomProperty(). |
99 | */ |
100 | void removeCustomProperty(const QByteArray &app, const QByteArray &key); |
101 | |
102 | /** |
103 | Return the value of a custom calendar property. |
104 | |
105 | @param app Application name as it appears in the custom property name. |
106 | @param key Property identifier specific to the application. |
107 | @return Property value, or QString() if (and only if) the property |
108 | does not exist. |
109 | */ |
110 | QString customProperty(const QByteArray &app, const QByteArray &key) const; |
111 | |
112 | /** |
113 | Validate and return the full name of a custom calendar property. |
114 | |
115 | @param app Application name as it appears in the custom property name. |
116 | @param key Property identifier specific to the application. |
117 | @return Full property name, or empty string if it would contain invalid |
118 | characters |
119 | */ |
120 | static QByteArray customPropertyName(const QByteArray &app, const QByteArray &key); |
121 | |
122 | /** |
123 | Create or modify a non-KDE or non-standard custom calendar property. |
124 | |
125 | @param name Full property name |
126 | @param value The property's value. A call with a value of QString() |
127 | will be ignored. |
128 | @param parameters The formatted list of parameters for the |
129 | property. They should be formatted as RFC specifies, that is, |
130 | KEY=VALUE;KEY2=VALUE2. We're mostly concerned about passing them |
131 | through as-is albeit they can be of course parsed if need be. |
132 | @see removeNonKDECustomProperty(). |
133 | */ |
134 | void setNonKDECustomProperty(const QByteArray &name, const QString &value, |
135 | const QString ¶meters = QString()); |
136 | |
137 | /** |
138 | Delete a non-KDE or non-standard custom calendar property. |
139 | |
140 | @param name Full property name |
141 | @see setNonKDECustomProperty(). |
142 | */ |
143 | void removeNonKDECustomProperty(const QByteArray &name); |
144 | |
145 | /** |
146 | Return the value of a non-KDE or non-standard custom calendar property. |
147 | |
148 | @param name Full property name |
149 | @return Property value, or QString() if (and only if) the property |
150 | does not exist. |
151 | */ |
152 | QString nonKDECustomProperty(const QByteArray &name) const; |
153 | |
154 | /** |
155 | Return the parameters of a non-KDE or non-standard custom |
156 | calendar property. |
157 | |
158 | @param name Full property name |
159 | @return The parameters for the given property. Empty string is |
160 | returned if none are set. |
161 | */ |
162 | QString nonKDECustomPropertyParameters(const QByteArray &name) const; |
163 | |
164 | /** |
165 | Initialise the alarm's custom calendar properties to the specified |
166 | key/value pairs. |
167 | @param properties is a QMap of property key/value pairs. |
168 | @see customProperties(). |
169 | */ |
170 | void setCustomProperties(const QMap<QByteArray, QString> &properties); |
171 | |
172 | /** |
173 | Returns all custom calendar property key/value pairs. |
174 | @see setCustomProperties(). |
175 | */ |
176 | QMap<QByteArray, QString> customProperties() const; |
177 | |
178 | /** |
179 | Assignment operator. |
180 | @warning The assignment is not polymorphic. |
181 | @param other is the CustomProperty to assign. |
182 | */ |
183 | CustomProperties &operator=(const CustomProperties &other); |
184 | |
185 | protected: |
186 | /** |
187 | Called before a custom property will be changed. |
188 | The default implementation does nothing: override in derived classes |
189 | to perform change processing. |
190 | */ |
191 | virtual void customPropertyUpdate(); |
192 | |
193 | /** |
194 | Called when a custom property has been changed. |
195 | The default implementation does nothing: override in derived classes |
196 | to perform change processing. |
197 | */ |
198 | virtual void customPropertyUpdated(); |
199 | |
200 | /** |
201 | @copydoc |
202 | IncidenceBase::virtual_hook() |
203 | */ |
204 | virtual void virtual_hook(int id, void *data); |
205 | |
206 | private: |
207 | //@cond PRIVATE |
208 | class Private; |
209 | Private *const d; |
210 | //@endcond |
211 | }; |
212 | |
213 | /** |
214 | Serializes the @p properties object into the @p stream. |
215 | */ |
216 | KCALCORE_EXPORT QDataStream &operator<<(QDataStream &stream, |
217 | const KCalCore::CustomProperties &properties); |
218 | |
219 | /** |
220 | Initializes the @p properties object from the @p stream. |
221 | */ |
222 | KCALCORE_EXPORT QDataStream &operator>>(QDataStream &stream, |
223 | KCalCore::CustomProperties &properties); |
224 | |
225 | } |
226 | |
227 | #endif |
228 | |