• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.10.5 API Reference
  • KDE Home
  • Contact Us
 

KAlarm Library

  • kalarmcal
kaevent.h
1 /*
2  * kaevent.h - represents calendar events
3  * This file is part of kalarmcal library, which provides access to KAlarm
4  * calendar data.
5  * Copyright © 2001-2012 by David Jarvie <djarvie@kde.org>
6  *
7  * This library is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU Library General Public License as published
9  * by the Free Software Foundation; either version 2 of the License, or (at
10  * your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
15  * License for more details.
16  *
17  * You should have received a copy of the GNU Library General Public License
18  * along with this library; see the file COPYING.LIB. If not, write to the
19  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
20  * MA 02110-1301, USA.
21  */
22 
23 #ifndef KAEVENT_H
24 #define KAEVENT_H
25 
26 #include "kalarmcal_export.h"
27 
28 #include "datetime.h"
29 #include "karecurrence.h"
30 #include "kacalendar.h"
31 #include "repetition.h"
32 
33 #ifndef KALARMCAL_USE_KRESOURCES
34 #include <akonadi/collection.h>
35 #include <akonadi/item.h>
36 #include <kcalcore/person.h>
37 #include <kcalcore/calendar.h>
38 #else
39 #include <kcal/person.h>
40 #endif
41 
42 #include <QtCore/QBitArray>
43 #include <QColor>
44 #include <QFont>
45 #include <QtCore/QVector>
46 #ifdef KALARMCAL_USE_KRESOURCES
47 #include <QtCore/QList>
48 #endif
49 #include <QtCore/QSharedDataPointer>
50 #include <QtCore/QMetaType>
51 
52 namespace KHolidays { class HolidayRegion; }
53 #ifdef KALARMCAL_USE_KRESOURCES
54 namespace KCal {
55  class CalendarLocal;
56  class Event;
57 }
58 class AlarmResource;
59 #endif
60 class AlarmData;
61 
62 namespace KAlarmCal
63 {
64 
78 class KALARMCAL_EXPORT KAAlarm
79 {
80  public:
82  enum Action
83  {
84  MESSAGE,
85  FILE,
86  COMMAND,
87  EMAIL,
88  AUDIO
89  };
90 
95  enum Type
96  {
97  INVALID_ALARM = 0,
98  MAIN_ALARM = 1,
99  REMINDER_ALARM = 0x02,
100  DEFERRED_ALARM = 0x04,
101  DEFERRED_REMINDER_ALARM = REMINDER_ALARM | DEFERRED_ALARM,
102  // The following values must be greater than the preceding ones, to
103  // ensure that in ordered processing they are processed afterwards.
104  AT_LOGIN_ALARM = 0x10,
105  DISPLAYING_ALARM = 0x20
106 
107  // IMPORTANT: if any values are added to this list, ensure that the
108  // KAEvent::Private::AlarmType enum is adjusted similarly.
109  };
110 
112  KAAlarm();
113 
115  KAAlarm(const KAAlarm& other);
116 
118  ~KAAlarm();
119 
121  KAAlarm& operator=(const KAAlarm& other);
122 
124  Action action() const;
125 
127  bool isValid() const;
128 
130  Type type() const;
131 
138  DateTime dateTime(bool withRepeats = false) const;
139 
144  QDate date() const;
145 
152  QTime time() const;
153 
155  void setTime(const DateTime& dt);
157  void setTime(const KDateTime& dt);
158 
160  bool repeatAtLogin() const;
161 
163  bool isReminder() const;
164 
166  bool deferred() const;
167 
172  bool timedDeferral() const;
173 
177  static const char* debugType(Type);
178 
179  private:
180  //@cond PRIVATE
181  class Private;
182  Private* const d;
183  //@endcond
184 
185  friend class KAEvent;
186 };
187 
188 
209 class KALARMCAL_EXPORT KAEvent
210 {
211  public:
213  typedef QVector<KAEvent*> List;
214 
216  enum Flag
217  {
218  BEEP = 0x02,
219  REPEAT_AT_LOGIN = 0x04,
220  ANY_TIME = 0x08,
221  CONFIRM_ACK = 0x10,
222  EMAIL_BCC = 0x20,
223  DEFAULT_FONT = 0x40,
224  REPEAT_SOUND = 0x80,
225  DISABLED = 0x100,
226  AUTO_CLOSE = 0x200,
227  SCRIPT = 0x400,
228  EXEC_IN_XTERM = 0x800,
229  SPEAK = 0x1000,
230  COPY_KORGANIZER = 0x2000,
231  EXCL_HOLIDAYS = 0x4000,
232  WORK_TIME_ONLY = 0x8000,
233  DISPLAY_COMMAND = 0x10000,
234  REMINDER_ONCE = 0x20000
235 
236  // IMPORTANT: if any values are added to this list, ensure that the
237  // additional enum values in KAEvent::Private are also adjusted.
238  };
239  Q_DECLARE_FLAGS(Flags, Flag)
240 
241 
243  enum Actions
244  {
245  ACT_NONE = 0,
246  ACT_DISPLAY = 0x01,
247  ACT_COMMAND = 0x02,
248  ACT_EMAIL = 0x04,
249  ACT_AUDIO = 0x08,
250  ACT_DISPLAY_COMMAND = ACT_DISPLAY | ACT_COMMAND,
251  ACT_ALL = ACT_DISPLAY | ACT_COMMAND | ACT_EMAIL | ACT_AUDIO
252  };
253 
255  enum SubAction
256  {
257  MESSAGE = KAAlarm::MESSAGE,
258  FILE = KAAlarm::FILE,
259  COMMAND = KAAlarm::COMMAND,
260  EMAIL = KAAlarm::EMAIL,
261  AUDIO = KAAlarm::AUDIO
262  };
263 
265  enum OccurType
266  {
267  NO_OCCURRENCE = 0,
268  FIRST_OR_ONLY_OCCURRENCE = 0x01,
269  RECURRENCE_DATE = 0x02,
270  RECURRENCE_DATE_TIME = 0x03,
271  LAST_RECURRENCE = 0x04,
272  OCCURRENCE_REPEAT = 0x10,
273  FIRST_OR_ONLY_OCCURRENCE_REPEAT = OCCURRENCE_REPEAT | FIRST_OR_ONLY_OCCURRENCE,
274  RECURRENCE_DATE_REPEAT = OCCURRENCE_REPEAT | RECURRENCE_DATE,
275  RECURRENCE_DATE_TIME_REPEAT = OCCURRENCE_REPEAT | RECURRENCE_DATE_TIME,
276  LAST_RECURRENCE_REPEAT = OCCURRENCE_REPEAT | LAST_RECURRENCE
277  };
278 
280  enum OccurOption
281  {
282  IGNORE_REPETITION,
283  RETURN_REPETITION,
284  ALLOW_FOR_REPETITION
285  };
286 
288  enum DeferLimitType
289  {
290  LIMIT_NONE,
291  LIMIT_MAIN,
292  LIMIT_RECURRENCE,
293  LIMIT_REPETITION,
294  LIMIT_REMINDER
295  };
296 
298  enum TriggerType
299  {
300  ALL_TRIGGER,
301  MAIN_TRIGGER,
302  WORK_TRIGGER,
303  ALL_WORK_TRIGGER,
304  DISPLAY_TRIGGER
305  };
306 
308  enum CmdErrType
309  {
310  CMD_NO_ERROR = 0,
311  CMD_ERROR = 0x01,
312  CMD_ERROR_PRE = 0x02,
313  CMD_ERROR_POST = 0x04,
314  CMD_ERROR_PRE_POST = CMD_ERROR_PRE | CMD_ERROR_POST
315  };
316 
320  enum ExtraActionOption
321  {
322  CancelOnPreActError = 0x01,
323  DontShowPreActError = 0x02,
324  ExecPreActOnDeferral = 0x04
325  };
326  Q_DECLARE_FLAGS(ExtraActionOptions, ExtraActionOption)
327 
328 
329  enum UidAction
330  {
331  UID_IGNORE,
332  UID_CHECK,
333  UID_SET
334  };
335 
337  KAEvent();
338 
357  KAEvent(const KDateTime&, const QString& text, const QColor& bg, const QColor& fg,
358  const QFont& f, SubAction, int lateCancel, Flags flags, bool changesPending = false);
359 #ifndef KALARMCAL_USE_KRESOURCES
360 
361  explicit KAEvent(const KCalCore::Event::Ptr&);
362 
364  void set(const KCalCore::Event::Ptr&);
365 #else
366 
367  explicit KAEvent(const KCal::Event*);
368 
370  void set(const KCal::Event*);
371 #endif
372 
373  KAEvent(const KAEvent& other);
374  ~KAEvent();
375 
376  KAEvent& operator=(const KAEvent& other);
377 
395  void set(const KDateTime& dt, const QString& text, const QColor& bg,
396  const QColor& fg, const QFont& font, SubAction action, int lateCancel,
397  Flags flags, bool changesPending = false);
398 
399 #ifndef KALARMCAL_USE_KRESOURCES
400 
409  bool updateKCalEvent(const KCalCore::Event::Ptr& event, UidAction u, bool setCustomProperties = true) const;
410 #else
411 
415  bool updateKCalEvent(KCal::Event* event, UidAction u) const;
416 #endif
417 
419  bool isValid() const;
420 
422  void setEnabled(bool enable);
424  bool enabled() const;
425 
426 #ifndef KALARMCAL_USE_KRESOURCES
427 
428  void setReadOnly(bool ro);
430  bool isReadOnly() const;
431 #endif
432 
436  void setArchive();
438  bool toBeArchived() const;
439 
441  bool mainExpired() const;
446  bool expired() const;
447 
449  Flags flags() const;
450 
452  void setCategory(CalEvent::Type type);
453 
455  CalEvent::Type category() const;
456 
460  void setEventId(const QString& id);
461 
465  QString id() const;
466 
468  void incrementRevision();
470  int revision() const;
471 
472 #ifndef KALARMCAL_USE_KRESOURCES
473 
474  void setCollectionId(Akonadi::Collection::Id id);
482  void setCollectionId_const(Akonadi::Collection::Id id) const;
484  Akonadi::Collection::Id collectionId() const;
485 
487  void setItemId(Akonadi::Item::Id id);
489  Akonadi::Item::Id itemId() const;
490 
496  bool setItemPayload(Akonadi::Item&, const QStringList& collectionMimeTypes) const;
497 
499  void setCompatibility(KACalendar::Compat c);
501  KACalendar::Compat compatibility() const;
502 
504  QMap<QByteArray, QString> customProperties() const;
505 #else
506 
510  void setResource(AlarmResource* r);
511 
515  AlarmResource* resource() const;
516 #endif
517 
524  SubAction actionSubType() const;
525 
531  Actions actionTypes() const;
532 
538  void setLateCancel(int minutes);
539 
545  int lateCancel() const;
546 
553  void setAutoClose(bool autoclose);
554 
562  bool autoClose() const;
563 
564  void setKMailSerialNumber(unsigned long n);
565  unsigned long kmailSerialNumber() const;
566 
571  QString cleanText() const;
575  QString message() const;
578  QString displayMessage() const;
581  QString fileName() const;
582 
584  QColor bgColour() const;
586  QColor fgColour() const;
587 
589  static void setDefaultFont(const QFont& font);
592  bool useDefaultFont() const;
594  QFont font() const;
595 
598  QString command() const;
600  bool commandScript() const;
602  bool commandXterm() const;
604  bool commandDisplay() const;
605 #ifndef KALARMCAL_USE_KRESOURCES
606 
607  void setCommandError(CmdErrType error) const;
608 #else
609 
612  void setCommandError(CmdErrType error, bool writeConfig = true) const;
616  void setCommandError(const QString& configString);
618  static QString commandErrorConfigGroup();
619 #endif
620 
621  CmdErrType commandError() const;
622 
626  void setLogFile(const QString& logfile);
629  QString logFile() const;
630 
632  bool confirmAck() const;
633 
635  bool copyToKOrganizer() const;
636 
638 #ifndef KALARMCAL_USE_KRESOURCES
639  void setEmail(uint from, const KCalCore::Person::List&, const QString& subject,
640  const QStringList& attachments);
641 #else
642  void setEmail(uint from, const QList<KCal::Person>&, const QString& subject,
643  const QStringList& attachments);
644 #endif
645 
649  QString emailMessage() const;
650 
654  uint emailFromId() const;
655 
657 #ifndef KALARMCAL_USE_KRESOURCES
658  KCalCore::Person::List emailAddressees() const;
659 #else
660  QList<KCal::Person> emailAddressees() const;
661 #endif
662 
664  QStringList emailAddresses() const;
665 
669  QString emailAddresses(const QString& sep) const;
670 
674 #ifndef KALARMCAL_USE_KRESOURCES
675  static QString joinEmailAddresses(const KCalCore::Person::List& addresses, const QString& sep);
676 #else
677  static QString joinEmailAddresses(const QList<KCal::Person>& addresses, const QString& sep);
678 #endif
679 
681  QStringList emailPureAddresses() const;
682 
686  QString emailPureAddresses(const QString& sep) const;
687 
689  QString emailSubject() const;
690 
692  QStringList emailAttachments() const;
693 
697  QString emailAttachments(const QString& sep) const;
698 
700  bool emailBcc() const;
701 
711  void setAudioFile(const QString& filename, float volume, float fadeVolume,
712  int fadeSeconds, int repeatPause = -1, bool allowEmptyFile = false);
713 
717  QString audioFile() const;
718 
723  float soundVolume() const;
724 
729  float fadeVolume() const;
730 
734  int fadeSeconds() const;
735 
737  bool repeatSound() const;
738 
742  int repeatSoundPause() const;
743 
745  bool beep() const;
746 
748  bool speak() const;
749 
756  void setTemplate(const QString& name, int afterTime = -1);
757 
761  bool isTemplate() const;
762 
767  QString templateName() const;
768 
773  bool usingDefaultTime() const;
774 
782  int templateAfterTime() const;
783 
791  void setActions(const QString& pre, const QString& post, ExtraActionOptions options);
792 
801  void setActions(const QString& pre, const QString& post, bool cancelOnError, bool dontShowError);
802 
804  QString preAction() const;
805 
809  QString postAction() const;
810 
815  ExtraActionOptions extraActionOptions() const;
816 
821  bool cancelOnPreActionError() const;
822 
828  bool dontShowPreActionError() const;
829 
837  void setReminder(int minutes, bool onceOnly);
838 
844  void activateReminderAfter(const DateTime& mainAlarmTime);
845 
852  int reminderMinutes() const;
857  bool reminderActive() const;
861  bool reminderOnceOnly() const;
863  bool reminderDeferral() const;
864 
874  void defer(const DateTime& dt, bool reminder, bool adjustRecurrence = false);
875 
879  void cancelDefer();
885  void setDeferDefaultMinutes(int minutes, bool dateOnly = false);
889  bool deferred() const;
894  DateTime deferDateTime() const;
895 
901  DateTime deferralLimit(DeferLimitType* limitType = 0) const;
902 
906  int deferDefaultMinutes() const;
908  bool deferDefaultDateOnly() const;
909 
914  DateTime startDateTime() const;
919  void setTime(const KDateTime& dt);
924  DateTime mainDateTime(bool withRepeats = false) const;
925 
928  QTime mainTime() const;
934  DateTime mainEndRepeatTime() const;
935 
940  static void setStartOfDay(const QTime&);
941 
947  static void adjustStartOfDay(const KAEvent::List& events);
948 
953  DateTime nextTrigger(TriggerType type) const;
954 
958  void setCreatedDateTime(const KDateTime& dt);
962  KDateTime createdDateTime() const;
963 
969  void setRepeatAtLogin(bool repeat);
970 
976  bool repeatAtLogin(bool includeArchived = false) const;
977 
984  void setExcludeHolidays(bool exclude);
988  bool holidaysExcluded() const;
989 
1000  static void setHolidays(const KHolidays::HolidayRegion& region);
1001 
1007  void setWorkTimeOnly(bool wto);
1011  bool workTimeOnly() const;
1012 
1015  bool isWorkingTime(const KDateTime& dt) const;
1016 
1023  static void setWorkTime(const QBitArray& days, const QTime& start, const QTime& end);
1024 
1028  void setNoRecur();
1029 
1034  void setRecurrence(const KARecurrence& r);
1035 
1044  bool setRecurMinutely(int freq, int count, const KDateTime& end);
1045 
1055  bool setRecurDaily(int freq, const QBitArray& days, int count, const QDate& end);
1056 
1066  bool setRecurWeekly(int freq, const QBitArray& days, int count, const QDate& end);
1067 
1077  bool setRecurMonthlyByDate(int freq, const QVector<int>& days, int count, const QDate& end);
1078 
1081  struct MonthPos
1082  {
1083  MonthPos() : days(7) {} //krazy:exclude=inline (need default constructor)
1084  int weeknum;
1085  QBitArray days;
1086  };
1087 
1098  bool setRecurMonthlyByPos(int freq, const QVector<MonthPos>& pos, int count, const QDate& end);
1099 
1113  bool setRecurAnnualByDate(int freq, const QVector<int>& months, int day, KARecurrence::Feb29Type, int count, const QDate& end);
1114 
1126  bool setRecurAnnualByPos(int freq, const QVector<MonthPos>& pos, const QVector<int>& months, int count, const QDate& end);
1127 
1131  bool recurs() const;
1136  KARecurrence::Type recurType() const;
1141  KARecurrence* recurrence() const;
1142 
1147  int recurInterval() const;
1148 
1152 #ifndef KALARMCAL_USE_KRESOURCES
1153  KCalCore::Duration longestRecurrenceInterval() const;
1154 #else
1155  KCal::Duration longestRecurrenceInterval() const;
1156 #endif
1157 
1162  void setFirstRecurrence();
1163 
1165  QString recurrenceText(bool brief = false) const;
1166 
1173  bool setRepetition(const Repetition& r);
1174 
1178  Repetition repetition() const;
1179 
1184  int nextRepetition() const;
1185 
1187  QString repetitionText(bool brief = false) const;
1188 
1195  bool occursAfter(const KDateTime& preDateTime, bool includeRepetitions) const;
1196 
1205  OccurType setNextOccurrence(const KDateTime& preDateTime);
1206 
1213  OccurType nextOccurrence(const KDateTime& preDateTime, DateTime& result, OccurOption option = IGNORE_REPETITION) const;
1214 
1224  OccurType previousOccurrence(const KDateTime& afterDateTime, DateTime& result, bool includeRepetitions = false) const;
1225 
1240 #ifndef KALARMCAL_USE_KRESOURCES
1241  bool setDisplaying(const KAEvent& event, KAAlarm::Type type, Akonadi::Collection::Id colId, const KDateTime& repeatAtLoginTime, bool showEdit, bool showDefer);
1242 #else
1243  bool setDisplaying(const KAEvent& event, KAAlarm::Type type, const QString& resourceID, const KDateTime& repeatAtLoginTime, bool showEdit, bool showDefer);
1244 #endif
1245 
1246 #ifndef KALARMCAL_USE_KRESOURCES
1247 
1256  void reinstateFromDisplaying(const KCalCore::Event::Ptr& event, Akonadi::Collection::Id& colId, bool& showEdit, bool& showDefer);
1257 #else
1258  void reinstateFromDisplaying(const KCal::Event* event, QString& resourceID, bool& showEdit, bool& showDefer);
1259 #endif
1260 
1267  KAAlarm convertDisplayingAlarm() const;
1268 
1270  bool displaying() const;
1271 
1276  KAAlarm alarm(KAAlarm::Type type) const;
1277 
1285  KAAlarm firstAlarm() const;
1286 
1290  KAAlarm nextAlarm(const KAAlarm& previousAlarm) const;
1294  KAAlarm nextAlarm(KAAlarm::Type previousType) const;
1295 
1303  int alarmCount() const;
1304 
1309  void removeExpiredAlarm(KAAlarm::Type type);
1310 
1317  void startChanges();
1321  void endChanges();
1322 
1327  static int currentCalendarVersion();
1328 
1333  static QByteArray currentCalendarVersionString();
1334 
1347 #ifndef KALARMCAL_USE_KRESOURCES
1348  static bool convertKCalEvents(const KCalCore::Calendar::Ptr&, int calendarVersion);
1349 #else
1350  static bool convertKCalEvents(KCal::CalendarLocal&, int calendarVersion);
1351 #endif
1352 
1353 #ifndef KALARMCAL_USE_KRESOURCES
1354 
1355  static List ptrList(QVector<KAEvent>& events);
1356 #endif
1357 
1359  void dumpDebug() const;
1360 
1361  private:
1362  class Private;
1363  QSharedDataPointer<Private> d;
1364 };
1365 
1366 } // namespace KAlarmCal
1367 
1368 Q_DECLARE_OPERATORS_FOR_FLAGS(KAlarmCal::KAEvent::Flags)
1369 Q_DECLARE_METATYPE(KAlarmCal::KAEvent)
1370 
1371 #endif // KAEVENT_H
1372 
1373 // vim: et sw=4:
This file is part of the KDE documentation.
Documentation copyright © 1996-2013 The KDE developers.
Generated on Sat Jul 13 2013 01:30:15 by doxygen 1.8.3.1 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KAlarm Library

Skip menu "KAlarm Library"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • Related Pages

kdepimlibs-4.10.5 API Reference

Skip menu "kdepimlibs-4.10.5 API Reference"
  • akonadi
  •   contact
  •   kmime
  •   socialutils
  • kabc
  • kalarmcal
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal