KCalendarCore

calendar.h
Go to the documentation of this file.
1 /*
2  This file is part of the kcalcore library.
3 
4  SPDX-FileCopyrightText: 1998 Preston Brown <[email protected]>
5  SPDX-FileCopyrightText 2001, 2003, 2004 Cornelius Schumacher <[email protected]>
6  SPDX-FileCopyrightText: 2003-2004 Reinhold Kainhofer <[email protected]>
7  SPDX-FileCopyrightText: 2006 David Jarvie <[email protected]>
8 
9  SPDX-License-Identifier: LGPL-2.0-or-later
10 */
22 /*
23 
24 TODO: KDE5:
25 
26 This API needs serious cleaning up:
27 - Most (all) methods aren't async ( deleteIncidence(), addIncidence(), load(), save(), ... )
28  so it's not very easy to make a derived class that loads from akonadi.
29 
30 - It has too many methods. Why do we need fooEvent()/fooJournal()/fooTodo() when fooIncidence()
31  should be enough.
32 
33 */
34 
35 #ifndef KCALCORE_CALENDAR_H
36 #define KCALCORE_CALENDAR_H
37 
38 #include "kcalendarcore_export.h"
39 #include "event.h"
40 #include "customproperties.h"
41 #include "incidence.h"
42 #include "journal.h"
43 #include "todo.h"
44 
45 #include <QObject>
46 #include <QDateTime>
47 #include <QTimeZone>
48 
50 namespace KCalendarCore
51 {
52 
53 class CalFilter;
54 class Person;
55 class ICalFormat;
56 
63 };
64 
73 };
74 
86 };
87 
95 };
96 
119 class KCALENDARCORE_EXPORT Calendar : public QObject, public CustomProperties,
121 {
122  Q_OBJECT
123  Q_PROPERTY(QString productId READ productId WRITE setProductId) //clazy:exclude=qproperty-without-notify
124  Q_PROPERTY(KCalendarCore::Person owner READ owner WRITE setOwner)
125 
126 public:
127 
132 
141  explicit Calendar(const QTimeZone &timeZone);
142 
154  explicit Calendar(const QByteArray &timeZoneId);
155 
159  ~Calendar() override;
160 
168  void setProductId(const QString &id);
169 
175  Q_REQUIRED_RESULT QString productId() const;
176 
184  void setOwner(const Person &owner);
185 
193  Q_REQUIRED_RESULT Person owner() const;
194 
201  void setTimeZone(const QTimeZone &timeZone);
202 
209  Q_REQUIRED_RESULT QTimeZone timeZone() const;
210 
222  void setTimeZoneId(const QByteArray &timeZoneId);
223 
231  Q_REQUIRED_RESULT QByteArray timeZoneId() const;
232 
247  void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone);
248 
257  void setModified(bool modified);
258 
266  Q_REQUIRED_RESULT bool isModified() const;
267 
271  virtual void close() = 0;
272 
279  virtual bool save();
280 
288  virtual bool reload();
289 
295  virtual bool isSaving() const;
296 
302  Q_REQUIRED_RESULT QStringList categories() const;
303 
304  // Incidence Specific Methods //
305 
312  virtual void startBatchAdding();
313 
319  virtual void endBatchAdding();
320 
324  Q_REQUIRED_RESULT bool batchAdding() const;
325 
335  virtual bool addIncidence(const Incidence::Ptr &incidence);
336 
346  virtual bool deleteIncidence(const Incidence::Ptr &incidence);
347 
353  virtual Incidence::List incidences() const;
354 
362  virtual Incidence::List incidences(const QDate &date) const;
363 
369  virtual Incidence::List rawIncidences() const;
370 
378  virtual Incidence::List instances(const Incidence::Ptr &incidence) const;
379 
380  // Notebook Specific Methods //
381 
386  virtual void clearNotebookAssociations();
387 
396  virtual bool setNotebook(const Incidence::Ptr &incidence, const QString &notebook);
397 
405  virtual QString notebook(const Incidence::Ptr &incidence) const;
406 
414  virtual QString notebook(const QString &uid) const;
415 
421  virtual QStringList notebooks() const;
422 
430  Q_REQUIRED_RESULT bool hasValidNotebook(const QString &notebook) const;
431 
441  Q_REQUIRED_RESULT bool addNotebook(const QString &notebook, bool isVisible);
442 
452  Q_REQUIRED_RESULT bool updateNotebook(const QString &notebook, bool isVisible);
453 
462  Q_REQUIRED_RESULT bool deleteNotebook(const QString &notebook);
463 
470  Q_REQUIRED_RESULT bool setDefaultNotebook(const QString &notebook);
471 
477  Q_REQUIRED_RESULT QString defaultNotebook() const;
478 
484  Q_REQUIRED_RESULT bool isVisible(const Incidence::Ptr &incidence) const;
485 
491  Q_REQUIRED_RESULT bool isVisible(const QString &notebook) const;
492 
499  virtual Incidence::List incidences(const QString &notebook) const;
500 
507  virtual Incidence::List duplicates(const Incidence::Ptr &incidence);
508 
518  Incidence::Ptr incidence(const QString &uid,
519  const QDateTime &recurrenceId = {}) const;
520 
530  Incidence::Ptr deleted(const QString &uid, const QDateTime &recurrenceId = {}) const;
531 
538  virtual bool deleteIncidenceInstances(const Incidence::Ptr &incidence) = 0;
539 
548  virtual Incidence::Ptr incidenceFromSchedulingID(const QString &sid) const;
549 
556  virtual Incidence::List incidencesFromSchedulingID(const QString &sid) const;
557 
567  static Incidence::List mergeIncidenceList(const Event::List &events,
568  const Todo::List &todos,
569  const Journal::List &journals);
570 
575  virtual bool beginChange(const Incidence::Ptr &incidence);
576 
581  virtual bool endChange(const Incidence::Ptr &incidence);
582 
597  static Incidence::Ptr createException(const Incidence::Ptr &incidence,
598  const QDateTime &recurrenceId,
599  bool thisAndFuture = false);
600 
601  // Event Specific Methods //
602 
612  virtual bool addEvent(const Event::Ptr &event) = 0;
613 
623  virtual bool deleteEvent(const Event::Ptr &event) = 0;
624 
631  virtual bool deleteEventInstances(const Event::Ptr &event) = 0;
632 
642  static Event::List sortEvents(const Event::List &eventList,
643  EventSortField sortField,
644  SortDirection sortDirection);
653  virtual Event::List events(EventSortField sortField = EventSortUnsorted,
654  SortDirection sortDirection = SortDirectionAscending) const;
655 
663  Q_REQUIRED_RESULT Event::List events(const QDateTime &dt) const;
664 
678  Q_REQUIRED_RESULT Event::List events(const QDate &start, const QDate &end,
679  const QTimeZone &timeZone = {},
680  bool inclusive = false) const;
681 
695  Q_REQUIRED_RESULT Event::List events(const QDate &date,
696  const QTimeZone &timeZone = {},
697  EventSortField sortField = EventSortUnsorted,
698  SortDirection sortDirection = SortDirectionAscending) const;
699 
708  virtual Event::List rawEvents(
709  EventSortField sortField = EventSortUnsorted,
710  SortDirection sortDirection = SortDirectionAscending) const = 0;
711 
721  virtual Event::List rawEventsForDate(const QDateTime &dt) const = 0;
722 
736  virtual Event::List rawEvents(const QDate &start, const QDate &end,
737  const QTimeZone &timeZone = {},
738  bool inclusive = false) const = 0;
739 
753  virtual Event::List rawEventsForDate(
754  const QDate &date,
755  const QTimeZone &timeZone = {},
756  EventSortField sortField = EventSortUnsorted,
757  SortDirection sortDirection = SortDirectionAscending) const = 0;
758 
768  virtual Event::Ptr event(const QString &uid,
769  const QDateTime &recurrenceId = {}) const = 0;
770 
783  virtual Event::Ptr deletedEvent(const QString &uid,
784  const QDateTime &recurrenceId = {}) const = 0;
785 
797  virtual Event::List deletedEvents(
798  EventSortField sortField = EventSortUnsorted,
799  SortDirection sortDirection = SortDirectionAscending) const = 0;
800 
810  virtual Event::List eventInstances(
811  const Incidence::Ptr &event,
812  EventSortField sortField = EventSortUnsorted,
813  SortDirection sortDirection = SortDirectionAscending) const = 0;
814 
815  // Todo Specific Methods //
816 
826  virtual bool addTodo(const Todo::Ptr &todo) = 0;
827 
837  virtual bool deleteTodo(const Todo::Ptr &todo) = 0;
838 
844  virtual bool deleteTodoInstances(const Todo::Ptr &todo) = 0;
845 
855  static Todo::List sortTodos(const Todo::List &todoList,
856  TodoSortField sortField,
857  SortDirection sortDirection);
858 
867  virtual Todo::List todos(TodoSortField sortField = TodoSortUnsorted,
868  SortDirection sortDirection = SortDirectionAscending) const;
869 
877  virtual Todo::List todos(const QDate &date) const;
878 
892  virtual Todo::List todos(const QDate &start, const QDate &end,
893  const QTimeZone &timeZone = {},
894  bool inclusive = false) const;
895 
904  virtual Todo::List rawTodos(
905  TodoSortField sortField = TodoSortUnsorted,
906  SortDirection sortDirection = SortDirectionAscending) const = 0;
907 
915  virtual Todo::List rawTodosForDate(const QDate &date) const = 0;
916 
930  virtual Todo::List rawTodos(const QDate &start, const QDate &end,
931  const QTimeZone &timeZone = {},
932  bool inclusive = false) const = 0;
933 
943  virtual Todo::Ptr todo(const QString &uid,
944  const QDateTime &recurrenceId = {}) const = 0;
945 
958  virtual Todo::Ptr deletedTodo(const QString &uid,
959  const QDateTime &recurrenceId = {}) const = 0;
960 
972  virtual Todo::List deletedTodos(
973  TodoSortField sortField = TodoSortUnsorted,
974  SortDirection sortDirection = SortDirectionAscending) const = 0;
975 
985  virtual Todo::List todoInstances(
986  const Incidence::Ptr &todo,
987  TodoSortField sortField = TodoSortUnsorted,
988  SortDirection sortDirection = SortDirectionAscending) const = 0;
989 
990  // Journal Specific Methods //
991 
1001  virtual bool addJournal(const Journal::Ptr &journal) = 0;
1002 
1012  virtual bool deleteJournal(const Journal::Ptr &journal) = 0;
1013 
1020  virtual bool deleteJournalInstances(const Journal::Ptr &journal) = 0;
1021 
1031  static Journal::List sortJournals(const Journal::List &journalList,
1032  JournalSortField sortField,
1033  SortDirection sortDirection);
1042  virtual Journal::List journals(
1044  SortDirection sortDirection = SortDirectionAscending) const;
1045 
1053  virtual Journal::List journals(const QDate &date) const;
1054 
1063  virtual Journal::List rawJournals(
1065  SortDirection sortDirection = SortDirectionAscending) const = 0;
1066 
1074  virtual Journal::List rawJournalsForDate(const QDate &date) const = 0;
1075 
1085  virtual Journal::Ptr journal(const QString &uid,
1086  const QDateTime &recurrenceId = {}) const = 0;
1087 
1100  virtual Journal::Ptr deletedJournal(const QString &uid,
1101  const QDateTime &recurrenceId = {}) const = 0;
1102 
1114  virtual Journal::List deletedJournals(
1116  SortDirection sortDirection = SortDirectionAscending) const = 0;
1117 
1127  virtual Journal::List journalInstances(
1128  const Incidence::Ptr &journal,
1130  SortDirection sortDirection = SortDirectionAscending) const = 0;
1131 
1132  // Relations Specific Methods //
1133 
1138  virtual void setupRelations(const Incidence::Ptr &incidence);
1139 
1145  virtual void removeRelations(const Incidence::Ptr &incidence);
1146 
1153  bool isAncestorOf(const Incidence::Ptr &ancestor,
1154  const Incidence::Ptr &incidence) const;
1155 
1162  Incidence::List relations(const QString &uid) const;
1163 
1164  // Filter Specific Methods //
1165 
1175  void setFilter(CalFilter *filter);
1176 
1185  CalFilter *filter() const;
1186 
1187  // Alarm Specific Methods //
1188 
1198  virtual Alarm::List alarms(const QDateTime &from, const QDateTime &to, bool excludeBlockedAlarms = false) const = 0;
1199 
1200  // Observer Specific Methods //
1201 
1207  class KCALENDARCORE_EXPORT CalendarObserver //krazy:exclude=dpointer
1208  {
1209  public:
1213  virtual ~CalendarObserver();
1214 
1222  virtual void calendarModified(bool modified, Calendar *calendar);
1223 
1228  virtual void calendarIncidenceAdded(const Incidence::Ptr &incidence);
1229 
1234  virtual void calendarIncidenceChanged(const Incidence::Ptr &incidence);
1235 
1240  virtual void calendarIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence);
1241 
1249  virtual void calendarIncidenceDeleted(const Incidence::Ptr &incidence, const Calendar *calendar);
1250 
1255  virtual void calendarIncidenceAdditionCanceled(const Incidence::Ptr &incidence);
1256  };
1257 
1266  void registerObserver(CalendarObserver *observer);
1267 
1276  void unregisterObserver(CalendarObserver *observer);
1277 
1278  using QObject::event; // prevent warning about hidden virtual method
1279 
1280 protected:
1286  void incidenceUpdated(const QString &uid, const QDateTime &recurrenceId) override;
1287 
1293  virtual void doSetTimeZone(const QTimeZone &timeZone);
1294 
1299  void notifyIncidenceAdded(const Incidence::Ptr &incidence);
1300 
1305  void notifyIncidenceChanged(const Incidence::Ptr &incidence);
1306 
1311  void notifyIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence);
1312 
1317  void notifyIncidenceDeleted(const Incidence::Ptr &incidence);
1318 
1323  void notifyIncidenceAdditionCanceled(const Incidence::Ptr &incidence);
1324 
1329  void customPropertyUpdated() override;
1330 
1337  void setObserversEnabled(bool enabled);
1338 
1348  void appendAlarms(Alarm::List &alarms, const Incidence::Ptr &incidence,
1349  const QDateTime &from, const QDateTime &to) const;
1350 
1360  void appendRecurringAlarms(Alarm::List &alarms, const Incidence::Ptr &incidence,
1361  const QDateTime &from, const QDateTime &to) const;
1362 
1371  void setDeletionTracking(bool enable);
1372 
1378  bool deletionTracking() const;
1379 
1384  virtual void virtual_hook(int id, void *data);
1385 
1386 Q_SIGNALS:
1391  void filterChanged();
1392 
1393 private:
1394  friend class ICalFormat;
1395 
1396  //@cond PRIVATE
1397  class Private;
1398  Private *const d;
1399  //@endcond
1400 
1401  Q_DISABLE_COPY(Calendar)
1402 };
1403 
1404 }
1405 
1406 Q_DECLARE_METATYPE(KCalendarCore::Calendar::Ptr)
1407 
1408 #endif
Do not sort Journals.
Definition: calendar.h:92
JournalSortField
Calendar Journal sort keys.
Definition: calendar.h:91
Sort Todos alphabetically, by summary.
Definition: calendar.h:84
Sort in descending order (last to first)
Definition: calendar.h:62
TodoSortField
Calendar Todo sort keys.
Definition: calendar.h:78
Represents the main calendar class.
Definition: calendar.h:119
The CalendarObserver class.
Definition: calendar.h:1207
A class to manage custom calendar properties.
This file is part of the API for handling calendar data and defines the CustomProperties class...
Sort Todos by priority.
Definition: calendar.h:82
Represents a person, by name and email address.
Definition: person.h:38
Sort Todos chronologically, by creation date.
Definition: calendar.h:85
Sort Events alphabetically, by summary.
Definition: calendar.h:72
Do not sort Events.
Definition: calendar.h:69
virtual bool event(QEvent *e)
Sort Todos chronologically, by start date.
Definition: calendar.h:80
EventSortField
Calendar Event sort keys.
Definition: calendar.h:68
This file is part of the API for handling calendar data and defines the Todo class.
Sort Events chronologically, by end date.
Definition: calendar.h:71
Sort in ascending order (first to last)
Definition: calendar.h:61
This file is part of the API for handling calendar data and defines the Journal class.
Sort Todos chronologically, by due date.
Definition: calendar.h:81
iCalendar format implementation.
Definition: icalformat.h:44
This file is part of the API for handling calendar data and defines the Event class.
Do not sort Todos.
Definition: calendar.h:79
This file is part of the API for handling calendar data and defines the Incidence class...
SortDirection
Calendar Incidence sort directions.
Definition: calendar.h:60
Sort Events chronologically, by start date.
Definition: calendar.h:70
Sort Todos by percentage completed.
Definition: calendar.h:83
Provides a filter for calendars.
Definition: calfilter.h:43
QSharedPointer< Calendar > Ptr
A shared pointer to a Calendar.
Definition: calendar.h:131
Sort Journals alphabetically, by summary.
Definition: calendar.h:94
Namespace for all KCalendarCore types.
Definition: alarm.h:36
Sort Journals chronologically by date.
Definition: calendar.h:93
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Sep 24 2020 22:51:32 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.