KCalendarCore

customproperties.h
Go to the documentation of this file.
1/*
2 This file is part of the kcalcore library.
3
4 SPDX-FileCopyrightText: 2002, 2006, 2010 David Jarvie <djarvie@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8/**
9 @file
10 This file is part of the API for handling calendar data and
11 defines the CustomProperties class.
12
13 @author David Jarvie <djarvie@kde.org>
14*/
15
16#ifndef KCALCORE_CUSTOMPROPERTIES_H
17#define KCALCORE_CUSTOMPROPERTIES_H
18
19#include "kcalendarcore_export.h"
20
21#include <QMap>
22#include <QString>
23
24namespace KCalendarCore
25{
26/**
27 @brief
28 A class to manage custom calendar properties.
29
30 This class represents custom calendar properties.
31 It is used as a base class for classes which represent calendar components.
32 A custom property name written by the kcalcore library has the form X-KDE-APP-KEY
33 where APP represents the application name, and KEY distinguishes individual
34 properties for the application.
35 In keeping with RFC2445, property names must be composed only of the
36 characters A-Z, a-z, 0-9 and '-'.
37*/
38class KCALENDARCORE_EXPORT CustomProperties
39{
40 friend KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalendarCore::CustomProperties &properties);
41 friend KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &s, KCalendarCore::CustomProperties &properties);
42
43public:
44 /**
45 Constructs an empty custom properties instance.
46 */
48
49 /**
50 Copy constructor.
51 @param other is the one to copy.
52 */
54
55 /**
56 Destructor.
57 */
58 virtual ~CustomProperties();
59
60 /**
61 Compare this with @p properties for equality.
62 @param properties is the one to compare.
63 @warning The comparison is not polymorphic.
64 */
65 bool operator==(const CustomProperties &properties) const;
66
67 /**
68 Create or modify a custom calendar property.
69
70 @param app Application name as it appears in the custom property name.
71 @param key Property identifier specific to the application.
72 @param value The property's value. A call with a value of QString()
73 will be ignored.
74 @see removeCustomProperty().
75 */
76 void setCustomProperty(const QByteArray &app, const QByteArray &key, const QString &value);
77
78 /**
79 Delete a custom calendar property.
80
81 @param app Application name as it appears in the custom property name.
82 @param key Property identifier specific to the application.
83 @see setCustomProperty().
84 */
85 void removeCustomProperty(const QByteArray &app, const QByteArray &key);
86
87 /**
88 Return the value of a custom calendar property.
89
90 @param app Application name as it appears in the custom property name.
91 @param key Property identifier specific to the application.
92 @return Property value, or QString() if (and only if) the property
93 does not exist.
94 */
95 Q_REQUIRED_RESULT QString customProperty(const QByteArray &app, const QByteArray &key) const;
96
97 /**
98 Validate and return the full name of a custom calendar property.
99
100 @param app Application name as it appears in the custom property name.
101 @param key Property identifier specific to the application.
102 @return Full property name, or empty string if it would contain invalid
103 characters
104 */
105 Q_REQUIRED_RESULT static QByteArray customPropertyName(const QByteArray &app, const QByteArray &key);
106
107 /**
108 Create or modify a non-KDE or non-standard custom calendar property.
109
110 @param name Full property name
111 @param value The property's value. A call with a value of QString()
112 will be ignored.
113 @param parameters The formatted list of parameters for the
114 property. They should be formatted as RFC specifies, that is,
115 KEY=VALUE;KEY2=VALUE2. We're mostly concerned about passing them
116 through as-is albeit they can be of course parsed if need be.
117 @see removeNonKDECustomProperty().
118 */
119 void setNonKDECustomProperty(const QByteArray &name, const QString &value, const QString &parameters = QString());
120
121 /**
122 Delete a non-KDE or non-standard custom calendar property.
123
124 @param name Full property name
125 @see setNonKDECustomProperty().
126 */
127 void removeNonKDECustomProperty(const QByteArray &name);
128
129 /**
130 Return the value of a non-KDE or non-standard custom calendar property.
131
132 @param name Full property name
133 @return Property value, or QString() if (and only if) the property
134 does not exist.
135 */
136 Q_REQUIRED_RESULT QString nonKDECustomProperty(const QByteArray &name) const;
137
138 /**
139 Return the parameters of a non-KDE or non-standard custom
140 calendar property.
141
142 @param name Full property name
143 @return The parameters for the given property. Empty string is
144 returned if none are set.
145 */
146 Q_REQUIRED_RESULT QString nonKDECustomPropertyParameters(const QByteArray &name) const;
147
148 /**
149 Initialise the alarm's custom calendar properties to the specified
150 key/value pairs.
151 @param properties is a QMap of property key/value pairs.
152 @see customProperties().
153 */
154 void setCustomProperties(const QMap<QByteArray, QString> &properties);
155
156 /**
157 Returns all custom calendar property key/value pairs.
158 @see setCustomProperties().
159 */
160 Q_REQUIRED_RESULT QMap<QByteArray, QString> customProperties() const;
161
162 /**
163 Assignment operator.
164 @warning The assignment is not polymorphic.
165 @param other is the CustomProperty to assign.
166 */
167 CustomProperties &operator=(const CustomProperties &other);
168
169protected:
170 /**
171 Called before a custom property will be changed.
172 The default implementation does nothing: override in derived classes
173 to perform change processing.
174 */
175 virtual void customPropertyUpdate();
176
177 /**
178 Called when a custom property has been changed.
179 The default implementation does nothing: override in derived classes
180 to perform change processing.
181 */
182 virtual void customPropertyUpdated();
183
184private:
185 //@cond PRIVATE
186 class Private;
187 Private *const d;
188 //@endcond
189};
190
191/**
192 Serializes the @p properties object into the @p stream.
193*/
194KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalendarCore::CustomProperties &properties);
195
196/**
197 Initializes the @p properties object from the @p stream.
198*/
199KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalendarCore::CustomProperties &properties);
200
201}
202
203#endif
A class to manage custom calendar properties.
friend KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &s, const KCalendarCore::CustomProperties &properties)
Serializes the properties object into the stream.
friend KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &s, KCalendarCore::CustomProperties &properties)
Initializes the properties object from the stream.
Namespace for all KCalendarCore types.
Definition alarm.h:37
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
Alarm deserializer.
Definition alarm.cpp:833
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Alarm serializer.
Definition alarm.cpp:820
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:51:09 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.