KCalendarCore

freebusy.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  SPDX-FileCopyrightText: 2004 Reinhold Kainhofer <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-or-later
8 */
9 /**
10  @file
11  This file is part of the API for handling calendar data and
12  defines the FreeBusy class.
13 
14  @author Cornelius Schumacher <[email protected]>
15  @author Reinhold Kainhofer <[email protected]>
16 */
17 
18 #ifndef KCALCORE_FREEBUSY_H
19 #define KCALCORE_FREEBUSY_H
20 
21 #include "event.h"
22 #include "freebusyperiod.h"
23 #include "incidencebase.h"
24 #include "kcalendarcore_export.h"
25 #include "period.h"
26 
27 #include <QMetaType>
28 
29 namespace KCalendarCore
30 {
31 
32 class FreeBusyPrivate;
33 
34 /**
35  @brief
36  Provides information about the free/busy time of a calendar.
37 
38  A free/busy is a collection of Periods.
39 
40  @see Period.
41 */
42 class KCALENDARCORE_EXPORT FreeBusy : public IncidenceBase
43 {
44  friend KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &s, const KCalendarCore::FreeBusy::Ptr &freebusy);
45  friend KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &s, KCalendarCore::FreeBusy::Ptr &freebusy);
46 
47 public:
48  /**
49  A shared pointer to a FreeBusy object.
50  */
52 
53  /**
54  List of FreeBusy objects.
55  */
56  typedef QVector<Ptr> List;
57 
58  /**
59  Constructs an free/busy without any periods.
60  */
61  FreeBusy();
62 
63  /**
64  Copy constructor.
65  @param other is the free/busy to copy.
66  */
67  FreeBusy(const FreeBusy &other);
68 
69  /**
70  Constructs a free/busy from a list of periods.
71  @param busyPeriods is a list of periods.
72  */
73  explicit FreeBusy(const Period::List &busyPeriods);
74 
75  /**
76  Constructs a free/busy from a list of periods.
77  @param busyPeriods is a list of periods.
78  */
79  explicit FreeBusy(const FreeBusyPeriod::List &busyPeriods);
80 
81  /**
82  Constructs a free/busy from a single period.
83 
84  @param start is the start date/time of the period.
85  @param end is the end date/time of the period.
86  */
87  FreeBusy(const QDateTime &start, const QDateTime &end);
88 
89  /**
90  Constructs a freebusy for a specified list of events given a single period.
91 
92  @param events list of events.
93  @param start is the start date/time of the period.
94  @param end is the end date/time of the period.
95  */
96  FreeBusy(const Event::List &events, const QDateTime &start, const QDateTime &end);
97 
98  /**
99  Destroys a free/busy.
100  */
101  ~FreeBusy() override;
102 
103  /**
104  @copydoc
105  IncidenceBase::type()
106  */
107  Q_REQUIRED_RESULT IncidenceType type() const override;
108 
109  /**
110  @copydoc
111  IncidenceBase::typeStr()
112  */
113  Q_REQUIRED_RESULT QByteArray typeStr() const override;
114 
115  /**
116  Sets the start date/time for the free/busy. Note that this date/time
117  may be later or earlier than all periods within the free/busy.
118 
119  @param start is a QDateTime specifying an start datetime.
120  @see IncidenceBase::dtStart(), setDtEnd().
121  */
122  void setDtStart(const QDateTime &start) override;
123 
124  /**
125  Sets the end datetime for the free/busy. Note that this datetime
126  may be later or earlier than all periods within the free/busy.
127 
128  @param end is a QDateTime specifying an end datetime.
129  @see dtEnd(), setDtStart().
130  */
131  void setDtEnd(const QDateTime &end);
132 
133  /**
134  Returns the end datetime for the free/busy.
135  FIXME: calling addPeriod() does not change mDtEnd. Is that incorrect?
136  @see setDtEnd().
137  */
138  Q_REQUIRED_RESULT virtual QDateTime dtEnd() const;
139 
140  /**
141  @copydoc
142  IncidenceBase::shiftTimes()
143  */
144  void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone) override;
145 
146  /**
147  Returns the list of all periods within the free/busy.
148  */
149  Q_REQUIRED_RESULT Period::List busyPeriods() const;
150 
151  /**
152  Returns the list of all periods within the free/busy.
153  */
154  Q_REQUIRED_RESULT FreeBusyPeriod::List fullBusyPeriods() const;
155 
156  /**
157  Adds a period to the freebusy list and sorts the list.
158 
159  @param start is the start datetime of the period.
160  @param end is the end datetime of the period.
161  */
162  void addPeriod(const QDateTime &start, const QDateTime &end);
163 
164  /**
165  Adds a period to the freebusy list and sorts the list.
166 
167  @param start is the start datetime of the period.
168  @param duration is the Duration of the period.
169  */
170  void addPeriod(const QDateTime &start, const Duration &duration);
171 
172  /**
173  Adds a list of periods to the freebusy object and then sorts that list.
174  Use this if you are adding many items, instead of the addPeriod method,
175  to avoid sorting repeatedly.
176 
177  @param list is a list of Period objects.
178  */
179  void addPeriods(const Period::List &list);
180 
181  /**
182  Adds a list of periods to the freebusy object and then sorts that list.
183  Use this if you are adding many items, instead of the addPeriod method,
184  to avoid sorting repeatedly.
185 
186  @param list is a list of FreeBusyPeriod objects.
187  */
188  void addPeriods(const FreeBusyPeriod::List &list);
189 
190  /**
191  Sorts the list of free/busy periods into ascending order.
192  */
193  void sortList();
194 
195  /**
196  Merges another free/busy into this free/busy.
197 
198  @param freebusy is a pointer to a valid FreeBusy object.
199  */
200  void merge(const FreeBusy::Ptr &freebusy);
201 
202  /**
203  @copydoc
204  IncidenceBase::dateTime()
205  */
206  Q_REQUIRED_RESULT QDateTime dateTime(DateTimeRole role) const override;
207 
208  /**
209  @copydoc
210  IncidenceBase::setDateTime()
211  */
212  void setDateTime(const QDateTime &dateTime, DateTimeRole role) override;
213 
214  /**
215  @copydoc
216  IncidenceBase::mimeType()
217  */
218  Q_REQUIRED_RESULT QLatin1String mimeType() const override;
219 
220  /**
221  Returns the Akonadi specific sub MIME type of a KCalendarCore::FreeBusy.
222  */
223  Q_REQUIRED_RESULT static QLatin1String freeBusyMimeType();
224 
225 protected:
226  /**
227  Compare this with @p freebusy for equality.
228  @param freebusy is the FreeBusy to compare.
229  */
230  bool equals(const IncidenceBase &freebusy) const override;
231 
232  /**
233  @copydoc
234  IncidenceBase::assign()
235  */
236  IncidenceBase &assign(const IncidenceBase &other) override;
237 
238  /**
239  @copydoc
240  IncidenceBase::virtual_hook()
241  */
242  void virtual_hook(VirtualHook id, void *data) override;
243 
244 private:
245 
246  Q_DECLARE_PRIVATE(FreeBusy)
247 
248  /**
249  @copydoc
250  IncidenceBase::accept()
251  */
252  bool accept(Visitor &v, const IncidenceBase::Ptr &incidence) override;
253 
254  /**
255  Disabled, otherwise could be dangerous if you subclass FreeBusy.
256  Use IncidenceBase::operator= which is safe because it calls
257  virtual function assign().
258  @param other is another FreeBusy object to assign to this one.
259  */
260  FreeBusy &operator=(const FreeBusy &other);
261 
262  //@cond PRIVATE
263 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 91)
264  KCALENDARCORE_DEPRECATED_VERSION(5, 91, "Do not use")
265  FreeBusyPrivate *const _ = nullptr; // TODO KF6 remove. ABI compatibility hack.
266 #endif
267  //@endcond
268 };
269 
270 /**
271  Serializes the @p freebusy object into the @p stream.
272 */
273 KCALENDARCORE_EXPORT QDataStream &operator<<(QDataStream &stream, const KCalendarCore::FreeBusy::Ptr &freebusy);
274 /**
275  Initializes the @p freebusy object from the @p stream.
276 */
277 KCALENDARCORE_EXPORT QDataStream &operator>>(QDataStream &stream, KCalendarCore::FreeBusy::Ptr &freebusy);
278 }
279 
280 //@cond PRIVATE
281 Q_DECLARE_TYPEINFO(KCalendarCore::FreeBusy::Ptr, Q_MOVABLE_TYPE);
282 Q_DECLARE_METATYPE(KCalendarCore::FreeBusy::Ptr)
283 //@endcond
284 
285 #endif
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Alarm serializer.
Definition: alarm.cpp:820
Represents a span of time measured in seconds or days.
Definition: duration.h:43
DateTimeRole
The different types of incidence date/times roles.
QVector< Ptr > List
List of FreeBusy objects.
Definition: freebusy.h:56
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
An abstract class that provides a common base for all calendar incidence classes.
Definition: incidencebase.h:98
Q_SCRIPTABLE Q_NOREPLY void start()
Provides information about the free/busy time of a calendar.
Definition: freebusy.h:42
This class provides the interface for a visitor of calendar components.
Definition: visitor.h:30
Represents a period of time.
IncidenceType
The different types of incidences, per RFC2445.
QSharedPointer< FreeBusy > Ptr
A shared pointer to a FreeBusy object.
Definition: freebusy.h:51
Represents a period of time.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 28 2023 03:53:12 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.