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
38namespace 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*/
52class 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