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

KDE's Doxygen guidelines are available online.