KCalendarCore

event.h
Go to the documentation of this file.
1 /*
2  This file is part of the kcalcore library.
3 
4  SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <[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 Event class.
12 
13  @author Cornelius Schumacher <[email protected]>
14 */
15 #ifndef KCALCORE_EVENT_H
16 #define KCALCORE_EVENT_H
17 
18 #include "incidence.h"
19 #include "kcalendarcore_export.h"
20 
21 #include <QTimeZone>
22 
23 namespace KCalendarCore
24 {
25 
26 class EventPrivate;
27 
28 /**
29  @brief
30  This class provides an Event in the sense of RFC2445.
31 */
32 class KCALENDARCORE_EXPORT Event : public Incidence
33 {
34  Q_GADGET
35  Q_PROPERTY(QDateTime dtEnd READ dtEnd WRITE setDtEnd)
36  Q_PROPERTY(KCalendarCore::Event::Transparency transparency READ transparency WRITE setTransparency)
37 public:
38  /**
39  The different Event transparency types.
40  */
41  enum Transparency {
42  Opaque, /**< Event appears in free/busy time */
43  Transparent, /**< Event does @b not appear in free/busy time */
44  };
45  Q_ENUM(Transparency)
46 
47  /**
48  A shared pointer to an Event object.
49  */
51 
52  /**
53  List of events.
54  */
55  typedef QVector<Ptr> List;
56 
57  ///@cond PRIVATE
58  // needed for Akonadi polymorphic payload support
59  typedef Incidence SuperClass;
60  ///@endcond
61 
62  /**
63  Constructs an event.
64  */
65  Event();
66 
67  /**
68  Copy constructor.
69  @param other is the event to copy.
70  */
71  Event(const Event &other);
72 
73  /**
74  Costructs an event out of an incidence
75  This constructs allows to make it easy to create an event from a todo.
76  @param other is the incidence to copy.
77  @since 4.14
78  */
79  Event(const Incidence &other); // krazy:exclude=explicit (copy ctor)
80 
81  /**
82  Destroys the event.
83  */
84  ~Event() override;
85 
86  /**
87  @copydoc
88  IncidenceBase::type()
89  */
90  Q_REQUIRED_RESULT IncidenceType type() const override;
91 
92  /**
93  @copydoc
94  IncidenceBase::typeStr()
95  */
96  Q_REQUIRED_RESULT QByteArray typeStr() const override;
97 
98  /**
99  Returns an exact copy of this Event. The caller owns the returned object.
100  */
101  Event *clone() const override;
102 
103  /**
104  Sets the incidence starting date/time.
105 
106  @param dt is the starting date/time.
107  @see IncidenceBase::dtStart().
108  */
109  void setDtStart(const QDateTime &dt) override;
110 
111  /**
112  Sets the event end date and time.
113  Important note for all day events: the end date is inclusive,
114  the event will still occur during dtEnd(). When serializing to iCalendar
115  DTEND will be dtEnd()+1, because the RFC states that DTEND is exclusive.
116  @param dtEnd is a QDateTime specifying when the event ends.
117  @see dtEnd(), dateEnd().
118  */
119  void setDtEnd(const QDateTime &dtEnd);
120 
121  /**
122  Returns the event end date and time.
123  Important note for all day events: the returned end date is inclusive,
124  the event will still occur during dtEnd(). When serializing to iCalendar
125  DTEND will be dtEnd()+1, because the RFC states that DTEND is exclusive.
126  @see setDtEnd().
127  */
128  virtual QDateTime dtEnd() const;
129 
130  /**
131  Returns the date when the event ends. This might be different from
132  dtEnd().date, since the end date/time is non-inclusive. So timed events
133  ending at 0:00 have their end date on the day before.
134  */
135  Q_REQUIRED_RESULT QDate dateEnd() const;
136 
137  /**
138  Returns whether the event has an end date/time.
139  */
140  Q_REQUIRED_RESULT bool hasEndDate() const;
141 
142  /**
143  Returns true if the event spans multiple days, otherwise return false.
144 
145  For recurring events, it returns true if the first occurrence spans multiple days,
146  otherwise returns false. Other occurrences might have a different span due to day light
147  savings changes.
148 
149  @param zone If set, looks if the event is multiday for the given zone.
150  If not set, looks if event this multiday for its zone.
151  */
152  Q_REQUIRED_RESULT bool isMultiDay(const QTimeZone &zone = {}) const;
153 
154  /**
155  @copydoc
156  IncidenceBase::shiftTimes()
157  */
158  void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone) override;
159 
160  /**
161  Sets the event's time transparency level.
162  @param transparency is the event Transparency level.
163  */
164  void setTransparency(Transparency transparency);
165 
166  /**
167  Returns the event's time transparency level.
168  */
169  Q_REQUIRED_RESULT Transparency transparency() const;
170 
171  /**
172  Sets the duration of this event.
173  @param duration is the event Duration.
174  */
175  void setDuration(const Duration &duration) override;
176 
177  /**
178  @copydoc
179  IncidenceBase::setAllDay().
180  */
181  void setAllDay(bool allDay) override;
182 
183  /**
184  @copydoc
185  IncidenceBase::dateTime()
186  */
187  Q_REQUIRED_RESULT QDateTime dateTime(DateTimeRole role) const override;
188 
189  /**
190  @copydoc
191  IncidenceBase::setDateTime()
192  */
193  void setDateTime(const QDateTime &dateTime, DateTimeRole role) override;
194 
195  /**
196  @copydoc
197  IncidenceBase::mimeType()
198  */
199  Q_REQUIRED_RESULT QLatin1String mimeType() const override;
200 
201  /**
202  @copydoc
203  Incidence::iconName()
204  */
205  Q_REQUIRED_RESULT QLatin1String iconName(const QDateTime &recurrenceId = {}) const override;
206 
207  /**
208  @copydoc
209  Incidence::supportsGroupwareCommunication()
210  */
211  Q_REQUIRED_RESULT bool supportsGroupwareCommunication() const override;
212 
213  /**
214  Returns the Akonadi specific sub MIME type of a KCalendarCore::Event.
215  */
216  Q_REQUIRED_RESULT static QLatin1String eventMimeType();
217 
218 protected:
219  /**
220  Compares two events for equality.
221  @param event is the event to compare.
222  */
223  bool equals(const IncidenceBase &event) const override;
224 
225  /**
226  @copydoc
227  IncidenceBase::assign()
228  */
229  IncidenceBase &assign(const IncidenceBase &other) override;
230 
231  /**
232  @copydoc
233  IncidenceBase::virtual_hook()
234  */
235  void virtual_hook(VirtualHook id, void *data) override;
236 
237 private:
238  /**
239  @copydoc
240  IncidenceBase::accept()
241  */
242  bool accept(Visitor &v, const IncidenceBase::Ptr &incidence) override;
243 
244  /**
245  Disabled, otherwise could be dangerous if you subclass Event.
246  Use IncidenceBase::operator= which is safe because it calls
247  virtual function assign().
248  @param other is another Event object to assign to this one.
249  */
250  Event &operator=(const Event &other);
251 
252  // For polymorphic serialization
253  void serialize(QDataStream &out) const override;
254  void deserialize(QDataStream &in) override;
255 
256  //@cond PRIVATE
257  Q_DECLARE_PRIVATE(Event)
258 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 91)
259  KCALENDARCORE_DEPRECATED_VERSION(5, 91, "Do not use")
260  EventPrivate *const _ = nullptr; // TODO KF6 remove. ABI compatibility hack.
261 #endif
262  //@endcond
263 };
264 
265 } // namespace KCalendarCore
266 
267 //@cond PRIVATE
268 Q_DECLARE_TYPEINFO(KCalendarCore::Event::Ptr, Q_MOVABLE_TYPE);
269 Q_DECLARE_METATYPE(KCalendarCore::Event::Ptr)
270 Q_DECLARE_METATYPE(KCalendarCore::Event *)
271 //@endcond
272 
273 #endif
Represents a span of time measured in seconds or days.
Definition: duration.h:43
Namespace for all KCalendarCore types.
Definition: alarm.h:36
Provides the abstract base class common to non-FreeBusy (Events, To-dos, Journals) calendar component...
Definition: incidence.h:59
@ Transparent
Event does not appear in free/busy time.
Definition: event.h:43
QSharedPointer< IncidenceBase > Ptr
A shared pointer to an IncidenceBase.
IncidenceType
The different types of incidences, per RFC2445.
@ Opaque
Event appears in free/busy time.
Definition: event.h:42
Transparency
The different Event transparency types.
Definition: event.h:41
This class provides an Event in the sense of RFC2445.
Definition: event.h:32
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 03:57:31 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.