1 | /* |
2 | This file is part of the kcal 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 KCAL_CUSTOMPROPERTIES_H |
30 | #define KCAL_CUSTOMPROPERTIES_H |
31 | |
32 | #include "kcal_export.h" |
33 | |
34 | #include <QtCore/QString> |
35 | #include <QtCore/QMap> |
36 | #include <QtCore/QByteArray> |
37 | |
38 | namespace KCal { |
39 | |
40 | /** |
41 | @brief |
42 | A class to manage custom calendar properties. |
43 | |
44 | This class represents custom calendar properties. |
45 | It is used as a base class for classes which represent calendar components. |
46 | A custom property name written by the kcal library has the form X-KDE-APP-KEY |
47 | where APP represents the application name, and KEY distinguishes individual |
48 | properties for the application. |
49 | In keeping with RFC2445, property names must be composed only of the |
50 | characters A-Z, a-z, 0-9 and '-'. |
51 | */ |
52 | class KCAL_DEPRECATED_EXPORT CustomProperties |
53 | { |
54 | public: |
55 | /** |
56 | Constructs an empty custom properties instance. |
57 | */ |
58 | CustomProperties(); |
59 | |
60 | /** |
61 | Copy constructor. |
62 | @param other is the one to copy. |
63 | */ |
64 | CustomProperties( const CustomProperties &other ); |
65 | |
66 | /** |
67 | Destructor. |
68 | */ |
69 | virtual ~CustomProperties(); |
70 | |
71 | /** |
72 | Compare this with @p properties for equality. |
73 | @param properties is the one to compare. |
74 | |
75 | @warning The comparison is not polymorphic. |
76 | */ |
77 | // KDE5: make protected to prevent accidental usage |
78 | bool operator==( const CustomProperties &properties ) const; |
79 | |
80 | /** |
81 | Create or modify a custom calendar property. |
82 | |
83 | @param app Application name as it appears in the custom property name. |
84 | @param key Property identifier specific to the application. |
85 | @param value The property's value. A call with a value of QString() |
86 | will be ignored. |
87 | @see removeCustomProperty(). |
88 | */ |
89 | void setCustomProperty( const QByteArray &app, const QByteArray &key, |
90 | const QString &value ); |
91 | |
92 | /** |
93 | Delete a custom calendar property. |
94 | |
95 | @param app Application name as it appears in the custom property name. |
96 | @param key Property identifier specific to the application. |
97 | @see setCustomProperty(). |
98 | */ |
99 | void removeCustomProperty( const QByteArray &app, const QByteArray &key ); |
100 | |
101 | /** |
102 | Return the value of a custom calendar property. |
103 | |
104 | @param app Application name as it appears in the custom property name. |
105 | @param key Property identifier specific to the application. |
106 | @return Property value, or QString() if (and only if) the property |
107 | does not exist. |
108 | */ |
109 | QString customProperty( const QByteArray &app, const QByteArray &key ) const; |
110 | |
111 | /** |
112 | Validate and return the full name of a custom calendar property. |
113 | |
114 | @param app Application name as it appears in the custom property name. |
115 | @param key Property identifier specific to the application. |
116 | @return Full property name, or empty string if it would contain invalid |
117 | characters |
118 | |
119 | @since 4.5 |
120 | */ |
121 | static QByteArray customPropertyName( const QByteArray &app, const QByteArray &key ); |
122 | |
123 | /** |
124 | Create or modify a non-KDE or non-standard custom calendar property. |
125 | |
126 | @param name Full property name |
127 | @param value The property's value. A call with a value of QString() |
128 | will be ignored. |
129 | @see removeNonKDECustomProperty(). |
130 | */ |
131 | void setNonKDECustomProperty( const QByteArray &name, const QString &value ); |
132 | |
133 | /** |
134 | Delete a non-KDE or non-standard custom calendar property. |
135 | |
136 | @param name Full property name |
137 | @see setNonKDECustomProperty(). |
138 | */ |
139 | void removeNonKDECustomProperty( const QByteArray &name ); |
140 | |
141 | /** |
142 | Return the value of a non-KDE or non-standard custom calendar property. |
143 | |
144 | @param name Full property name |
145 | @return Property value, or QString() if (and only if) the property |
146 | does not exist. |
147 | */ |
148 | QString nonKDECustomProperty( const QByteArray &name ) const; |
149 | |
150 | /** |
151 | Initialise the alarm's custom calendar properties to the specified |
152 | key/value pairs. |
153 | @param properties is a QMap of property key/value pairs. |
154 | @see customProperties(). |
155 | */ |
156 | void setCustomProperties( const QMap<QByteArray, QString> &properties ); |
157 | |
158 | /** |
159 | Returns all custom calendar property key/value pairs. |
160 | @see setCustomProperties(). |
161 | */ |
162 | QMap<QByteArray, QString> customProperties() const; |
163 | |
164 | /** |
165 | Assignment operator. |
166 | |
167 | @warning The assignment is not polymorphic. |
168 | */ |
169 | // KDE5: make protected to prevent accidental usage |
170 | CustomProperties &operator=( const CustomProperties &other ); |
171 | |
172 | protected: |
173 | /** |
174 | Called when a custom property has been changed. |
175 | The default implementation does nothing: override in derived classes |
176 | to perform change processing. |
177 | */ |
178 | virtual void customPropertyUpdated() {} |
179 | |
180 | private: |
181 | //@cond PRIVATE |
182 | class Private; |
183 | Private *const d; |
184 | //@endcond |
185 | }; |
186 | |
187 | } |
188 | |
189 | #endif |
190 | |