KAlarmCal

kaevent.h
1 /*
2  * kaevent.h - represents KAlarm calendar events
3  * This file is part of kalarmcal library, which provides access to KAlarm
4  * calendar data.
5  * SPDX-FileCopyrightText: 2001-2021 David Jarvie <[email protected]>
6  *
7  * SPDX-License-Identifier: LGPL-2.0-or-later
8  */
9 
10 #pragma once
11 
12 #include "kalarmcal_export.h"
13 
14 #include "datetime.h"
15 #include "karecurrence.h"
16 #include "kacalendar.h"
17 #include "repetition.h"
18 
19 #include <collection.h>
20 #include <item.h>
21 #include <KCalendarCore/Person>
22 #include <KCalendarCore/Calendar>
23 #include <AkonadiCore/item.h>
24 
25 #include <QBitArray>
26 #include <QColor>
27 #include <QFont>
28 #include <QVector>
29 #include <QSharedDataPointer>
30 #include <QMetaType>
31 
32 namespace KHolidays
33 {
34 class HolidayRegion;
35 }
36 
37 namespace KAlarmCal
38 {
39 
40 /**
41  * @short KAAlarm represents individual alarms within a KAEvent.
42  *
43  * The KAAlarm class represents one of the main or subsidiary alarms in
44  * a KAEvent instance. It contains the alarm's type and trigger time.
45  *
46  * Note that valid KAAlarm instances can only be created by the KAEvent
47  * class.
48  *
49  * @see KAEvent::alarm(), KAEvent::firstAlarm(), KAEvent::nextAlarm().
50  *
51  * @author David Jarvie <[email protected]>
52  */
53 class KALARMCAL_EXPORT KAAlarm
54 {
55 public:
56  /** The basic KAAlarm action types. */
57  enum Action {
58  MESSAGE, //!< KCal::Alarm::Display type: display a text message
59  FILE, //!< KCal::Alarm::Display type: display a file (URL given by the alarm text)
60  COMMAND, //!< KCal::Alarm::Procedure type: execute a shell command
61  EMAIL, //!< KCal::Alarm::Email type: send an email
62  AUDIO //!< KCal::Alarm::Audio type: play a sound file
63  };
64 
65  /** Alarm types.
66  * KAAlarm's of different types may be contained in a KAEvent,
67  * each KAAlarm defining a different component of the overall alarm.
68  */
69  enum Type {
70  INVALID_ALARM = 0, //!< Not an alarm
71  MAIN_ALARM = 1, //!< THE real alarm. Must be the first in the enumeration.
72  REMINDER_ALARM = 0x02, //!< Reminder in advance of/after the main alarm
73  DEFERRED_ALARM = 0x04, //!< Deferred alarm
74  DEFERRED_REMINDER_ALARM = REMINDER_ALARM | DEFERRED_ALARM, //!< Deferred reminder alarm
75  // The following values must be greater than the preceding ones, to
76  // ensure that in ordered processing they are processed afterwards.
77  AT_LOGIN_ALARM = 0x10, //!< Additional repeat-at-login trigger
78  DISPLAYING_ALARM = 0x20 //!< Copy of the alarm currently being displayed
79 
80  // IMPORTANT: if any values are added to this list, ensure that the
81  // KAEventPrivate::AlarmType enum is adjusted similarly.
82  };
83 
84  /** Default constructor, which creates an invalid instance. */
85  KAAlarm();
86 
87  /** Copy constructor. */
88  KAAlarm(const KAAlarm &other);
89 
90  /** Destructor. */
91  ~KAAlarm();
92 
93  /** Assignment operator. */
94  KAAlarm &operator=(const KAAlarm &other);
95 
96  /** Return the action type for the alarm. */
97  Action action() const;
98 
99  /** Return whether the alarm is valid, i.e. whether it contains any alarm data. */
100  bool isValid() const;
101 
102  /** Return the alarm's type (main, reminder, etc.). */
103  Type type() const;
104 
105  /** Return the trigger time for the alarm.
106  * Sub-repetitions can optionally be ignored; in this case, if a sub-repetition
107  * is due next, the last main recurrence will be returned instead.
108  * @param withRepeats if true, returns the next sub-repetition time where appropriate;
109  * if false, ignores sub-repetitions.
110  */
111  DateTime dateTime(bool withRepeats = false) const;
112 
113  /** Return the trigger date for the alarm.
114  * Sub-repetitions are ignored: if a sub-repetition is due next, the
115  * last main recurrence will be returned instead.
116  */
117  QDate date() const;
118 
119  /** Return the trigger time-of-day for the alarm.
120  * Sub-repetitions are ignored: if a sub-repetition is due next, the
121  * last main recurrence will be returned instead.
122  * @return trigger time-of-day. If the alarm is date-only, this will be
123  * the user-defined start-of-day time.
124  */
125  QTime time() const;
126 
127  /** Set the alarm's trigger time. */
128  void setTime(const DateTime &dt);
129 
130  /** Set the alarm's trigger time. */
131  void setTime(const KADateTime &dt);
132 
133  /** Return whether this is a repeat-at-login alarm. */
134  bool repeatAtLogin() const;
135 
136  /** Return whether this is a reminder alarm. */
137  bool isReminder() const;
138 
139  /** Return whether this is a deferred alarm. */
140  bool deferred() const;
141 
142  /** Return whether in the case of a deferred alarm, it is timed (as
143  * opposed to date-only).
144  * @return @c true if a timed deferral alarm, @c false if date-only or not a deferred alarm.
145  */
146  bool timedDeferral() const;
147 
148  /** Return an alarm type as a string.
149  * @return alarm type string, or the empty string if debug output is disabled.
150  */
151  static const char *debugType(Type);
152 
153 private:
154  //@cond PRIVATE
155  class Private;
156  Private *const d;
157  //@endcond
158 
159  friend class KAEvent;
160  friend class KAEventPrivate;
161 };
162 
163 class KAEventPrivate;
164 
165 /**
166  * @short KAEvent represents a KAlarm event
167  *
168  * KAEvent represents a KAlarm event. An event contains a main alarm together
169  * with optional subsidiary alarms such as reminders and deferrals. Individual
170  * alarms are represented by the KAAlarm class. KAEvent includes the complete
171  * definition of the event including recurrence information, and also holds
172  * current status information such as the next due occurrence and command
173  * execution error status. It provides methods to set and get the event
174  * properties, to defer the alarm, to convert it for storage in the displaying
175  * calendar.
176  *
177  * Methods which act globally or on multiple KAEvent instances include
178  * convertKCalEvents() which converts events stored in an older KAlarm
179  * calendar format to the current format; setStartOfDay() and adjustStartOfDay()
180  * which set a new start-of-day time for date-only alarms; setHolidays()
181  * and setWorkTime() which set holiday region and working days/hours.
182  *
183  * @author David Jarvie <[email protected]>
184  */
185 class KALARMCAL_EXPORT KAEvent
186 {
187 public:
188  /** A list of pointers to KAEvent objects. */
190 
191  /** Flags for use in D-Bus calls, etc. Flags may be combined by OR'ing them together. */
192  enum Flag {
193  BEEP = 0x02, //!< sound an audible beep when the alarm is displayed
194  REPEAT_AT_LOGIN = 0x04, //!< repeat the alarm at every login
195  ANY_TIME = 0x08, //!< only a date is specified for the alarm, not a time
196  CONFIRM_ACK = 0x10, //!< closing the alarm message window requires a confirmation prompt
197  EMAIL_BCC = 0x20, //!< blind copy the email to the user
198  DEFAULT_FONT = 0x40, //!< use the default alarm message font. Overrides any specified font.
199  REPEAT_SOUND = 0x80, //!< repeat the sound file while the alarm is displayed
200  DISABLED = 0x100, //!< the alarm is currently disabled
201  AUTO_CLOSE = 0x200, //!< auto-close the alarm window after the late-cancel period
202  SCRIPT = 0x400, //!< the command is a script, not a shell command line
203  EXEC_IN_XTERM = 0x800, //!< execute the command in a terminal window
204  SPEAK = 0x1000, //!< speak the message when the alarm is displayed
205  COPY_KORGANIZER = 0x2000, //!< KOrganizer should hold a copy of the event
206  EXCL_HOLIDAYS = 0x4000, //!< don't trigger the alarm on holidays. Only valid
207  //!< if a holiday region has been set by setHolidays().
208  WORK_TIME_ONLY = 0x8000, //!< trigger the alarm only during working hours
209  DISPLAY_COMMAND = 0x10000, //!< display command output in the alarm window
210  REMINDER_ONCE = 0x20000, //!< only trigger the reminder on the first recurrence
211  DONT_SHOW_ERROR = 0x40000, //!< do not notify command alarm errors to user
212  NOTIFY = 0x80000 //!< use the standard notification system instead of alarm message window
213 
214  // IMPORTANT: if any values are added to this list, ensure that the
215  // additional enum values in KAEventPrivate are also adjusted.
216  };
217  Q_DECLARE_FLAGS(Flags, Flag)
218 
219  /** The basic action type(s) for the event's main alarm.
220  * Values may be combined by OR'ing them together. */
221  enum Actions {
222  ACT_NONE = 0, //!< invalid
223  ACT_DISPLAY = 0x01, //!< the alarm displays something
224  ACT_COMMAND = 0x02, //!< the alarm executes a command
225  ACT_EMAIL = 0x04, //!< the alarm sends an email
226  ACT_AUDIO = 0x08, //!< the alarm plays an audio file (without any display)
227  ACT_DISPLAY_COMMAND = ACT_DISPLAY | ACT_COMMAND, //!< the alarm displays command output
228  ACT_ALL = ACT_DISPLAY | ACT_COMMAND | ACT_EMAIL | ACT_AUDIO //!< all types mask
229  };
230 
231  /** The sub-action type for the event's main alarm. */
232  enum SubAction {
233  MESSAGE = KAAlarm::MESSAGE, //!< display a message text
234  FILE = KAAlarm::FILE, //!< display the contents of a file
235  COMMAND = KAAlarm::COMMAND, //!< execute a command
236  EMAIL = KAAlarm::EMAIL, //!< send an email
237  AUDIO = KAAlarm::AUDIO //!< play an audio file
238  };
239 
240  /** What type of occurrence is due. */
241  enum OccurType {
242  NO_OCCURRENCE = 0, //!< no occurrence is due
243  FIRST_OR_ONLY_OCCURRENCE = 0x01, //!< the first occurrence (takes precedence over LAST_RECURRENCE)
244  RECURRENCE_DATE = 0x02, //!< a recurrence with only a date, not a time
245  RECURRENCE_DATE_TIME = 0x03, //!< a recurrence with a date and time
246  LAST_RECURRENCE = 0x04, //!< the last recurrence
247  OCCURRENCE_REPEAT = 0x10, //!< (bitmask for a sub-repetition of an occurrence)
248  FIRST_OR_ONLY_OCCURRENCE_REPEAT = OCCURRENCE_REPEAT | FIRST_OR_ONLY_OCCURRENCE, //!< a sub-repetition of the first occurrence
249  RECURRENCE_DATE_REPEAT = OCCURRENCE_REPEAT | RECURRENCE_DATE, //!< a sub-repetition of a date-only recurrence
250  RECURRENCE_DATE_TIME_REPEAT = OCCURRENCE_REPEAT | RECURRENCE_DATE_TIME, //!< a sub-repetition of a date/time recurrence
251  LAST_RECURRENCE_REPEAT = OCCURRENCE_REPEAT | LAST_RECURRENCE //!< a sub-repetition of the last recurrence
252  };
253 
254  /** How to treat sub-repetitions in nextOccurrence(). */
255  enum OccurOption {
256  IGNORE_REPETITION, //!< check for recurrences only, ignore sub-repetitions
257  RETURN_REPETITION, //!< return a sub-repetition if it's the next occurrence
258  ALLOW_FOR_REPETITION //!< if a sub-repetition is the next occurrence, return the previous recurrence, not the sub-repetition
259  };
260 
261  /** What type of occurrence currently limits how long the alarm can be deferred. */
263  LIMIT_NONE, //!< there is no limit
264  LIMIT_MAIN, //!< the main alarm
265  LIMIT_RECURRENCE, //!< a recurrence
266  LIMIT_REPETITION, //!< a sub-repetition
267  LIMIT_REMINDER //!< a reminder
268  };
269 
270  /** Next trigger type for an alarm. */
271  enum TriggerType {
272 
273  /** Next trigger, including reminders. No account is taken of any
274  * working hours or holiday restrictions when evaluating this. */
276 
277  /** Next trigger of the main alarm, i.e. excluding reminders. No
278  * account is taken of any working hours or holiday restrictions when
279  * evaluating this. */
281 
282  /** Next trigger of the main alarm, i.e. excluding reminders, taking
283  * account of any working hours or holiday restrictions. If the event
284  * has no working hours or holiday restrictions, this is equivalent to
285  * MAIN_TRIGGER. */
287 
288  /** Next trigger, including reminders, taking account of any working
289  * hours or holiday restrictions. If the event has no working hours or
290  * holiday restrictions, this is equivalent to ALL_TRIGGER. */
292 
293  /** Next trigger time for display purposes (i.e. excluding reminders). */
294  DISPLAY_TRIGGER
295  };
296 
297  /** Command execution error type for last time the alarm was triggered. */
298  enum CmdErrType {
299  CMD_NO_ERROR = 0, //!< no error
300  CMD_ERROR = 0x01, //!< command alarm execution failed
301  CMD_ERROR_PRE = 0x02, //!< pre-alarm command execution failed
302  CMD_ERROR_POST = 0x04, //!< post-alarm command execution failed
303  CMD_ERROR_PRE_POST = CMD_ERROR_PRE | CMD_ERROR_POST
304  };
305 
306  /** Options for pre- or post-alarm actions. These may be OR'ed together.
307  * @since 4.9
308  */
310  CancelOnPreActError = 0x01, //!< cancel alarm on pre-alarm action error
311  DontShowPreActError = 0x02, //!< do not notify pre-alarm action errors to user
312  ExecPreActOnDeferral = 0x04 //!< execute pre-alarm action also for deferred alarms
313  };
314  Q_DECLARE_FLAGS(ExtraActionOptions, ExtraActionOption)
315 
316  /** How to deal with the event UID in updateKCalEvent(). */
317  enum UidAction {
318  UID_IGNORE, //!< leave KCal::Event UID unchanged
319  UID_CHECK, //!< verify that the KCal::Event UID is already the same as the KAEvent ID, if the latter is non-empty
320  UID_SET //!< set the KCal::Event UID to the KAEvent ID
321  };
322 
323  /** Default constructor which creates an invalid event. */
324  KAEvent();
325 
326  /** Construct an event and initialise with the specified parameters.
327  * @param dt start date/time. If @p dt is date-only, or if #ANY_TIME flag
328  * is specified, the event will be date-only.
329  * @param name name of the alarm.
330  * @param text alarm message (@p action = #MESSAGE);
331  * file to display (@p action = #FILE);
332  * command to execute (@p action = #COMMAND);
333  * email body (@p action = #EMAIL);
334  * audio file (@p action = #AUDIO).
335  * @param bg background color (for display alarms, ignored otherwise).
336  * @param fg foreground color (for display alarms, ignored otherwise).
337  * @param font font (for display alarms, ignored otherwise). Ignored if
338  * #DEFAULT_FONT flag is specified.
339  * @param action alarm action type.
340  * @param lateCancel late-cancellation period (minutes), else 0.
341  * @param flags OR of #Flag enum values.
342  * @param changesPending true to inhibit automatic calculations and data
343  * updates until further changes have been applied
344  * to the instance; call endChanges() when changes
345  * are complete.
346  */
347  KAEvent(const KADateTime &dt, const QString &name, const QString &text,
348  const QColor &bg, const QColor &fg, const QFont &font,
349  SubAction action, int lateCancel, Flags flags, bool changesPending = false);
350 
351  /** Construct an event and initialise with the specified parameters.
352  * @param dt start date/time. If @p dt is date-only, or if #ANY_TIME flag
353  * is specified, the event will be date-only.
354  * @param text alarm message (@p action = #MESSAGE);
355  * file to display (@p action = #FILE);
356  * command to execute (@p action = #COMMAND);
357  * email body (@p action = #EMAIL);
358  * audio file (@p action = #AUDIO).
359  * @param bg background color (for display alarms, ignored otherwise).
360  * @param fg foreground color (for display alarms, ignored otherwise).
361  * @param font font (for display alarms, ignored otherwise). Ignored if
362  * #DEFAULT_FONT flag is specified.
363  * @param action alarm action type.
364  * @param lateCancel late-cancellation period (minutes), else 0.
365  * @param flags OR of #Flag enum values.
366  * @param changesPending true to inhibit automatic calculations and data
367  * updates until further changes have been applied
368  * to the instance; call endChanges() when changes
369  * are complete.
370  * @deprecated Use the other constructor.
371  */
372  KALARMCAL_DEPRECATED KAEvent(const KADateTime &dt, const QString &text, const QColor &bg, const QColor &fg,
373  const QFont &font, SubAction action, int lateCancel, Flags flags, bool changesPending = false);
374 
375  /** Construct an event and initialise it from a KCalendarCore::Event.
376  *
377  * The initialisation is identical to that performed by set().
378  */
379  explicit KAEvent(const KCalendarCore::Event::Ptr &);
380 
381  /** Initialise the instance from a KCalendarCore::Event.
382  *
383  * It uses the following properties from KCalendarCore::Event:
384  * - Unique ID.
385  * - Summary.
386  * - Creation date/time.
387  * - Start date/time.
388  * - Recurrence rule.
389  * - Alarms.
390  * - Read only.
391  * - Custom properties. X-KDE-KALARM- properties are interpreted and used to
392  * set numerous KAEvent properties; non-KAlarm properties are simply stored.
393  * - Custom status if equal to "DISABLED".
394  * - Revision number.
395  * @deprecated Use constructor and operator=() instead.
396  */
397  KALARMCAL_DEPRECATED void set(const KCalendarCore::Event::Ptr &);
398 
399  KAEvent(const KAEvent &other);
400  ~KAEvent();
401 
402  KAEvent &operator=(const KAEvent &other);
403 
404  /** Initialise the instance with the specified parameters.
405  * @param dt start date/time
406  * @param text alarm message (@p action = #MESSAGE);
407  * file to display (@p action = #FILE);
408  * command to execute (@p action = #COMMAND);
409  * email body (@p action = #EMAIL);
410  * audio file (@p action = #AUDIO)
411  * @param bg background color (for display alarms, ignored otherwise)
412  * @param fg background color (for display alarms, ignored otherwise)
413  * @param font font (for display alarms, ignored otherwise)
414  * @param action alarm action type
415  * @param lateCancel late-cancellation period (minutes), else 0
416  * @param flags OR of #Flag enum values
417  * @param changesPending true to inhibit automatic data updates until
418  * further changes have been applied to the instance;
419  * call endChanges() when changes are complete.
420  * @deprecated Use constructor and operator=() instead.
421  */
422  KALARMCAL_DEPRECATED void set(const KADateTime &dt, const QString &text, const QColor &bg,
423  const QColor &fg, const QFont &font, SubAction action, int lateCancel,
424  Flags flags, bool changesPending = false);
425 
426  /** Update an existing KCalendarCore::Event with the KAEvent data.
427  * @param event Event to update.
428  * @param u how to deal with the Event's UID.
429  * @param setCustomProperties if true, all the Event's existing custom
430  * properties are cleared and replaced with the
431  * KAEvent's custom properties. If false, the
432  * KCal::Event's non-KAlarm custom properties
433  * are left untouched.
434  */
435  bool updateKCalEvent(const KCalendarCore::Event::Ptr &event, UidAction u, bool setCustomProperties = true) const;
436 
437  /** Return whether the instance represents a valid event. */
438  bool isValid() const;
439 
440  /** Enable or disable the alarm. */
441  void setEnabled(bool enable);
442 
443  /** Return the enabled status of the alarm. */
444  bool enabled() const;
445 
446  /** Set the read-only status of the alarm. */
447  void setReadOnly(bool ro);
448 
449  /** Return the read-only status of the alarm. */
450  bool isReadOnly() const;
451 
452  /** Set the event to be archived when it expires or is deleted.
453  * Normally this is set when the event has triggered at least once.
454  */
455  void setArchive();
456 
457  /** Return whether the event should be archived when it expires or is deleted. */
458  bool toBeArchived() const;
459 
460  /** Return whether the event's main alarm has expired. If so, a deferral alarm will exist. */
461  bool mainExpired() const;
462 
463  /** Return whether the event has expired.
464  * @return @c true if the event has expired and is currently being displayed,
465  * or it is an archived event.
466  */
467  bool expired() const;
468 
469  /** Return the OR of various Flag enum status values. */
470  Flags flags() const;
471 
472  /** Set the alarm category (active/archived/template, or displaying). */
473  void setCategory(CalEvent::Type type);
474 
475  /** Return the alarm category (active/archived/template, or displaying). */
476  CalEvent::Type category() const;
477 
478  /** Set the event's unique identifier. Note that the UID is guaranteed to be unique
479  * only within the calendar containing the event.
480  */
481  void setEventId(const QString &id);
482 
483  /** Return the event's unique identifier. Note that the UID is guaranteed to be unique
484  * only within the calendar containing the event.
485  */
486  QString id() const;
487 
488  /** Increment the revision number of the event (SEQUENCE property in iCalendar). */
489  void incrementRevision();
490 
491  /** Return the revision number of the event (SEQUENCE property in iCalendar). */
492  int revision() const;
493 
494  /** Set the ID of the Akonadi Collection which contains the event.
495  * @see setResourceId() is the generic form of this method.
496  */
497  void setCollectionId(Akonadi::Collection::Id id);
498 
499  /** Set the ID of the calendar resource which contains the event. */
500  void setResourceId(ResourceId id);
501 
502  /** Set the ID of the Akonadi Collection which contains the event.
503  * @warning This is a const method, which means that any other instance
504  * which references the same shared data will also be
505  * updated. It is designed to be used when a KAEvent is
506  * being created from an Akonadi Item, to avoid unnecessary
507  * copying. Use with caution!
508  * @see setResourceId_const() is the generic form of this method.
509  */
510  void setCollectionId_const(Akonadi::Collection::Id id) const;
511 
512  /** Set the ID of the Akonadi Collection which contains the event.
513  * @warning This is a const method, which means that any other instance
514  * which references the same shared data will also be
515  * updated. It is designed to be used when a KAEvent is
516  * being created from an Akonadi Item, to avoid unnecessary
517  * copying. Use with caution!
518  */
519  void setResourceId_const(ResourceId id) const;
520 
521  /** Return the ID of the Akonadi Collection which contains the event.
522  * @see resourceId() is the generic form of this method.
523  */
524  Akonadi::Collection::Id collectionId() const;
525 
526  /** Return the ID of the calendar resource which contains the event. */
527  ResourceId resourceId() const;
528 
529  /** Set the ID of the Akonadi Item which contains the event.
530  * @deprecated KAlarmCal will no longer provide this functionality.
531  */
532  KALARMCAL_DEPRECATED void setItemId(Akonadi::Item::Id id);
533 
534  /** Return the ID of the Akonadi Item which contains the event.
535  * @deprecated KAlarmCal will no longer provide this functionality.
536  */
537  KALARMCAL_DEPRECATED Akonadi::Item::Id itemId() const;
538 
539  /** Initialise an Akonadi::Item with the event's data.
540  * Note that the event is not updated with the Item ID.
541  * @return @c true if successful; @c false if the event's category does not match the
542  * collection's mime types.
543  * @deprecated Use KAlarmCal::setItemPayload() instead.
544  */
545  KALARMCAL_DEPRECATED bool setItemPayload(Akonadi::Item &, const QStringList &collectionMimeTypes) const;
546 
547  /** Note the event's storage format compatibility compared to the current KAlarm calendar format. */
548  void setCompatibility(KACalendar::Compat c);
549 
550  /** Return the event's storage format compatibility compared to the current KAlarm calendar format. */
551  KACalendar::Compat compatibility() const;
552 
553  /** Return the original KCalendarCore::Event's custom properties in the source calendar. */
554  QMap<QByteArray, QString> customProperties() const;
555 
556  /** Return the action sub-type of the event's main alarm. For display alarms,
557  * this is MESSAGE or FILE, while other types of alarm simply return the
558  * basic action type (COMMAND, EMAIL, AUDIO).
559  * Note that for a display alarm whose text is generated by a command, the
560  * returned type is COMMAND.
561  */
562  SubAction actionSubType() const;
563 
564  /** Return the OR of the basic action types of the event's main alarm (display,
565  * command, email, audio).
566  * Note that for a display alarm whose text is generated by a command, the
567  * returned type is @c ACT_DISPLAY|ACT_COMMAND.
568  */
569  Actions actionTypes() const;
570 
571  /** Set or clear the late-cancel option. This determines whether the alarm
572  * will be cancelled if it is late in triggering.
573  * @param minutes late cancellation period in minutes, or 0 to clear
574  * @see lateCancel()
575  */
576  void setLateCancel(int minutes);
577 
578  /** Get the late cancellation period. This is how late the alarm can
579  * trigger after its scheduled time, before it will be cancelled.
580  * @return period in minutes, or 0 if no late cancellation is specified
581  * @see setLateCancel()
582  */
583  int lateCancel() const;
584 
585  /** Enable or disable auto-close for a display alarm, i.e. whether the
586  * alarm window will be closed on expiry of the late-cancellation
587  * time. Note that auto-close will only take effect if the late-cancel
588  * option is also set.
589  * @see setLateCancel(), autoClose()
590  */
591  void setAutoClose(bool autoclose);
592 
593  /** Return whether auto-close is enabled, i.e. whether the alarm window
594  * will be closed on expiry of the late-cancellation time. Note that
595  * auto-close will only operate if in addition to being enabled,
596  * late-cancel is also set.
597  * @return @c true if it is a display alarm and auto-close is enabled.
598  * @see lateCancel(), setAutoClose()
599  */
600  bool autoClose() const;
601 
602  /** Enable the notification system to be used for a display alarm, instead
603  * of displaying a window.
604  * @see notify()
605  */
606  void setNotify(bool useNotify);
607 
608  /** Return whether the notification system is used instead of displaying
609  * a window, for a display alarm.
610  * @return @c true if it is a display alarm and it uses the notification
611  * system
612  * @see setNotify()
613  */
614  bool notify() const;
615 
616  /** Set the Akonadi item ID of the email which the alarm is related to.
617  */
618  void setAkonadiItemId(Akonadi::Item::Id id);
619 
620  /** Return the Akonadi item ID of the email which the alarm is related to.
621  */
622  Akonadi::Item::Id akonadiItemId() const;
623 
624  /** Set the alarm's name. */
625  void setName(const QString& newName);
626 
627  /** Return the alarm's name. */
628  QString name() const;
629 
630  /** Return the alarm's text. Its significance depends on the type of alarm;
631  * alternatively, use message(), displayMessage(), fileName() or command(),
632  * which incorporate checks on alarm type.
633  */
634  QString cleanText() const;
635 
636  /** Return the message text for a display alarm, or the email body for
637  * an email alarm.
638  * @return message/email text, or empty if not a display or email alarm. */
639  QString message() const;
640 
641  /** Return the message text for a display alarm.
642  * @return message text, or empty if not a text display alarm. */
643  QString displayMessage() const;
644 
645  /** Return the path of the file whose contents are to be shown, for a display alarm.
646  * @return file path, or empty if not a file display alarm. */
647  QString fileName() const;
648 
649  /** Return the message window background color, for a display alarm. */
650  QColor bgColour() const;
651 
652  /** Return the message window foreground color, for a display alarm. */
653  QColor fgColour() const;
654 
655  /** Set the global default font for alarm message texts. */
656  static void setDefaultFont(const QFont &font);
657 
658  /** Return whether to use the default font (as set by setDefaultFont())
659  * for alarm message texts. */
660  bool useDefaultFont() const;
661 
662  /** Return the font to use for alarm message texts. */
663  QFont font() const;
664 
665  /** Return the command or script to execute, for a command alarm.
666  * @return command, or empty if not a command alarm. */
667  QString command() const;
668 
669  /** Return whether a command script is specified, for a command alarm. */
670  bool commandScript() const;
671 
672  /** Return whether to execute the command in a terminal window, for a command alarm. */
673  bool commandXterm() const;
674 
675  /** Return whether the command output is to be displayed in an alarm message window. */
676  bool commandDisplay() const;
677 
678  /** Set or clear the command execution error for the last time the alarm triggered. */
679  void setCommandError(CmdErrType error) const;
680 
681  /** Return the command execution error for the last time the alarm triggered. */
682  CmdErrType commandError() const;
683 
684  /** Return whether execution errors for the command should not to be shown to the user.
685  * @since 20.08
686  */
687  bool commandHideError() const;
688 
689  /** Set the log file to write command alarm output to.
690  * @param logfile log file path
691  */
692  void setLogFile(const QString &logfile);
693  /** Return the log file which command alarm output should be written to.
694  * @return log file path, or empty if no log file. */
695  QString logFile() const;
696 
697  /** Return whether alarm acknowledgement must be confirmed by the user, for a display alarm. */
698  bool confirmAck() const;
699 
700  /** Return whether KOrganizer should hold a copy of the event. */
701  bool copyToKOrganizer() const;
702 
703  /** Set the email related data for the event. */
704  void setEmail(uint from, const KCalendarCore::Person::List &, const QString &subject,
705  const QStringList &attachments);
706 
707  /** Return the email message body, for an email alarm.
708  * @return email body, or empty if not an email alarm
709  */
710  QString emailMessage() const;
711 
712  /** Return the email identity to be used as the sender, for an email alarm.
713  * @return email UOID
714  */
715  uint emailFromId() const;
716 
717  /** Return the list of email addressees, including names, for an email alarm. */
718  KCalendarCore::Person::List emailAddressees() const;
719 
720  /** Return a list of the email addresses, including names, for an email alarm. */
721  QStringList emailAddresses() const;
722 
723  /** Return a string containing the email addressees, including names, for an email alarm.
724  * @param sep separator string to insert between addresses.
725  */
726  QString emailAddresses(const QString &sep) const;
727 
728  /** Concatenate a list of email addresses into a string.
729  * @param addresses list of email addresses
730  * @param sep separator string to insert between addresses
731  */
732  static QString joinEmailAddresses(const KCalendarCore::Person::List &addresses, const QString &sep);
733  /** Return the list of email addressees, excluding names, for an email alarm. */
734  QStringList emailPureAddresses() const;
735 
736  /** Return a string containing the email addressees, excluding names, for an email alarm.
737  * @param sep separator string to insert between addresses.
738  */
739  QString emailPureAddresses(const QString &sep) const;
740 
741  /** Return the email subject line, for an email alarm. */
742  QString emailSubject() const;
743 
744  /** Return the list of file paths of the attachments, for an email alarm. */
745  QStringList emailAttachments() const;
746 
747  /** Return the file paths of the attachments, as a string, for an email alarm.
748  * @param sep string separator
749  */
750  QString emailAttachments(const QString &sep) const;
751 
752  /** Return whether to send a blind copy of the email to the sender, for an email alarm. */
753  bool emailBcc() const;
754 
755  /** Set the audio file related data for the event.
756  * @param filename audio file path
757  * @param volume final volume (0 - 1), or -1 for default volume
758  * @param fadeVolume initial volume (0 - 1), or -1 for no fade
759  * @param fadeSeconds number of seconds to fade from @p fadeVolume to @p volume
760  * @param repeatPause number of seconds to pause between repetitions, or -1 if no repeat
761  * @param allowEmptyFile true to set the volume levels even if @p filename is empty
762  * @see audioFile(), soundVolume(), fadeVolume(), fadeSeconds()
763  */
764  void setAudioFile(const QString &filename, float volume, float fadeVolume,
765  int fadeSeconds, int repeatPause = -1, bool allowEmptyFile = false);
766 
767  /** Return the audio file path.
768  * @see setAudioFile()
769  */
770  QString audioFile() const;
771 
772  /** Return the sound volume (the final volume if fade is specified).
773  * @return volume in range 0 - 1, or -1 for default volume.
774  * @see setAudioFile()
775  */
776  float soundVolume() const;
777 
778  /** Return the initial volume which will fade to the final volume.
779  * @return volume in range 0 - 1, or -1 if no fade specified.
780  * @see setAudioFile()
781  */
782  float fadeVolume() const;
783 
784  /** Return the fade period in seconds, or 0 if no fade is specified.
785  * @see setAudioFile()
786  */
787  int fadeSeconds() const;
788 
789  /** Return whether the sound file will be repeated indefinitely. */
790  bool repeatSound() const;
791 
792  /** Return how many seconds to pause between repetitions of the sound file.
793  * @return pause interval, or -1 if sound does not repeat.
794  */
795  int repeatSoundPause() const;
796 
797  /** Return whether a beep should sound when the alarm is displayed. */
798  bool beep() const;
799 
800  /** Return whether the displayed alarm text should be spoken. */
801  bool speak() const;
802 
803  /** Set the event to be an alarm template.
804  * @param name template's name
805  * @param afterTime number of minutes after default time to schedule alarm for, or
806  * -1 to not use 'time from now'
807  * @see isTemplate(), templateName()
808  */
809  void setTemplate(const QString &name, int afterTime = -1);
810 
811  /** Return whether the event is an alarm template.
812  * @see setTemplate()
813  */
814  bool isTemplate() const;
815 
816  /** Return the alarm template's name.
817  * @return template name, or empty if not a template
818  * @see setTemplate()
819  * @deprecated Use name() instead.
820  */
821  KALARMCAL_DEPRECATED QString templateName() const;
822 
823  /** Return whether the alarm template does not specify a time.
824  * @return @c true if no time is specified, i.e. the normal default alarm time will
825  * be used, @c false if the template specifies a time.
826  */
827  bool usingDefaultTime() const;
828 
829  /** Return the number of minutes (>= 0) after the default alarm time which is
830  * specified in the alarm template. If this is specified, an alarm based on
831  * this template wll have the "Time from now" radio button enabled in the alarm
832  * edit dialog.
833  * @return minutes after the default time, or -1 if the template specifies a time
834  * of day or a date-only alarm.
835  */
836  int templateAfterTime() const;
837 
838  /** Set the pre-alarm and post-alarm actions, and their options.
839  * @param pre shell command to execute before the alarm is displayed
840  * @param post shell command to execute after the alarm is acknowledged
841  * @param preOptions options for pre-alarm actions
842  * @see preAction(), postAction(), extraActionOptions()
843  * @since 4.9
844  */
845  void setActions(const QString &pre, const QString &post, ExtraActionOptions preOptions);
846 
847  /** Return the shell command to execute before the alarm is displayed. */
848  QString preAction() const;
849 
850  /** Return the shell command to execute after the display alarm is acknowledged.
851  * @see setActions()
852  */
853  QString postAction() const;
854 
855  /** Return the pre-alarm action options.
856  * @see preAction(), setActions()
857  * @since 4.9
858  */
859  ExtraActionOptions extraActionOptions() const;
860 
861  /** Set an additional reminder alarm.
862  * @param minutes number of minutes BEFORE the main alarm; if negative, the reminder
863  * will occur AFTER the main alarm.
864  * 0 = clear the reminder.
865  * @param onceOnly true to trigger a reminder only for the first recurrence.
866  * @see reminderMinutes(), reminderOnceOnly()
867  */
868  void setReminder(int minutes, bool onceOnly);
869 
870  /** If there is a reminder which occurs AFTER the main alarm,
871  * activate the event's reminder which occurs after the given main alarm time.
872  * If there is no reminder after the main alarm, this method does nothing.
873  * @return @c true if successful (i.e. reminder falls before the next main alarm).
874  */
875  void activateReminderAfter(const DateTime &mainAlarmTime);
876 
877  /** Return the number of minutes BEFORE the main alarm when a reminder alarm is set.
878  * @return >0 if the reminder is before the main alarm;
879  * <0 if the reminder is after the main alarm;
880  * 0 if no reminder is configured.
881  * @see setReminder()
882  */
883  int reminderMinutes() const;
884 
885  /** Return whether a reminder is currently due (before the next, or after the last,
886  * main alarm/recurrence).
887  * @see reminderDeferral()
888  */
889  bool reminderActive() const;
890 
891  /** Return whether the reminder alarm is triggered only for the first recurrence.
892  * @see setReminder()
893  */
894  bool reminderOnceOnly() const;
895 
896  /** Return whether there is currently a deferred reminder alarm pending. */
897  bool reminderDeferral() const;
898 
899  /** Defer the event to the specified time.
900  * If the main alarm time has passed, the main alarm is marked as expired.
901  * @param dt date/time to defer the event to
902  * @param reminder true if deferring a reminder alarm
903  * @param adjustRecurrence if true, ensure that the next scheduled recurrence is
904  * after the current time.
905  *
906  * @see cancelDefer(), deferred(), deferDateTime()
907  */
908  void defer(const DateTime &dt, bool reminder, bool adjustRecurrence = false);
909 
910  /** Cancel any deferral alarm which is pending.
911  * @see defer()
912  */
913  void cancelDefer();
914 
915  /** Set defaults for the deferral dialog.
916  * @param minutes default number of minutes, or 0 to select time control.
917  * @param dateOnly true to select date-only by default.
918  * @see deferDefaultMinutes()
919  */
920  void setDeferDefaultMinutes(int minutes, bool dateOnly = false);
921 
922  /** Return whether there is currently a deferred alarm pending.
923  * @see defer(), deferDateTime()
924  */
925  bool deferred() const;
926 
927  /** Return the time at which the currently pending deferred alarm should trigger.
928  * @return trigger time, or invalid if no deferral pending.
929  * @see defer(), deferred()
930  */
931  DateTime deferDateTime() const;
932 
933  /** Return the latest time which the alarm can currently be deferred to.
934  * @param limitType if non-null, pointer to variable which will be updated to hold
935  * the type of occurrence which currently limits the deferral.
936  * @return deferral limit, or invalid if no limit
937  */
938  DateTime deferralLimit(DeferLimitType *limitType = nullptr) const;
939 
940  /** Return the default deferral interval used in the deferral dialog.
941  * @see setDeferDefaultMinutes()
942  */
943  int deferDefaultMinutes() const;
944 
945  /** Return the default date-only setting used in the deferral dialog. */
946  bool deferDefaultDateOnly() const;
947 
948  /** Return the start time for the event. If the event recurs, this is the
949  * time of the first recurrence. If the event is date-only, this returns a
950  * date-only value.
951  * @note No account is taken of any working hours or holiday restrictions.
952  * when determining the start date/time.
953  *
954  * @see mainDateTime()
955  */
956  DateTime startDateTime() const;
957 
958  /** Set the next time to trigger the alarm (excluding sub-repetitions).
959  * Note that for a recurring event, this should match one of the
960  * recurrence times.
961  */
962  void setTime(const KADateTime &dt);
963 
964  /** Return the next time the main alarm will trigger.
965  * @note No account is taken of any working hours or holiday restrictions.
966  * when determining the next trigger date/time.
967  *
968  * @param withRepeats true to include sub-repetitions, false to exclude them.
969  * @see mainTime(), startDateTime(), setTime()
970  */
971  DateTime mainDateTime(bool withRepeats = false) const;
972 
973  /** Return the time at which the main alarm will next trigger.
974  * Sub-repetitions are ignored.
975  * @note No account is taken of any working hours or holiday restrictions.
976  * when determining the next trigger time.
977  */
978  QTime mainTime() const;
979 
980  /** Return the time at which the last sub-repetition of the current
981  * recurrence of the main alarm will occur.
982  * @note No account is taken of any working hours or holiday restrictions
983  * when determining the last sub-repetition time.
984  *
985  * @return last sub-repetition time, or main alarm time if no
986  * sub-repetitions are configured.
987  */
988  DateTime mainEndRepeatTime() const;
989 
990  /** Set the start-of-day time used by all date-only alarms.
991  * Note that adjustStartOfDay() should be called immediately after this,
992  * to adjust all events' internal data.
993  */
994  static void setStartOfDay(const QTime &);
995 
996  /** Call when the user changes the start-of-day time, to adjust the data
997  * for each date-only event in a list.
998  * @param events list of events. Any date-time events in the list are ignored.
999  * @see setStartOfDay()
1000  */
1001  static void adjustStartOfDay(const KAEvent::List &events);
1002 
1003  /** Return the next time the alarm will trigger.
1004  * @param type specifies whether to ignore reminders, working time
1005  * restrictions, etc.
1006  */
1007  DateTime nextTrigger(TriggerType type) const;
1008 
1009  /** Set the date/time the event was created, or saved in the archive calendar.
1010  * @see createdDateTime()
1011  */
1012  void setCreatedDateTime(const KADateTime &dt);
1013 
1014  /** Return the date/time the event was created, or saved in the archive calendar.
1015  * @see setCreatedDateTime()
1016  */
1017  KADateTime createdDateTime() const;
1018 
1019  /** Enable or disable repeat-at-login.
1020  * If @p repeat is true, any existing pre-alarm reminder, late-cancel and
1021  * copy-to-KOrganizer will all be disabled.
1022  * @see repeatAtLogin()
1023  */
1024  void setRepeatAtLogin(bool repeat);
1025 
1026  /** Return whether the alarm repeats at login.
1027  * @param includeArchived true to also test for archived repeat-at-login status,
1028  * false to test only for a current repeat-at-login alarm.
1029  * @see setRepeatAtLogin()
1030  */
1031  bool repeatAtLogin(bool includeArchived = false) const;
1032 
1033  /** Enable or disable the alarm on holiday dates. The currently selected
1034  * holiday region determines which dates are holidays.
1035  * Note that this option only has any effect for recurring alarms.
1036  * @param exclude true to disable on holidays, false to enable
1037  * @see holidaysExcluded(), setHolidays()
1038  */
1039  void setExcludeHolidays(bool exclude);
1040 
1041  /** Return whether the alarm is disabled on holiday dates.
1042  * If no holiday region has been set by setHolidays(), this returns false;
1043  * @see setExcludeHolidays()
1044  */
1045  bool holidaysExcluded() const;
1046 
1047  /** Set the holiday region to be used by all KAEvent instances.
1048  * Alarms which exclude holidays record the pointer to the holiday definition
1049  * at the time their next trigger times were last calculated. The change in
1050  * holiday definition pointer will cause their next trigger times to be
1051  * recalculated.
1052  * @param region the holiday region data. The data object must persist for
1053  * the lifetime of the application, since this class just
1054  * stores a pointer to @p region.
1055  * @see setExcludeHolidays()
1056  */
1057  static void setHolidays(const KHolidays::HolidayRegion &region);
1058 
1059  /** Enable or disable the alarm on non-working days and outside working hours.
1060  * Note that this option only has any effect for recurring alarms.
1061  * @param wto true to restrict to working time, false to enable any time
1062  * @see workTimeOnly(), setWorkTime()
1063  */
1064  void setWorkTimeOnly(bool wto);
1065 
1066  /** Return whether the alarm is disabled on non-working days and outside working hours.
1067  * @see setWorkTimeOnly()
1068  */
1069  bool workTimeOnly() const;
1070 
1071  /** Check whether a date/time is during working hours and/or holidays, depending
1072  * on the flags set for the specified event.
1073  * @deprecated Use !excludedByWorkTimeOrHoliday() instead.
1074  */
1075  KALARMCAL_DEPRECATED bool isWorkingTime(const KADateTime &dt) const;
1076 
1077  /** Check whether a date/time conflicts with working hours and/or holiday
1078  * restrictions for the alarm.
1079  * @return true if the alarm is disabled from occurring at time @p dt
1080  * because @p dt is outside working hours (if the alarm is
1081  * working time only) or is during a holiday (if the alarm is
1082  * disabled on holidays);
1083  * false if the alarm is permitted to occur at time @p dt. (But
1084  * note that no check is made as to whether the alarm is
1085  * actually scheduled to occur at time @p dt.)
1086  */
1087  bool excludedByWorkTimeOrHoliday(const KADateTime &dt) const;
1088 
1089  /** Set working days and times, to be used by all KAEvent instances.
1090  * @param days bits set to 1 for each working day. Array element 0 = Monday ... 6 = Sunday.
1091  * @param start start time in working day.
1092  * @param end end time in working day.
1093  * @see setWorkTimeOnly(), excludedByWorkTimeOrHoliday()
1094  */
1095  static void setWorkTime(const QBitArray &days, const QTime &start, const QTime &end);
1096 
1097  /** Clear the event's recurrence and sub-repetition data.
1098  * @see setRecurrence(), recurs()
1099  */
1100  void setNoRecur();
1101 
1102  /** Initialise the event's recurrence from a KARecurrence.
1103  * The event's start date/time is not changed.
1104  * @see setRecurMinutely(), setRecurDaily(), setRecurWeekly(), setRecurMonthlyByDate(), setRecurMonthlyByPos(), setRecurAnnualByDate(), setRecurAnnualByPos(), setFirstRecurrence()
1105  */
1106  void setRecurrence(const KARecurrence &r);
1107 
1108  /** Set the recurrence to recur at a minutes interval.
1109  * @param freq how many minutes between recurrences.
1110  * @param count number of occurrences, including first and last;
1111  * = -1 to recur indefinitely;
1112  * = 0 to use @p end instead.
1113  * @param end = end date/time (set invalid to use @p count instead).
1114  * @return @c false if no recurrence was set up.
1115  */
1116  bool setRecurMinutely(int freq, int count, const KADateTime &end);
1117 
1118  /** Set the recurrence to recur daily.
1119  * @param freq how many days between recurrences.
1120  * @param days which days of the week alarms are allowed to occur on.
1121  * @param count number of occurrences, including first and last;
1122  * = -1 to recur indefinitely;
1123  * = 0 to use @p end instead.
1124  * @param end = end date (set invalid to use @p count instead).
1125  * @return @c false if no recurrence was set up.
1126  */
1127  bool setRecurDaily(int freq, const QBitArray &days, int count, QDate end);
1128 
1129  /** Set the recurrence to recur weekly, on the specified weekdays.
1130  * @param freq how many weeks between recurrences.
1131  * @param days which days of the week alarms are allowed to occur on.
1132  * @param count number of occurrences, including first and last;
1133  * = -1 to recur indefinitely;
1134  * = 0 to use @p end instead.
1135  * @param end = end date (set invalid to use @p count instead).
1136  * @return @c false if no recurrence was set up.
1137  */
1138  bool setRecurWeekly(int freq, const QBitArray &days, int count, QDate end);
1139 
1140  /** Set the recurrence to recur monthly, on the specified days within the month.
1141  * @param freq how many months between recurrences.
1142  * @param days which days of the month alarms should occur on.
1143  * @param count number of occurrences, including first and last;
1144  * = -1 to recur indefinitely;
1145  * = 0 to use @p end instead.
1146  * @param end = end date (set invalid to use @p count instead).
1147  * @return @c false if no recurrence was set up.
1148  */
1149  bool setRecurMonthlyByDate(int freq, const QVector<int> &days, int count, QDate end);
1150 
1151  /** Holds days of the week combined with a week number in the month,
1152  * used to specify some monthly or annual recurrences. */
1153  struct MonthPos {
1154  MonthPos() : days(7) {} //krazy:exclude=inline (need default constructor)
1155  int weeknum; //!< Week in month, or < 0 to count from end of month.
1156  QBitArray days; //!< Days in week, element 0 = Monday.
1157  };
1158 
1159  /** Set the recurrence to recur monthly, on the specified weekdays in the
1160  * specified weeks of the month.
1161  * @param freq how many months between recurrences.
1162  * @param pos which days of the week/weeks of the month alarms should occur on.
1163  * @param count number of occurrences, including first and last;
1164  * = -1 to recur indefinitely;
1165  * = 0 to use @p end instead.
1166  * @param end = end date (set invalid to use @p count instead).
1167  * @return @c false if no recurrence was set up.
1168  */
1169  bool setRecurMonthlyByPos(int freq, const QVector<MonthPos> &pos, int count, QDate end);
1170 
1171  /** Set the recurrence to recur annually, on the specified day in each
1172  * of the specified months.
1173  * @param freq how many years between recurrences.
1174  * @param months which months of the year alarms should occur on.
1175  * @param day day of month, or 0 to use event start date.
1176  * @param feb29 for a February 29th recurrence, when February 29th should
1177  * recur in non-leap years.
1178  * @param count number of occurrences, including first and last;
1179  * = -1 to recur indefinitely;
1180  * = 0 to use @p end instead.
1181  * @param end = end date (set invalid to use @p count instead).
1182  * @return @c false if no recurrence was set up.
1183  */
1184  bool setRecurAnnualByDate(int freq, const QVector<int> &months, int day, KARecurrence::Feb29Type, int count, QDate end);
1185 
1186  /** Set the recurrence to recur annually, on the specified weekdays in the
1187  * specified weeks of the specified months.
1188  * @param freq how many years between recurrences.
1189  * @param pos which days of the week/weeks of the month alarms should occur on.
1190  * @param months which months of the year alarms should occur on.
1191  * @param count number of occurrences, including first and last;
1192  * = -1 to recur indefinitely;
1193  * = 0 to use @p end instead.
1194  * @param end = end date (set invalid to use @p count instead).
1195  * @return @c false if no recurrence was set up.
1196  */
1197  bool setRecurAnnualByPos(int freq, const QVector<MonthPos> &pos, const QVector<int> &months, int count, QDate end);
1198 
1199  /** Return whether the event recurs.
1200  * @see recurType()
1201  */
1202  bool recurs() const;
1203 
1204  /** Return the recurrence period type for the event.
1205  * Note that this does not test for repeat-at-login.
1206  * @see recurInterval()
1207  */
1208  KARecurrence::Type recurType() const;
1209 
1210  /** Return the full recurrence data for the event.
1211  * @return recurrence data, or null if none.
1212  * @see recurrenceText()
1213  */
1214  KARecurrence *recurrence() const;
1215 
1216  /** Return the recurrence interval in units of the recurrence period type
1217  * (minutes, days, etc).
1218  * @see longestRecurrenceInterval()
1219  */
1220  int recurInterval() const;
1221 
1222  /** Return the longest interval which can occur between consecutive recurrences.
1223  * @note No account is taken of any working hours or holiday restrictions
1224  * when evaluating consecutive recurrence dates/times.
1225  * @see recurInterval()
1226  */
1227  KCalendarCore::Duration longestRecurrenceInterval() const;
1228 
1229  /** Adjust the event date/time to the first recurrence of the event, on or after
1230  * the event start date/time. The event start date may not be a recurrence date,
1231  * in which case a later date will be set.
1232  * @note No account is taken of any working hours or holiday restrictions
1233  * when determining the first recurrence of the event.
1234  */
1235  void setFirstRecurrence();
1236 
1237  /** Return the recurrence interval as text suitable for display. */
1238  QString recurrenceText(bool brief = false) const;
1239 
1240  /** Initialise the event's sub-repetition.
1241  * The repetition length is adjusted if necessary to fit the recurrence interval.
1242  * If the event doesn't recur, the sub-repetition is cleared.
1243  * @return @c false if a non-daily interval was specified for a date-only recurrence.
1244  * @see repetition()
1245  */
1246  bool setRepetition(const Repetition &r);
1247 
1248  /** Return the event's sub-repetition data.
1249  * @see setRepetition(), repetitionText()
1250  */
1251  Repetition repetition() const;
1252 
1253  /** Return the count of the next sub-repetition which is due.
1254  * @note No account is taken of any working hours or holiday restrictions
1255  * when determining the next event sub-repetition.
1256  *
1257  * @return sub-repetition count (>=1), or 0 for the main recurrence.
1258  * @see nextOccurrence()
1259  */
1260  int nextRepetition() const;
1261 
1262  /** Return the repetition interval as text suitable for display. */
1263  QString repetitionText(bool brief = false) const;
1264 
1265  /** Determine whether the event will occur strictly after the specified
1266  * date/time. Reminders are ignored.
1267  * @note No account is taken of any working hours or holiday restrictions
1268  * when determining event occurrences.
1269  *
1270  * @param preDateTime the specified date/time.
1271  * @param includeRepetitions if true and the alarm has a sub-repetition, the
1272  * method will return true if any sub-repetitions
1273  * occur after @p preDateTime.
1274  * @see nextOccurrence()
1275  */
1276  bool occursAfter(const KADateTime &preDateTime, bool includeRepetitions) const;
1277 
1278  /** Set the date/time of the event to the next scheduled occurrence after a
1279  * specified date/time, provided that this is later than its current date/time.
1280  * Any reminder alarm is adjusted accordingly.
1281  * If the alarm has a sub-repetition, and a sub-repetition of a previous
1282  * recurrence occurs after the specified date/time, that sub-repetition is
1283  * set as the next occurrence.
1284  * @note No account is taken of any working hours or holiday restrictions
1285  * when determining and setting the next occurrence date/time.
1286  *
1287  * @see nextOccurrence()
1288  */
1289  OccurType setNextOccurrence(const KADateTime &preDateTime);
1290 
1291  /** Get the date/time of the next occurrence of the event, strictly after
1292  * the specified date/time. Reminders are ignored.
1293  * @note No account is taken of any working hours or holiday restrictions
1294  * when determining the next event occurrence.
1295  *
1296  * @param preDateTime the specified date/time.
1297  * @param result date/time of next occurrence, or invalid date/time if none.
1298  * @param option how/whether to make allowance for sub-repetitions.
1299  * @see nextRepetition(), setNextOccurrence(), previousOccurrence(), occursAfter()
1300  */
1301  OccurType nextOccurrence(const KADateTime &preDateTime, DateTime &result, OccurOption option = IGNORE_REPETITION) const;
1302 
1303  /** Get the date/time of the last previous occurrence of the event,
1304  * strictly before the specified date/time. Reminders are ignored.
1305  * @note No account is taken of any working hours or holiday restrictions
1306  * when determining the previous event occurrence.
1307  *
1308  * @param afterDateTime the specified date/time.
1309  * @param result date/time of previous occurrence, or invalid
1310  * date/time if none.
1311  * @param includeRepetitions if true and the alarm has a sub-repetition, the
1312  * last previous repetition is returned if
1313  * appropriate.
1314  * @see nextOccurrence()
1315  */
1316  OccurType previousOccurrence(const KADateTime &afterDateTime, DateTime &result, bool includeRepetitions = false) const;
1317 
1318  /** Set the event to be a copy of the specified event, making the specified
1319  * alarm the 'displaying' alarm.
1320  * The purpose of setting up a 'displaying' alarm is to be able to reinstate
1321  * the alarm message in case of a crash, or to reinstate it should the user
1322  * choose to defer the alarm. Note that even repeat-at-login alarms need to be
1323  * saved in case their end time expires before the next login.
1324  * @param event the event to copy
1325  * @param type the alarm type (main, reminder, deferred etc.)
1326  * @param colId the ID of the calendar resource which originally contained the event
1327  * @param repeatAtLoginTime repeat-at-login time if @p type == AT_LOGIN_ALARM, else ignored
1328  * @param showEdit whether the Edit button was displayed
1329  * @param showDefer whether the Defer button was displayed
1330  * @return @c true if successful, @c false if alarm was not copied.
1331  */
1332  bool setDisplaying(const KAEvent &event, KAAlarm::Type type, ResourceId colId, const KADateTime &repeatAtLoginTime, bool showEdit, bool showDefer);
1333 
1334  /** Reinstate the original event from the 'displaying' event.
1335  * This instance is initialised from the supplied displaying @p event,
1336  * and appropriate adjustments are made to convert it back to the
1337  * original pre-displaying state.
1338  * @param event the displaying event
1339  * @param colId updated to the ID of the calendar resource which
1340  * originally contained the event
1341  * @param showEdit updated to true if Edit button was displayed, else false
1342  * @param showDefer updated to true if Defer button was displayed, else false
1343  */
1344  void reinstateFromDisplaying(const KCalendarCore::Event::Ptr &event, ResourceId &colId, bool &showEdit, bool &showDefer);
1345 
1346  /** Return the original alarm which the displaying alarm refers to.
1347  * Note that the caller is responsible for ensuring that the event was
1348  * a displaying event; this check is not made in convertDisplayingAlarm()
1349  * since it is normally called after reinstateFromDisplaying(), which
1350  * resets the instance so that displaying() returns false.
1351  */
1352  KAAlarm convertDisplayingAlarm() const;
1353 
1354  /** Return whether the alarm is currently being displayed, i.e. is in the displaying calendar. */
1355  bool displaying() const;
1356 
1357  /** Return the alarm of a specified type.
1358  * @param type alarm type to return.
1359  * @see nextAlarm(), alarmCount()
1360  */
1361  KAAlarm alarm(KAAlarm::Type type) const;
1362 
1363  /** Return the main alarm for the event.
1364  * If the main alarm does not exist, one of the subsidiary ones is returned if
1365  * possible.
1366  * N.B. a repeat-at-login alarm can only be returned if it has been read from/
1367  * written to the calendar file.
1368  * @see nextAlarm()
1369  */
1370  KAAlarm firstAlarm() const;
1371 
1372  /** Return the next alarm for the event, after the specified alarm.
1373  * @see firstAlarm()
1374  */
1375  KAAlarm nextAlarm(const KAAlarm &previousAlarm) const;
1376 
1377  /** Return the next alarm for the event, after the specified alarm type.
1378  * @see firstAlarm()
1379  */
1380  KAAlarm nextAlarm(KAAlarm::Type previousType) const;
1381 
1382  /** Return the number of alarms in the event, i.e. the count of:
1383  * - main alarm
1384  * - repeat-at-login alarm
1385  * - deferral alarm
1386  * - reminder alarm
1387  * - displaying alarm
1388  */
1389  int alarmCount() const;
1390 
1391  /** Remove the alarm of the specified type from the event.
1392  * This must only be called to remove an alarm which has expired, not to
1393  * reconfigure the event.
1394  */
1395  void removeExpiredAlarm(KAAlarm::Type type);
1396 
1397  /** Data categories for compare(). */
1398  enum class Compare {
1399  Id = 0x01, //!< the event ID
1400  ICalendar = 0x02, //!< extra event properties in the iCalendar file: custom properties, revision, creation timestamp
1401  UserSettable = 0x04, //!< user settable data: resource ID, item ID
1402  CurrentState = 0x08 //!< changeable data which records the event's current state: next trigger time etc.
1403  };
1404  Q_DECLARE_FLAGS(Comparison, Compare)
1405 
1406  /** Compare this instance with another.
1407  * All data which defines the characteristics of this event will be
1408  * compared, plus optional data categories as specified.
1409  * @param other the other event to be compared.
1410  * @param comparison the optional data categories to compare, in addition
1411  * to the basic data. Other optional categories will be
1412  * ignored in the comparison.
1413  * @return true if the instances match, false otherwise.
1414  */
1415  bool compare(const KAEvent& other, Comparison comparison) const;
1416 
1417  /** Call before making a group of changes to the event, to avoid unnecessary
1418  * calculation intensive recalculations of trigger times from being
1419  * performed until all the changes have been applied. When the changes
1420  * are complete, endChanges() should be called to allow resultant
1421  * updates to occur.
1422  */
1423  void startChanges();
1424 
1425  /** Call when a group of changes preceded by startChanges() is complete, to
1426  * allow resultant updates to occur.
1427  */
1428  void endChanges();
1429 
1430  /** Return the current KAlarm calendar storage format version.
1431  * This is the KAlarm version which first used the current calendar/event
1432  * format. It is NOT the KAlarmCal library .so version!
1433  * @return version in the format returned by KAlarmCal::Version().
1434  * @see currentCalendarVersionString()
1435  */
1436  static int currentCalendarVersion();
1437 
1438  /** Return the current KAlarm calendar storage format version.
1439  * This is the KAlarm version which first used the current calendar/event
1440  * format. It is NOT the KAlarmCal library .so version!
1441  * @return version as a string in the format "1.2.3".
1442  * @see currentCalendarVersion()
1443  */
1444  static QByteArray currentCalendarVersionString();
1445 
1446  /** If a calendar was written by a previous version of KAlarm, do any
1447  * necessary format conversions on the events to ensure that when the calendar
1448  * is saved, no information is lost or corrupted.
1449  * @param calendar calendar whose events are to be converted.
1450  * @param calendarVersion KAlarm calendar format version of @p calendar, in the
1451  * format returned by KAlarmCal::Version(). The KDE 3.0.0
1452  * version 0.5.7 requires a special adjustment for
1453  * summer time and should be passed negated (-507) to
1454  * distinguish it from the KDE 3.0.1 version 0.5.7
1455  * which does not require the adjustment.
1456  * @return @c true if any conversions were done.
1457  */
1458  static bool convertKCalEvents(const KCalendarCore::Calendar::Ptr &, int calendarVersion);
1459 
1460  /** Return a list of pointers to a list of KAEvent objects. */
1461  static List ptrList(QVector<KAEvent> &events);
1462 
1463  /** Output the event's data as debug output. */
1464  void dumpDebug() const;
1465 
1466 private:
1468 };
1469 
1470 } // namespace KAlarmCal
1471 
1472 Q_DECLARE_OPERATORS_FOR_FLAGS(KAlarmCal::KAEvent::Flags)
1473 Q_DECLARE_OPERATORS_FOR_FLAGS(KAlarmCal::KAEvent::Comparison)
1474 Q_DECLARE_METATYPE(KAlarmCal::KAEvent)
1475 
1476 
1477 // vim: et sw=4:
QBitArray days
Days in week, element 0 = Monday.
Definition: kaevent.h:1156
Type
Alarm types.
Definition: kaevent.h:69
Type
The recurrence&#39;s period type.
Definition: karecurrence.h:52
KAAlarm represents individual alarms within a KAEvent.
Definition: kaevent.h:53
Compare
Data categories for compare().
Definition: kaevent.h:1398
A class representing a date and time with an associated time zone.
Definition: kadatetime.h:144
ExtraActionOption
Options for pre- or post-alarm actions.
Definition: kaevent.h:309
Represents a sub-repetition, defined by interval and repeat count.
Definition: repetition.h:29
there is no limit
Definition: kaevent.h:263
Feb29Type
When annual February 29th recurrences should occur in non-leap years.
Definition: karecurrence.h:64
Type
The category of an event, indicated by the middle part of its UID.
Definition: kacalendar.h:112
check for recurrences only, ignore sub-repetitions
Definition: kaevent.h:256
Represents recurrences for KAlarm.
Definition: karecurrence.h:46
KCal::Alarm::Display type: display a text message.
Definition: kaevent.h:58
Action
The basic KAAlarm action types.
Definition: kaevent.h:57
DeferLimitType
What type of occurrence currently limits how long the alarm can be deferred.
Definition: kaevent.h:262
CmdErrType
Command execution error type for last time the alarm was triggered.
Definition: kaevent.h:298
Next trigger of the main alarm, i.e.
Definition: kaevent.h:286
TriggerType
Next trigger type for an alarm.
Definition: kaevent.h:271
KCal::Alarm::Display type: display a file (URL given by the alarm text)
Definition: kaevent.h:59
verify that the KCal::Event UID is already the same as the KAEvent ID, if the latter is non-empty ...
Definition: kaevent.h:319
Next trigger, including reminders, taking account of any working hours or holiday restrictions...
Definition: kaevent.h:291
OccurOption
How to treat sub-repetitions in nextOccurrence().
Definition: kaevent.h:255
KCal::Alarm::Email type: send an email.
Definition: kaevent.h:61
leave KCal::Event UID unchanged
Definition: kaevent.h:318
OccurType
What type of occurrence is due.
Definition: kaevent.h:241
Flag
Flags for use in D-Bus calls, etc.
Definition: kaevent.h:192
KAEvent represents a KAlarm event.
Definition: kaevent.h:185
int weeknum
Week in month, or < 0 to count from end of month.
Definition: kaevent.h:1155
UidAction
How to deal with the event UID in updateKCalEvent().
Definition: kaevent.h:317
Actions
The basic action type(s) for the event&#39;s main alarm.
Definition: kaevent.h:221
KCal::Alarm::Procedure type: execute a shell command.
Definition: kaevent.h:60
return a sub-repetition if it&#39;s the next occurrence
Definition: kaevent.h:257
Holds days of the week combined with a week number in the month, used to specify some monthly or annu...
Definition: kaevent.h:1153
SubAction
The sub-action type for the event&#39;s main alarm.
Definition: kaevent.h:232
As KADateTime, but with a configurable start-of-day time for date-only values.
Definition: datetime.h:28
Next trigger, including reminders.
Definition: kaevent.h:275
Next trigger of the main alarm, i.e.
Definition: kaevent.h:280
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Jun 17 2021 23:10:34 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.