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-2020 David Jarvie <[email protected]>
6  *
7  * SPDX-License-Identifier: LGPL-2.0-or-later
8  */
9 
10 #ifndef KALARM_KAEVENT_H
11 #define KALARM_KAEVENT_H
12 
13 #include "kalarmcal_export.h"
14 
15 #include "datetime.h"
16 #include "karecurrence.h"
17 #include "kacalendar.h"
18 #include "repetition.h"
19 
20 #include <collection.h>
21 #include <item.h>
22 #include <KCalendarCore/Person>
23 #include <KCalendarCore/Calendar>
24 #include <AkonadiCore/item.h>
25 
26 #include <QBitArray>
27 #include <QColor>
28 #include <QFont>
29 #include <QVector>
30 #include <QSharedDataPointer>
31 #include <QMetaType>
32 
33 namespace KHolidays
34 {
35 class HolidayRegion;
36 }
37 
38 namespace KAlarmCal
39 {
40 
54 class KALARMCAL_EXPORT KAAlarm
55 {
56 public:
58  enum Action {
60  FILE,
63  AUDIO
64  };
65 
70  enum Type {
71  INVALID_ALARM = 0,
72  MAIN_ALARM = 1,
73  REMINDER_ALARM = 0x02,
74  DEFERRED_ALARM = 0x04,
75  DEFERRED_REMINDER_ALARM = REMINDER_ALARM | DEFERRED_ALARM,
76  // The following values must be greater than the preceding ones, to
77  // ensure that in ordered processing they are processed afterwards.
78  AT_LOGIN_ALARM = 0x10,
79  DISPLAYING_ALARM = 0x20
80 
81  // IMPORTANT: if any values are added to this list, ensure that the
82  // KAEventPrivate::AlarmType enum is adjusted similarly.
83  };
84 
86  KAAlarm();
87 
89  KAAlarm(const KAAlarm &other);
90 
92  ~KAAlarm();
93 
95  KAAlarm &operator=(const KAAlarm &other);
96 
98  Action action() const;
99 
101  bool isValid() const;
102 
104  Type type() const;
105 
112  DateTime dateTime(bool withRepeats = false) const;
113 
118  QDate date() const;
119 
126  QTime time() const;
127 
129  void setTime(const DateTime &dt);
130 
132  void setTime(const KADateTime &dt);
133 
135  bool repeatAtLogin() const;
136 
138  bool isReminder() const;
139 
141  bool deferred() const;
142 
147  bool timedDeferral() const;
148 
152  static const char *debugType(Type);
153 
154 private:
155  //@cond PRIVATE
156  class Private;
157  Private *const d;
158  //@endcond
159 
160  friend class KAEvent;
161  friend class KAEventPrivate;
162 };
163 
164 class KAEventPrivate;
165 
186 class KALARMCAL_EXPORT KAEvent
187 {
188 public:
191 
193  enum Flag {
194  BEEP = 0x02,
195  REPEAT_AT_LOGIN = 0x04,
196  ANY_TIME = 0x08,
197  CONFIRM_ACK = 0x10,
198  EMAIL_BCC = 0x20,
199  DEFAULT_FONT = 0x40,
200  REPEAT_SOUND = 0x80,
201  DISABLED = 0x100,
202  AUTO_CLOSE = 0x200,
203  SCRIPT = 0x400,
204  EXEC_IN_XTERM = 0x800,
205  SPEAK = 0x1000,
206  COPY_KORGANIZER = 0x2000,
207  EXCL_HOLIDAYS = 0x4000,
208  WORK_TIME_ONLY = 0x8000,
210  DISPLAY_COMMAND = 0x10000,
211  REMINDER_ONCE = 0x20000,
212  DONT_SHOW_ERROR = 0x40000,
213  NOTIFY = 0x80000
214 
215  // IMPORTANT: if any values are added to this list, ensure that the
216  // additional enum values in KAEventPrivate are also adjusted.
217  };
218  Q_DECLARE_FLAGS(Flags, Flag)
219 
220 
222  enum Actions {
223  ACT_NONE = 0,
224  ACT_DISPLAY = 0x01,
225  ACT_COMMAND = 0x02,
226  ACT_EMAIL = 0x04,
227  ACT_AUDIO = 0x08,
228  ACT_DISPLAY_COMMAND = ACT_DISPLAY | ACT_COMMAND,
229  ACT_ALL = ACT_DISPLAY | ACT_COMMAND | ACT_EMAIL | ACT_AUDIO
230  };
231 
233  enum SubAction {
234  MESSAGE = KAAlarm::MESSAGE,
235  FILE = KAAlarm::FILE,
236  COMMAND = KAAlarm::COMMAND,
237  EMAIL = KAAlarm::EMAIL,
238  AUDIO = KAAlarm::AUDIO
239  };
240 
242  enum OccurType {
243  NO_OCCURRENCE = 0,
244  FIRST_OR_ONLY_OCCURRENCE = 0x01,
245  RECURRENCE_DATE = 0x02,
246  RECURRENCE_DATE_TIME = 0x03,
247  LAST_RECURRENCE = 0x04,
248  OCCURRENCE_REPEAT = 0x10,
249  FIRST_OR_ONLY_OCCURRENCE_REPEAT = OCCURRENCE_REPEAT | FIRST_OR_ONLY_OCCURRENCE,
250  RECURRENCE_DATE_REPEAT = OCCURRENCE_REPEAT | RECURRENCE_DATE,
251  RECURRENCE_DATE_TIME_REPEAT = OCCURRENCE_REPEAT | RECURRENCE_DATE_TIME,
252  LAST_RECURRENCE_REPEAT = OCCURRENCE_REPEAT | LAST_RECURRENCE
253  };
254 
256  enum OccurOption {
259  ALLOW_FOR_REPETITION
260  };
261 
268  LIMIT_REMINDER
269  };
270 
272  enum TriggerType {
277  DISPLAY_TRIGGER
278  };
279 
281  enum CmdErrType {
282  CMD_NO_ERROR = 0,
283  CMD_ERROR = 0x01,
284  CMD_ERROR_PRE = 0x02,
285  CMD_ERROR_POST = 0x04,
286  CMD_ERROR_PRE_POST = CMD_ERROR_PRE | CMD_ERROR_POST
287  };
288 
293  CancelOnPreActError = 0x01,
294  DontShowPreActError = 0x02,
295  ExecPreActOnDeferral = 0x04
296  };
297  Q_DECLARE_FLAGS(ExtraActionOptions, ExtraActionOption)
298 
299 
300  enum UidAction {
303  UID_SET
304  };
305 
307  KAEvent();
308 
329  KAEvent(const KADateTime &dt, const QString &text, const QColor &bg, const QColor &fg,
330  const QFont &font, SubAction action, int lateCancel, Flags flags, bool changesPending = false);
331 
336  explicit KAEvent(const KCalendarCore::Event::Ptr &);
337 
354  KALARMCAL_DEPRECATED void set(const KCalendarCore::Event::Ptr &);
355 
356  KAEvent(const KAEvent &other);
357  ~KAEvent();
358 
359  KAEvent &operator=(const KAEvent &other);
360 
379  KALARMCAL_DEPRECATED void set(const KADateTime &dt, const QString &text, const QColor &bg,
380  const QColor &fg, const QFont &font, SubAction action, int lateCancel,
381  Flags flags, bool changesPending = false);
382 
392  bool updateKCalEvent(const KCalendarCore::Event::Ptr &event, UidAction u, bool setCustomProperties = true) const;
393 
395  bool isValid() const;
396 
398  void setEnabled(bool enable);
399 
401  bool enabled() const;
402 
404  void setReadOnly(bool ro);
405 
407  bool isReadOnly() const;
408 
412  void setArchive();
413 
415  bool toBeArchived() const;
416 
418  bool mainExpired() const;
419 
424  bool expired() const;
425 
427  Flags flags() const;
428 
430  void setCategory(CalEvent::Type type);
431 
433  CalEvent::Type category() const;
434 
438  void setEventId(const QString &id);
439 
443  QString id() const;
444 
446  void incrementRevision();
447 
449  int revision() const;
450 
454  void setCollectionId(Akonadi::Collection::Id id);
455 
457  void setResourceId(ResourceId id);
458 
467  void setCollectionId_const(Akonadi::Collection::Id id) const;
468 
476  void setResourceId_const(ResourceId id) const;
477 
481  Akonadi::Collection::Id collectionId() const;
482 
484  ResourceId resourceId() const;
485 
489  KALARMCAL_DEPRECATED void setItemId(Akonadi::Item::Id id);
490 
494  KALARMCAL_DEPRECATED Akonadi::Item::Id itemId() const;
495 
502  KALARMCAL_DEPRECATED bool setItemPayload(Akonadi::Item &, const QStringList &collectionMimeTypes) const;
503 
505  void setCompatibility(KACalendar::Compat c);
506 
508  KACalendar::Compat compatibility() const;
509 
511  QMap<QByteArray, QString> customProperties() const;
512 
519  SubAction actionSubType() const;
520 
526  Actions actionTypes() const;
527 
533  void setLateCancel(int minutes);
534 
540  int lateCancel() const;
541 
548  void setAutoClose(bool autoclose);
549 
557  bool autoClose() const;
558 
563  void setNotify(bool useNotify);
564 
571  bool notify() const;
572 
575  void setAkonadiItemId(Akonadi::Item::Id id);
576 
579  Akonadi::Item::Id akonadiItemId() const;
580 
585  QString cleanText() const;
586 
590  QString message() const;
591 
594  QString displayMessage() const;
595 
598  QString fileName() const;
599 
601  QColor bgColour() const;
602 
604  QColor fgColour() const;
605 
607  static void setDefaultFont(const QFont &font);
608 
611  bool useDefaultFont() const;
612 
614  QFont font() const;
615 
618  QString command() const;
619 
621  bool commandScript() const;
622 
624  bool commandXterm() const;
625 
627  bool commandDisplay() const;
628 
630  void setCommandError(CmdErrType error) const;
631 
633  CmdErrType commandError() const;
634 
638  bool commandHideError() const;
639 
643  void setLogFile(const QString &logfile);
646  QString logFile() const;
647 
649  bool confirmAck() const;
650 
652  bool copyToKOrganizer() const;
653 
655  void setEmail(uint from, const KCalendarCore::Person::List &, const QString &subject,
656  const QStringList &attachments);
657 
661  QString emailMessage() const;
662 
666  uint emailFromId() const;
667 
669  KCalendarCore::Person::List emailAddressees() const;
670 
672  QStringList emailAddresses() const;
673 
677  QString emailAddresses(const QString &sep) const;
678 
683  static QString joinEmailAddresses(const KCalendarCore::Person::List &addresses, const QString &sep);
685  QStringList emailPureAddresses() const;
686 
690  QString emailPureAddresses(const QString &sep) const;
691 
693  QString emailSubject() const;
694 
696  QStringList emailAttachments() const;
697 
701  QString emailAttachments(const QString &sep) const;
702 
704  bool emailBcc() const;
705 
715  void setAudioFile(const QString &filename, float volume, float fadeVolume,
716  int fadeSeconds, int repeatPause = -1, bool allowEmptyFile = false);
717 
721  QString audioFile() const;
722 
727  float soundVolume() const;
728 
733  float fadeVolume() const;
734 
738  int fadeSeconds() const;
739 
741  bool repeatSound() const;
742 
746  int repeatSoundPause() const;
747 
749  bool beep() const;
750 
752  bool speak() const;
753 
760  void setTemplate(const QString &name, int afterTime = -1);
761 
765  bool isTemplate() const;
766 
771  QString templateName() const;
772 
777  bool usingDefaultTime() const;
778 
786  int templateAfterTime() const;
787 
795  void setActions(const QString &pre, const QString &post, ExtraActionOptions preOptions);
796 
798  QString preAction() const;
799 
803  QString postAction() const;
804 
809  ExtraActionOptions extraActionOptions() const;
810 
818  void setReminder(int minutes, bool onceOnly);
819 
825  void activateReminderAfter(const DateTime &mainAlarmTime);
826 
833  int reminderMinutes() const;
834 
839  bool reminderActive() const;
840 
844  bool reminderOnceOnly() const;
845 
847  bool reminderDeferral() const;
848 
858  void defer(const DateTime &dt, bool reminder, bool adjustRecurrence = false);
859 
863  void cancelDefer();
864 
870  void setDeferDefaultMinutes(int minutes, bool dateOnly = false);
871 
875  bool deferred() const;
876 
881  DateTime deferDateTime() const;
882 
888  DateTime deferralLimit(DeferLimitType *limitType = nullptr) const;
889 
893  int deferDefaultMinutes() const;
894 
896  bool deferDefaultDateOnly() const;
897 
903  DateTime startDateTime() const;
904 
909  void setTime(const KADateTime &dt);
910 
915  DateTime mainDateTime(bool withRepeats = false) const;
916 
919  QTime mainTime() const;
920 
926  DateTime mainEndRepeatTime() const;
927 
932  static void setStartOfDay(const QTime &);
933 
939  static void adjustStartOfDay(const KAEvent::List &events);
940 
945  DateTime nextTrigger(TriggerType type) const;
946 
950  void setCreatedDateTime(const KADateTime &dt);
951 
955  KADateTime createdDateTime() const;
956 
962  void setRepeatAtLogin(bool repeat);
963 
969  bool repeatAtLogin(bool includeArchived = false) const;
970 
977  void setExcludeHolidays(bool exclude);
978 
983  bool holidaysExcluded() const;
984 
995  static void setHolidays(const KHolidays::HolidayRegion &region);
996 
1002  void setWorkTimeOnly(bool wto);
1003 
1007  bool workTimeOnly() const;
1008 
1011  bool isWorkingTime(const KADateTime &dt) const;
1012 
1019  static void setWorkTime(const QBitArray &days, const QTime &start, const QTime &end);
1020 
1024  void setNoRecur();
1025 
1030  void setRecurrence(const KARecurrence &r);
1031 
1040  bool setRecurMinutely(int freq, int count, const KADateTime &end);
1041 
1051  bool setRecurDaily(int freq, const QBitArray &days, int count, const QDate &end);
1052 
1062  bool setRecurWeekly(int freq, const QBitArray &days, int count, const QDate &end);
1063 
1073  bool setRecurMonthlyByDate(int freq, const QVector<int> &days, int count, const QDate &end);
1074 
1077  struct MonthPos {
1078  MonthPos() : days(7) {} //krazy:exclude=inline (need default constructor)
1079  int weeknum;
1081  };
1082 
1093  bool setRecurMonthlyByPos(int freq, const QVector<MonthPos> &pos, int count, const QDate &end);
1094 
1108  bool setRecurAnnualByDate(int freq, const QVector<int> &months, int day, KARecurrence::Feb29Type, int count, const QDate &end);
1109 
1121  bool setRecurAnnualByPos(int freq, const QVector<MonthPos> &pos, const QVector<int> &months, int count, const QDate &end);
1122 
1126  bool recurs() const;
1127 
1132  KARecurrence::Type recurType() const;
1133 
1138  KARecurrence *recurrence() const;
1139 
1144  int recurInterval() const;
1145 
1149  KCalendarCore::Duration longestRecurrenceInterval() const;
1150 
1155  void setFirstRecurrence();
1156 
1158  QString recurrenceText(bool brief = false) const;
1159 
1166  bool setRepetition(const Repetition &r);
1167 
1171  Repetition repetition() const;
1172 
1177  int nextRepetition() const;
1178 
1180  QString repetitionText(bool brief = false) const;
1181 
1189  bool occursAfter(const KADateTime &preDateTime, bool includeRepetitions) const;
1190 
1199  OccurType setNextOccurrence(const KADateTime &preDateTime);
1200 
1208  OccurType nextOccurrence(const KADateTime &preDateTime, DateTime &result, OccurOption option = IGNORE_REPETITION) const;
1209 
1220  OccurType previousOccurrence(const KADateTime &afterDateTime, DateTime &result, bool includeRepetitions = false) const;
1221 
1236  bool setDisplaying(const KAEvent &event, KAAlarm::Type type, ResourceId colId, const KADateTime &repeatAtLoginTime, bool showEdit, bool showDefer);
1237 
1248  void reinstateFromDisplaying(const KCalendarCore::Event::Ptr &event, ResourceId &colId, bool &showEdit, bool &showDefer);
1249 
1256  KAAlarm convertDisplayingAlarm() const;
1257 
1259  bool displaying() const;
1260 
1265  KAAlarm alarm(KAAlarm::Type type) const;
1266 
1274  KAAlarm firstAlarm() const;
1275 
1279  KAAlarm nextAlarm(const KAAlarm &previousAlarm) const;
1280 
1284  KAAlarm nextAlarm(KAAlarm::Type previousType) const;
1285 
1293  int alarmCount() const;
1294 
1299  void removeExpiredAlarm(KAAlarm::Type type);
1300 
1302  enum class Compare {
1303  Id = 0x01,
1304  ICalendar = 0x02,
1305  UserSettable = 0x04,
1306  CurrentState = 0x08
1307  };
1308  Q_DECLARE_FLAGS(Comparison, Compare)
1309 
1310 
1319  bool compare(const KAEvent& other, Comparison comparison) const;
1320 
1327  void startChanges();
1328 
1332  void endChanges();
1333 
1340  static int currentCalendarVersion();
1341 
1348  static QByteArray currentCalendarVersionString();
1349 
1362  static bool convertKCalEvents(const KCalendarCore::Calendar::Ptr &, int calendarVersion);
1363 
1365  static List ptrList(QVector<KAEvent> &events);
1366 
1368  void dumpDebug() const;
1369 
1370 private:
1372 };
1373 
1374 } // namespace KAlarmCal
1375 
1376 Q_DECLARE_OPERATORS_FOR_FLAGS(KAlarmCal::KAEvent::Flags)
1377 Q_DECLARE_OPERATORS_FOR_FLAGS(KAlarmCal::KAEvent::Comparison)
1378 Q_DECLARE_METATYPE(KAlarmCal::KAEvent)
1379 
1380 #endif // KALARM_KAEVENT_H
1381 
1382 // vim: et sw=4:
QBitArray days
Days in week, element 0 = Monday.
Definition: kaevent.h:1080
Type
Alarm types.
Definition: kaevent.h:70
Type
The recurrence&#39;s period type.
Definition: karecurrence.h:53
KAAlarm represents individual alarms within a KAEvent.
Definition: kaevent.h:54
Compare
Data categories for compare().
Definition: kaevent.h:1302
A class representing a date and time with an associated time zone.
Definition: kadatetime.h:145
ExtraActionOption
Options for pre- or post-alarm actions.
Definition: kaevent.h:292
Represents a sub-repetition, defined by interval and repeat count.
Definition: repetition.h:30
there is no limit
Definition: kaevent.h:264
Feb29Type
When annual February 29th recurrences should occur in non-leap years.
Definition: karecurrence.h:65
Type
The category of an event, indicated by the middle part of its UID.
Definition: kacalendar.h:113
check for recurrences only, ignore sub-repetitions
Definition: kaevent.h:257
Represents recurrences for KAlarm.
Definition: karecurrence.h:47
KCal::Alarm::Display type: display a text message.
Definition: kaevent.h:59
Action
The basic KAAlarm action types.
Definition: kaevent.h:58
DeferLimitType
What type of occurrence currently limits how long the alarm can be deferred.
Definition: kaevent.h:263
CmdErrType
Command execution error type for last time the alarm was triggered.
Definition: kaevent.h:281
next main working time trigger, excluding reminders
Definition: kaevent.h:275
TriggerType
Alarm trigger type.
Definition: kaevent.h:272
KCal::Alarm::Display type: display a file (URL given by the alarm text)
Definition: kaevent.h:60
verify that the KCal::Event UID is already the same as the KAEvent ID, if the latter is non-empty ...
Definition: kaevent.h:302
next actual working time trigger, including reminders
Definition: kaevent.h:276
OccurOption
How to treat sub-repetitions in nextOccurrence().
Definition: kaevent.h:256
KCal::Alarm::Email type: send an email.
Definition: kaevent.h:62
leave KCal::Event UID unchanged
Definition: kaevent.h:301
OccurType
What type of occurrence is due.
Definition: kaevent.h:242
Flag
Flags for use in D-Bus calls, etc.
Definition: kaevent.h:193
KAEvent represents a KAlarm event.
Definition: kaevent.h:186
int weeknum
Week in month, or < 0 to count from end of month.
Definition: kaevent.h:1079
UidAction
How to deal with the event UID in updateKCalEvent().
Definition: kaevent.h:300
Actions
The basic action type(s) for the event&#39;s main alarm.
Definition: kaevent.h:222
KCal::Alarm::Procedure type: execute a shell command.
Definition: kaevent.h:61
return a sub-repetition if it&#39;s the next occurrence
Definition: kaevent.h:258
Holds days of the week combined with a week number in the month, used to specify some monthly or annu...
Definition: kaevent.h:1077
SubAction
The sub-action type for the event&#39;s main alarm.
Definition: kaevent.h:233
As KADateTime, but with a configurable start-of-day time for date-only values.
Definition: datetime.h:29
next trigger, including reminders, ignoring working hours & holidays
Definition: kaevent.h:273
next trigger, excluding reminders, ignoring working hours & holidays
Definition: kaevent.h:274
QVector< KAEvent * > List
A list of pointers to KAEvent objects.
Definition: kaevent.h:190
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Sat Sep 19 2020 23:09:24 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.