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 <[email protected]>
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 <[email protected]>
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 
24 namespace 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 */
38 class 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 
43 public:
44  /**
45  Constructs an empty custom properties instance.
46  */
48 
49  /**
50  Copy constructor.
51  @param other is the one to copy.
52  */
53  CustomProperties(const CustomProperties &other);
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 
169 protected:
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 
184 private:
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 */
194 KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalendarCore::CustomProperties &properties);
195 
196 /**
197  Initializes the @p properties object from the @p stream.
198 */
199 KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalendarCore::CustomProperties &properties);
200 
201 }
202 
203 #endif
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Alarm serializer.
Definition: alarm.cpp:820
Namespace for all KCalendarCore types.
Definition: alarm.h:36
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
Alarm deserializer.
Definition: alarm.cpp:833
A class to manage custom calendar properties.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 21 2023 04:00:45 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.