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 */
11 /**
12  @file
13  This file is part of the API for handling calendar data and
14  defines the Calendar class.
15 
16  @author Preston Brown <[email protected]>
17  @author Cornelius Schumacher <[email protected]>
18  @author Reinhold Kainhofer <[email protected]>
19  @author David Jarvie <[email protected]>
20  */
21 
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 "customproperties.h"
39 #include "event.h"
40 #include "incidence.h"
41 #include "journal.h"
42 #include "kcalendarcore_export.h"
43 #include "todo.h"
44 
45 #include <QDateTime>
46 #include <QIcon>
47 #include <QObject>
48 #include <QTimeZone>
49 
50 /** Namespace for all KCalendarCore types. */
51 namespace KCalendarCore
52 {
53 Q_NAMESPACE_EXPORT(KCALENDARCORE_EXPORT)
54 
55 class CalFilter;
56 class Person;
57 class ICalFormat;
58 
59 /**
60  Calendar Incidence sort directions.
61 */
63  SortDirectionAscending, /**< Sort in ascending order (first to last) */
64  SortDirectionDescending, /**< Sort in descending order (last to first) */
65 };
66 
67 /**
68  Calendar Event sort keys.
69 */
71  EventSortUnsorted, /**< Do not sort Events */
72  EventSortStartDate, /**< Sort Events chronologically, by start date */
73  EventSortEndDate, /**< Sort Events chronologically, by end date */
74  EventSortSummary, /**< Sort Events alphabetically, by summary */
75 };
76 
77 /**
78  Calendar Todo sort keys.
79 */
81  TodoSortUnsorted, /**< Do not sort Todos */
82  TodoSortStartDate, /**< Sort Todos chronologically, by start date */
83  TodoSortDueDate, /**< Sort Todos chronologically, by due date */
84  TodoSortPriority, /**< Sort Todos by priority */
85  TodoSortPercentComplete, /**< Sort Todos by percentage completed */
86  TodoSortSummary, /**< Sort Todos alphabetically, by summary */
87  TodoSortCreated, /**< Sort Todos chronologically, by creation date */
88  TodoSortCategories, /**< Sort Todos by categories (tags) @since 5.83 */
89 };
90 
91 /**
92  Calendar Journal sort keys.
93 */
95  JournalSortUnsorted, /**< Do not sort Journals */
96  JournalSortDate, /**< Sort Journals chronologically by date */
97  JournalSortSummary, /**< Sort Journals alphabetically, by summary */
98 };
99 
100 /**
101  The calendar's access mode, i.e. whether it can be written to or is read only.
102  @since 5.85
103 */
105  ReadOnly,
106  ReadWrite,
107 };
108 Q_ENUM_NS(AccessMode)
109 
110 /**
111  @brief
112  Represents the main calendar class.
113 
114  A calendar contains information like incidences (events, to-dos, journals),
115  alarms, time zones, and other useful information.
116 
117  This is an abstract base class defining the interface to a calendar.
118  It is implemented by subclasses like MemoryCalendar, which use different
119  methods to store and access the data.
120 
121  <b>Ownership of Incidences</b>:
122 
123  Incidence ownership is handled by the following policy: as soon as an
124  incidence (or any other subclass of IncidenceBase) is added to the
125  Calendar by an add...() method it is owned by the Calendar object.
126  The Calendar takes care of deleting the incidence using the delete...()
127  methods. All Incidences returned by the query functions are returned
128  as pointers so that changes to the returned Incidences are immediately
129  visible in the Calendar. Do <em>Not</em> attempt to 'delete' any Incidence
130  object you get from Calendar -- use the delete...() methods.
131 */
132 class KCALENDARCORE_EXPORT Calendar : public QObject, public CustomProperties, public IncidenceBase::IncidenceObserver
133 {
134  Q_OBJECT
135  Q_PROPERTY(QString productId READ productId WRITE setProductId) // clazy:exclude=qproperty-without-notify
136  Q_PROPERTY(KCalendarCore::Person owner READ owner WRITE setOwner NOTIFY ownerChanged)
137  Q_PROPERTY(QString id READ id WRITE setId NOTIFY idChanged)
138  Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged)
139  Q_PROPERTY(QIcon icon READ icon WRITE setIcon NOTIFY iconChanged)
140  Q_PROPERTY(KCalendarCore::AccessMode accessMode READ accessMode WRITE setAccessMode NOTIFY accessModeChanged)
141  Q_PROPERTY(bool isLoading READ isLoading NOTIFY isLoadingChanged)
142 
143 public:
144  /**
145  A shared pointer to a Calendar
146  */
148 
149  /**
150  Constructs a calendar with a specified time zone @p timeZone.
151  The time zone is used as the default for creating or
152  modifying incidences in the Calendar. The time zone does
153  not alter existing incidences.
154 
155  @param timeZone time specification
156  */
157  explicit Calendar(const QTimeZone &timeZone);
158 
159  /**
160  Construct Calendar object using a time zone ID.
161  The time zone ID is used as the default for creating or modifying
162  incidences in the Calendar. The time zone does not alter existing
163  incidences.
164 
165  @param timeZoneId is a string containing a time zone ID, which is
166  assumed to be valid. If no time zone is found, the viewing time
167  specification is set to local time zone.
168  @e Example: "Europe/Berlin"
169  */
170  explicit Calendar(const QByteArray &timeZoneId);
171 
172  /**
173  Destroys the calendar.
174  */
175  ~Calendar() override;
176 
177  /**
178  Sets the calendar Product ID to @p id.
179 
180  @param id is a string containing the Product ID.
181 
182  @see productId() const
183  */
184  void setProductId(const QString &id);
185 
186  /**
187  Returns the calendar's Product ID.
188 
189  @see setProductId()
190  */
191  Q_REQUIRED_RESULT QString productId() const;
192 
193  /**
194  Sets the owner of the calendar to @p owner.
195 
196  @param owner is a Person object. Must be a non-null pointer.
197 
198  @see owner()
199  */
200  void setOwner(const Person &owner);
201 
202  /**
203  Returns the owner of the calendar.
204 
205  @return the owner Person object.
206 
207  @see setOwner()
208  */
209  Q_REQUIRED_RESULT Person owner() const;
210 
211  /**
212  Sets the default time specification zone used for creating
213  or modifying incidences in the Calendar.
214 
215  @param timeZone The time zone
216  */
217  void setTimeZone(const QTimeZone &timeZone);
218 
219  /**
220  Get the time zone used for creating or
221  modifying incidences in the Calendar.
222 
223  @return time specification
224  */
225  Q_REQUIRED_RESULT QTimeZone timeZone() const;
226 
227  /**
228  Sets the time zone ID used for creating or modifying incidences in the
229  Calendar. This method has no effect on existing incidences.
230 
231  @param timeZoneId is a string containing a time zone ID, which is
232  assumed to be valid. The time zone ID is used to set the time zone
233  for viewing Incidence date/times. If no time zone is found, the
234  viewing time specification is set to local time zone.
235  @e Example: "Europe/Berlin"
236  @see setTimeZone()
237  */
238  void setTimeZoneId(const QByteArray &timeZoneId);
239 
240  /**
241  Returns the time zone ID used for creating or modifying incidences in
242  the calendar.
243 
244  @return the string containing the time zone ID, or empty string if the
245  creation/modification time specification is not a time zone.
246  */
247  Q_REQUIRED_RESULT QByteArray timeZoneId() const;
248 
249  /**
250  Shifts the times of all incidences so that they appear at the same clock
251  time as before but in a new time zone. The shift is done from a viewing
252  time zone rather than from the actual incidence time zone.
253 
254  For example, shifting an incidence whose start time is 09:00 America/New York,
255  using an old viewing time zone (@p oldSpec) of Europe/London, to a new time
256  zone (@p newSpec) of Europe/Paris, will result in the time being shifted
257  from 14:00 (which is the London time of the incidence start) to 14:00 Paris
258  time.
259 
260  @param oldZone the time zone which provides the clock times
261  @param newZone the new time zone
262  */
263  void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone);
264 
265  /**
266  Sets if the calendar has been modified.
267 
268  @param modified is true if the calendar has been modified since open
269  or last save.
270 
271  @see isModified()
272  */
273  void setModified(bool modified);
274 
275  /**
276  Determine the calendar's modification status.
277 
278  @return true if the calendar has been modified since open or last save.
279 
280  @see setModified()
281  */
282  Q_REQUIRED_RESULT bool isModified() const;
283 
284  /**
285  * A unique identifier for this calendar.
286  * @since 5.85
287  * @see setId()
288  */
289  QString id() const;
290 
291  /**
292  * set a unique identifier for this calendar.
293  * @since 5.85
294  * @see id()
295  */
296  void setId(const QString &id);
297 
298  /**
299  * The user-visible name for this calendar.
300  * @since 5.85
301  * @see setName()
302  */
303  QString name() const;
304 
305  /**
306  * Set the user-visible name for this calendar.
307  * @since 5.85
308  * @see name()
309  */
310  void setName(const QString &name);
311 
312  /**
313  * This calendar's icon.
314  * @since 5.85
315  * @see setIconName()
316  */
317  QIcon icon() const;
318 
319  /**
320  * Set this calendar's icon.
321  * @since 5.85
322  * @see icon()
323  */
324  void setIcon(const QIcon &icon);
325 
326  /**
327  * This calendar's AccessMode, i.e. whether it is writable or read-only.
328  * Defaults to ReadWrite.
329  * @since 5.85
330  * @see setAccessMode()
331  */
332  AccessMode accessMode() const;
333 
334  /**
335  * Set this calendar's AccessMode, i.e. whether it is writable or read-only.
336  * @since 5.85
337  * @see accessMode()
338  */
339  void setAccessMode(const AccessMode mode);
340 
341  /**
342  * Returns @c true if the calendar is still loading its data and thus
343  * read access will not return complete (or even any) results.
344  * @since 5.96
345  */
346  bool isLoading() const;
347 
348  /**
349  Clears out the current calendar, freeing all used memory etc.
350  */
351  virtual void close() = 0;
352 
353  /**
354  Syncs changes in memory to persistent storage.
355 
356  @return true if the save was successful; false otherwise.
357  Base implementation returns true.
358  */
359  virtual bool save();
360 
361  /**
362  Loads the calendar contents from storage. This requires that the
363  calendar has been previously loaded (initialized).
364 
365  @return true if the reload was successful; otherwise false.
366  Base implementation returns true.
367  */
368  virtual bool reload();
369 
370  /**
371  Determine if the calendar is currently being saved.
372 
373  @return true if the calendar is currently being saved; false otherwise.
374  */
375  virtual bool isSaving() const;
376 
377  /**
378  Returns a list of all categories used by Incidences in this Calendar.
379 
380  @return a QStringList containing all the categories.
381  */
382  Q_REQUIRED_RESULT QStringList categories() const;
383 
384  // Incidence Specific Methods //
385 
386  /**
387  Call this to tell the calendar that you're adding a batch of incidences.
388  So it doesn't, for example, ask the destination for each incidence.
389 
390  @see endBatchAdding()
391  */
392  virtual void startBatchAdding();
393 
394  /**
395  Tells the Calendar that you stopped adding a batch of incidences.
396 
397  @see startBatchAdding()
398  */
399  virtual void endBatchAdding();
400 
401  /**
402  @return true if batch adding is in progress
403  */
404  Q_REQUIRED_RESULT bool batchAdding() const;
405 
406  /**
407  Inserts an Incidence into the calendar.
408 
409  @param incidence is a pointer to the Incidence to insert.
410 
411  @return true if the Incidence was successfully inserted; false otherwise.
412 
413  @see deleteIncidence()
414  */
415  virtual bool addIncidence(const Incidence::Ptr &incidence);
416 
417  /**
418  Removes an Incidence from the calendar.
419 
420  @param incidence is a pointer to the Incidence to remove.
421 
422  @return true if the Incidence was successfully removed; false otherwise.
423 
424  @see addIncidence()
425  */
426  virtual bool deleteIncidence(const Incidence::Ptr &incidence);
427 
428  /**
429  Returns a filtered list of all Incidences for this Calendar.
430 
431  @return the list of all filtered Incidences.
432  */
433  virtual Incidence::List incidences() const;
434 
435  /**
436  Returns a filtered list of all Incidences which occur on the given date.
437 
438  @param date request filtered Incidence list for this QDate only.
439 
440  @return the list of filtered Incidences occurring on the specified date.
441  */
442  virtual Incidence::List incidences(const QDate &date) const;
443 
444  /**
445  Returns an unfiltered list of all Incidences for this Calendar.
446 
447  @return the list of all unfiltered Incidences.
448  */
449  virtual Incidence::List rawIncidences() const;
450 
451  /**
452  Returns an unfiltered list of all exceptions of this recurring incidence.
453 
454  @param incidence incidence to check
455 
456  @return the list of all unfiltered exceptions.
457  */
458  virtual Incidence::List instances(const Incidence::Ptr &incidence) const;
459 
460  // Notebook Specific Methods //
461 
462  /**
463  Clears notebook associations from hash-tables for incidences.
464  Called when in-memory content of the calendar is cleared.
465  */
466  virtual void clearNotebookAssociations();
467 
468  /**
469  Associate notebook for an incidence.
470 
471  @param incidence incidence
472  @param notebook notebook uid
473 
474  @return true if the operation was successful; false otherwise.
475  */
476  virtual bool setNotebook(const Incidence::Ptr &incidence, const QString &notebook);
477 
478  /**
479  Get incidence's notebook.
480 
481  @param incidence incidence
482 
483  @return notebook uid
484  */
485  virtual QString notebook(const Incidence::Ptr &incidence) const;
486 
487  /**
488  Get incidence's notebook.
489 
490  @param uid is a unique identifier string
491 
492  @return notebook uid
493  */
494  virtual QString notebook(const QString &uid) const;
495 
496  /**
497  List all uids of notebooks currently in the memory.
498 
499  @return list of uids of notebooks
500  */
501  virtual QStringList notebooks() const;
502 
503  /**
504  Check if calendar knows about the given notebook.
505  This means that it will be saved by one of the attached storages.
506 
507  @param notebook notebook uid
508  @return true if calendar has valid notebook
509  */
510  Q_REQUIRED_RESULT bool hasValidNotebook(const QString &notebook) const;
511 
512  /**
513  Add notebook information into calendar.
514  Is usually called by storages only.
515 
516  @param notebook notebook uid
517  @param isVisible notebook visibility
518  @return true if operation succeeded
519  @see isVisible()
520  */
521  Q_REQUIRED_RESULT bool addNotebook(const QString &notebook, bool isVisible);
522 
523  /**
524  Update notebook information in calendar.
525  Is usually called by storages only.
526 
527  @param notebook notebook uid
528  @param isVisible notebook visibility
529  @return true if operation succeeded
530  @see isVisible()
531  */
532  Q_REQUIRED_RESULT bool updateNotebook(const QString &notebook, bool isVisible);
533 
534  /**
535  Delete notebook information from calendar.
536  Is usually called by storages only.
537 
538  @param notebook notebook uid
539  @return true if operation succeeded
540  @see isVisible()
541  */
542  Q_REQUIRED_RESULT bool deleteNotebook(const QString &notebook);
543 
544  /**
545  set DefaultNotebook information to calendar.
546 
547  @param notebook notebook uid
548  @return true if operation was successful; false otherwise.
549  */
550  Q_REQUIRED_RESULT bool setDefaultNotebook(const QString &notebook);
551 
552  /**
553  Get uid of default notebook.
554 
555  @return notebook uid
556  */
557  Q_REQUIRED_RESULT QString defaultNotebook() const;
558 
559  /**
560  Check if incidence is visible.
561  @param incidence is a pointer to the Incidence to check for visibility.
562  @return true if incidence is visible, false otherwise
563  */
564  Q_REQUIRED_RESULT bool isVisible(const Incidence::Ptr &incidence) const;
565 
566  /**
567  Check if notebook is visible.
568  @param notebook notebook uid.
569  @return true if notebook is visible, false otherwise
570  */
571  Q_REQUIRED_RESULT bool isVisible(const QString &notebook) const;
572 
573  /**
574  List all notebook incidences in the memory.
575 
576  @param notebook is the notebook uid.
577  @return a list of incidences for the notebook.
578  */
579  virtual Incidence::List incidences(const QString &notebook) const;
580 
581  /**
582  List all possible duplicate incidences.
583 
584  @param incidence is the incidence to check.
585  @return a list of duplicate incidences.
586  */
587  virtual Incidence::List duplicates(const Incidence::Ptr &incidence);
588 
589  /**
590  Returns the Incidence associated with the given unique identifier.
591 
592  @param uid is a unique identifier string.
593  @param recurrenceId is possible recurrenceid of incidence, default is null
594 
595  @return a pointer to the Incidence.
596  A null pointer is returned if no such Incidence exists.
597  */
598  Incidence::Ptr incidence(const QString &uid, const QDateTime &recurrenceId = {}) const;
599 
600  /**
601  Returns the deleted Incidence associated with the given unique identifier.
602 
603  @param uid is a unique identifier string.
604  @param recurrenceId is possible recurrenceid of incidence, default is null
605 
606  @return a pointer to the Incidence.
607  A null pointer is returned if no such Incidence exists.
608  */
609  Incidence::Ptr deleted(const QString &uid, const QDateTime &recurrenceId = {}) const;
610 
611  /**
612  Delete all incidences that are instances of recurring incidence @p incidence.
613 
614  @param incidence is a pointer to a deleted Incidence
615  @return true if delete was successful; false otherwise
616  */
617  virtual bool deleteIncidenceInstances(const Incidence::Ptr &incidence) = 0;
618 
619  /**
620  Returns the Incidence associated with the given scheduling identifier.
621 
622  @param sid is a unique scheduling identifier string.
623 
624  @return a pointer to the Incidence.
625  A null pointer is returned if no such Incidence exists.
626  */
627  virtual Incidence::Ptr incidenceFromSchedulingID(const QString &sid) const;
628 
629  /**
630  Searches all events and todos for an incidence with this
631  scheduling identifier. Returns a list of matching results.
632 
633  @param sid is a unique scheduling identifier string.
634  */
635  virtual Incidence::List incidencesFromSchedulingID(const QString &sid) const;
636 
637  /**
638  Create a merged list of Events, Todos, and Journals.
639 
640  @param events is an Event list to merge.
641  @param todos is a Todo list to merge.
642  @param journals is a Journal list to merge.
643 
644  @return a list of merged Incidences.
645  */
646  static Incidence::List mergeIncidenceList(const Event::List &events, const Todo::List &todos, const Journal::List &journals);
647 
648  /**
649  Flag that a change to a Calendar Incidence is starting.
650  @param incidence is a pointer to the Incidence that will be changing.
651  */
652  virtual bool beginChange(const Incidence::Ptr &incidence);
653 
654  /**
655  Flag that a change to a Calendar Incidence has completed.
656  @param incidence is a pointer to the Incidence that was changed.
657  */
658  virtual bool endChange(const Incidence::Ptr &incidence);
659 
660  /**
661  Creates an exception for an occurrence from a recurring Incidence.
662 
663  The returned exception is not automatically inserted into the calendar.
664 
665  @param incidence is a pointer to a recurring Incidence.
666  @param recurrenceId specifies the specific occurrence for which the
667  exception applies.
668  @param thisAndFuture specifies if the exception applies only this specific
669  occcurrence or also to all future occurrences.
670 
671  @return a pointer to a new exception incidence with @param recurrenceId set.
672  @since 4.11
673  */
674  static Incidence::Ptr createException(const Incidence::Ptr &incidence, const QDateTime &recurrenceId, bool thisAndFuture = false);
675 
676  // Event Specific Methods //
677 
678  /**
679  Inserts an Event into the calendar.
680 
681  @param event is a pointer to the Event to insert.
682 
683  @return true if the Event was successfully inserted; false otherwise.
684 
685  @see deleteEvent()
686  */
687  virtual bool addEvent(const Event::Ptr &event) = 0;
688 
689  /**
690  Removes an Event from the calendar.
691 
692  @param event is a pointer to the Event to remove.
693 
694  @return true if the Event was successfully remove; false otherwise.
695 
696  @see addEvent()
697  */
698  virtual bool deleteEvent(const Event::Ptr &event) = 0;
699 
700  /**
701  Delete all events that are instances of recurring event @p event.
702 
703  @param event is a pointer to a deleted Event
704  @return true if delete was successful; false otherwise
705  */
706  virtual bool deleteEventInstances(const Event::Ptr &event) = 0;
707 
708 #if KCALENDARCORE_ENABLE_DEPRECATED_SINCE(5, 95)
709  /**
710  Sort a list of Events.
711 
712  @param eventList is a pointer to a list of Events.
713  @param sortField specifies the EventSortField.
714  @param sortDirection specifies the SortDirection.
715 
716  @return a list of Events sorted as specified.
717 
718  @deprecated since 5.95 Use the sortEvents(Event::List &&eventList, EventSortField sortField, SortDirection sortDirection)
719  overload instead. In the common case that you are sorting a list in-place, wrapping the @p eventList
720  argument with std::move will be all that's needed. In the less common case you actually want a copy,
721  create that explicitly first.
722  */
723  KCALENDARCORE_DEPRECATED_VERSION(
724  5,
725  95,
726  "Use sortEvents(Event::List &&eventList, EventSortField sortField, SortDirection sortDirection); see API docs for details.")
727  static Event::List sortEvents(const Event::List &eventList, EventSortField sortField, SortDirection sortDirection);
728 #endif
729  /**
730  Sort a list of Events.
731 
732  @param eventList the list of events that should be sorted. The list is sorted in place and returned.
733  @param sortField specifies the EventSortField.
734  @param sortDirection specifies the SortDirection.
735 
736  @return a list of Events sorted as specified.
737  @since 5.95
738  */
739  static Event::List sortEvents(Event::List &&eventList, EventSortField sortField, SortDirection sortDirection);
740 
741  /**
742  Returns a sorted, filtered list of all Events for this Calendar.
743 
744  @param sortField specifies the EventSortField.
745  @param sortDirection specifies the SortDirection.
746 
747  @return the list of all filtered Events sorted as specified.
748  */
749  virtual Event::List events(EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const;
750 
751  /**
752  Returns a filtered list of all Events which occur on the given timestamp.
753 
754  @param dt request filtered Event list for this QDateTime only.
755 
756  @return the list of filtered Events occurring on the specified timestamp.
757  */
758  Q_REQUIRED_RESULT Event::List events(const QDateTime &dt) const;
759 
760  /**
761  Returns a filtered list of all Events occurring within a date range.
762 
763  @param start is the starting date.
764  @param end is the ending date.
765  @param timeZone time zone to interpret @p start and @p end,
766  or the calendar's default time zone if none is specified
767  @param inclusive if true only Events which are completely included
768  within the date range are returned.
769 
770  @return the list of filtered Events occurring within the specified
771  date range.
772  */
773  Q_REQUIRED_RESULT Event::List events(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const;
774 
775  /**
776  Returns a sorted, filtered list of all Events which occur on the given
777  date. The Events are sorted according to @a sortField and
778  @a sortDirection.
779 
780  @param date request filtered Event list for this QDate only.
781  @param timeZone time zone to interpret @p start and @p end,
782  or the calendar's default time zone if none is specified
783  @param sortField specifies the EventSortField.
784  @param sortDirection specifies the SortDirection.
785 
786  @return the list of sorted, filtered Events occurring on @a date.
787  */
788  Q_REQUIRED_RESULT Event::List events(const QDate &date,
789  const QTimeZone &timeZone = {},
790  EventSortField sortField = EventSortUnsorted,
791  SortDirection sortDirection = SortDirectionAscending) const;
792 
793  /**
794  Returns a sorted, unfiltered list of all Events for this Calendar.
795 
796  @param sortField specifies the EventSortField.
797  @param sortDirection specifies the SortDirection.
798 
799  @return the list of all unfiltered Events sorted as specified.
800  */
801  virtual Event::List rawEvents(EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0;
802 
803 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 95)
804  /**
805  Returns an unfiltered list of all Events which occur on the given
806  timestamp.
807 
808  @param dt request unfiltered Event list for this QDateTime only.
809 
810  @return the list of unfiltered Events occurring on the specified
811  timestamp.
812 
813  @deprecated since 5.95 use rawEventsForDate(dt.date(), dt.timeZone()) overload instead.
814  */
815  KCALENDARCORE_DEPRECATED_VERSION(5, 95, "Use rawEventsForDate(dt.date(), dt.timeZone()) insead")
816  virtual Event::List rawEventsForDate(const QDateTime &dt) const = 0;
817 #endif
818 
819  /**
820  Returns an unfiltered list of all Events occurring within a date range.
821 
822  @param start is the starting date
823  @param end is the ending date
824  @param timeZone time zone to interpret @p start and @p end,
825  or the calendar's default time zone if none is specified
826  @param inclusive if true only Events which are completely included
827  within the date range are returned.
828 
829  @return the list of unfiltered Events occurring within the specified
830  date range.
831  */
832  virtual Event::List rawEvents(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const = 0;
833 
834  /**
835  Returns a sorted, unfiltered list of all Events which occur on the given
836  date. The Events are sorted according to @a sortField and
837  @a sortDirection.
838 
839  @param date request unfiltered Event list for this QDate only
840  @param timeZone time zone to interpret @p date,
841  or the calendar's default time zone if none is specified
842  @param sortField specifies the EventSortField
843  @param sortDirection specifies the SortDirection
844 
845  @return the list of sorted, unfiltered Events occurring on @p date
846  */
847  virtual Event::List rawEventsForDate(const QDate &date,
848  const QTimeZone &timeZone = {},
849  EventSortField sortField = EventSortUnsorted,
850  SortDirection sortDirection = SortDirectionAscending) const = 0;
851 
852  /**
853  Returns the Event associated with the given unique identifier.
854 
855  @param uid is a unique identifier string.
856  @param recurrenceId is possible recurrenceId of event, default is null
857 
858  @return a pointer to the Event.
859  A null pointer is returned if no such Event exists.
860  */
861  virtual Event::Ptr event(const QString &uid, const QDateTime &recurrenceId = {}) const = 0;
862 
863  /**
864  Returns the deleted Event associated with the given unique identifier.
865 
866  @param uid is a unique identifier string.
867  @param recurrenceId is possible recurrenceId of event, default is null
868 
869  @return a pointer to the deleted Event.
870  A null pointer is returned if no such deleted Event exists, or if deletion tracking
871  is disabled.
872 
873  @see deletionTracking()
874  */
875  virtual Event::Ptr deletedEvent(const QString &uid, const QDateTime &recurrenceId = {}) const = 0;
876 
877  /**
878  Returns a sorted, unfiltered list of all deleted Events for this Calendar.
879 
880  @param sortField specifies the EventSortField.
881  @param sortDirection specifies the SortDirection.
882 
883  @return the list of all unfiltered deleted Events sorted as specified. An empty list
884  is returned if deletion tracking is disabled.
885 
886  @see deletionTracking()
887  */
888  virtual Event::List deletedEvents(EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0;
889 
890  /**
891  Returns a sorted, unfiltered list of all possible instances for this recurring Event.
892 
893  @param event event to check for. Caller guarantees it's of type Event.
894  @param sortField specifies the EventSortField.
895  @param sortDirection specifies the SortDirection.
896 
897  @return the list of all unfiltered event instances sorted as specified.
898  */
899  virtual Event::List
900  eventInstances(const Incidence::Ptr &event, EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0;
901 
902  // Todo Specific Methods //
903 
904  /**
905  Inserts a Todo into the calendar.
906 
907  @param todo is a pointer to the Todo to insert.
908 
909  @return true if the Todo was successfully inserted; false otherwise.
910 
911  @see deleteTodo()
912  */
913  virtual bool addTodo(const Todo::Ptr &todo) = 0;
914 
915  /**
916  Removes a Todo from the calendar.
917 
918  @param todo is a pointer to the Todo to remove.
919 
920  @return true if the Todo was successfully removed; false otherwise.
921 
922  @see addTodo()
923  */
924  virtual bool deleteTodo(const Todo::Ptr &todo) = 0;
925 
926  /**
927  Delete all to-dos that are instances of recurring to-do @p todo.
928  @param todo is a pointer to a deleted Todo
929  @return true if delete was successful; false otherwise
930  */
931  virtual bool deleteTodoInstances(const Todo::Ptr &todo) = 0;
932 
933 #if KCALENDARCORE_ENABLE_DEPRECATED_SINCE(5, 95)
934  /**
935  Sort a list of Todos.
936 
937  @param todoList is a pointer to a list of Todos.
938  @param sortField specifies the TodoSortField.
939  @param sortDirection specifies the SortDirection.
940 
941  @return a list of Todos sorted as specified.
942 
943  @deprecated since 5.95 Use the sortTodos(Todo::List &&todoList, TodoSortField sortField, SortDirection sortDirection)
944  overload instead. In the common case that you are sorting a list in-place, wrapping the @p todoList
945  argument with std::move will be all that's needed. In the less common case you actually want a copy,
946  create that explicitly first.
947  */
948  KCALENDARCORE_DEPRECATED_VERSION(5,
949  95,
950  "Use sortTodos(Todo::List &&todoList, TodoSortField sortField, SortDirection sortDirection); see API docs for details.")
951  static Todo::List sortTodos(const Todo::List &todoList, TodoSortField sortField, SortDirection sortDirection);
952 #endif
953  /**
954  Sort a list of Todos.
955 
956  @param todoList the list of todos that should be sorted. The list is sorted in place and returned.
957  @param sortField specifies the TodoSortField.
958  @param sortDirection specifies the SortDirection.
959 
960  @return a list of Todos sorted as specified.
961 
962  @since 5.95
963  */
964  static Todo::List sortTodos(Todo::List &&todoList, TodoSortField sortField, SortDirection sortDirection);
965 
966  /**
967  Returns a sorted, filtered list of all Todos for this Calendar.
968 
969  @param sortField specifies the TodoSortField.
970  @param sortDirection specifies the SortDirection.
971 
972  @return the list of all filtered Todos sorted as specified.
973  */
974  virtual Todo::List todos(TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const;
975 
976  /**
977  Returns a filtered list of all Todos which are due on the specified date.
978 
979  @param date request filtered Todos due on this QDate.
980 
981  @return the list of filtered Todos due on the specified date.
982  */
983  virtual Todo::List todos(const QDate &date) const;
984 
985  /**
986  Returns a filtered list of all Todos occurring within a date range.
987 
988  @param start is the starting date
989  @param end is the ending date
990  @param timeZone time zone to interpret @p start and @p end,
991  or the calendar's default time zone if none is specified
992  @param inclusive if true only Todos which are completely included
993  within the date range are returned.
994 
995  @return the list of filtered Todos occurring within the specified
996  date range.
997  */
998  virtual Todo::List todos(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const;
999 
1000  /**
1001  Returns a sorted, unfiltered list of all Todos for this Calendar.
1002 
1003  @param sortField specifies the TodoSortField.
1004  @param sortDirection specifies the SortDirection.
1005 
1006  @return the list of all unfiltered Todos sorted as specified.
1007  */
1008  virtual Todo::List rawTodos(TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0;
1009 
1010  /**
1011  Returns an unfiltered list of all Todos which due on the specified date.
1012 
1013  @param date request unfiltered Todos due on this QDate.
1014 
1015  @return the list of unfiltered Todos due on the specified date.
1016  */
1017  virtual Todo::List rawTodosForDate(const QDate &date) const = 0;
1018 
1019  /**
1020  Returns an unfiltered list of all Todos occurring within a date range.
1021 
1022  @param start is the starting date
1023  @param end is the ending date
1024  @param timeZone time zone to interpret @p start and @p end,
1025  or the calendar's default time zone if none is specified
1026  @param inclusive if true only Todos which are completely included
1027  within the date range are returned.
1028 
1029  @return the list of unfiltered Todos occurring within the specified
1030  date range.
1031  */
1032  virtual Todo::List rawTodos(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const = 0;
1033 
1034  /**
1035  Returns the Todo associated with the given unique identifier.
1036 
1037  @param uid is a unique identifier string.
1038  @param recurrenceId is possible recurrenceId of todo, default is null
1039 
1040  @return a pointer to the Todo.
1041  A null pointer is returned if no such Todo exists.
1042  */
1043  virtual Todo::Ptr todo(const QString &uid, const QDateTime &recurrenceId = {}) const = 0;
1044 
1045  /**
1046  Returns the deleted Todo associated with the given unique identifier.
1047 
1048  @param uid is a unique identifier string.
1049  @param recurrenceId is possible recurrenceId of todo, default is null
1050 
1051  @return a pointer to the deleted Todo.
1052  A null pointer is returned if no such deleted Todo exists or if deletion tracking
1053  is disabled.
1054 
1055  @see deletionTracking()
1056  */
1057  virtual Todo::Ptr deletedTodo(const QString &uid, const QDateTime &recurrenceId = {}) const = 0;
1058 
1059  /**
1060  Returns a sorted, unfiltered list of all deleted Todos for this Calendar.
1061 
1062  @param sortField specifies the TodoSortField.
1063  @param sortDirection specifies the SortDirection.
1064 
1065  @return the list of all unfiltered deleted Todos sorted as specified. An empty list
1066  is returned if deletion tracking is disabled.
1067 
1068  @see deletionTracking()
1069  */
1070  virtual Todo::List deletedTodos(TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0;
1071 
1072  /**
1073  Returns a sorted, unfiltered list of all possible instances for this recurring Todo.
1074 
1075  @param todo todo to check for. Caller guarantees it's of type Todo.
1076  @param sortField specifies the TodoSortField.
1077  @param sortDirection specifies the SortDirection.
1078 
1079  @return the list of all unfiltered todo instances sorted as specified.
1080  */
1081  virtual Todo::List
1082  todoInstances(const Incidence::Ptr &todo, TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0;
1083 
1084  // Journal Specific Methods //
1085 
1086  /**
1087  Inserts a Journal into the calendar.
1088 
1089  @param journal is a pointer to the Journal to insert.
1090 
1091  @return true if the Journal was successfully inserted; false otherwise.
1092 
1093  @see deleteJournal()
1094  */
1095  virtual bool addJournal(const Journal::Ptr &journal) = 0;
1096 
1097  /**
1098  Removes a Journal from the calendar.
1099 
1100  @param journal is a pointer to the Journal to remove.
1101 
1102  @return true if the Journal was successfully removed; false otherwise.
1103 
1104  @see addJournal()
1105  */
1106  virtual bool deleteJournal(const Journal::Ptr &journal) = 0;
1107 
1108  /**
1109  Delete all journals that are instances of recurring journal @p journal.
1110 
1111  @param journal is a pointer to a deleted Journal
1112  @return true if delete was successful; false otherwise
1113  */
1114  virtual bool deleteJournalInstances(const Journal::Ptr &journal) = 0;
1115 
1116 #if KCALENDARCORE_ENABLE_DEPRECATED_SINCE(5, 95)
1117  /**
1118  Sort a list of Journals.
1119 
1120  @param journalList is a pointer to a list of Journals.
1121  @param sortField specifies the JournalSortField.
1122  @param sortDirection specifies the SortDirection.
1123 
1124  @return a list of Journals sorted as specified.
1125 
1126  @deprecated since 5.95 Use the sortJournals(Journal::List &&journalList, JournalSortField sortField, SortDirection sortDirection)
1127  overload instead. In the common case that you are sorting a list in-place, wrapping the @p journalList
1128  argument with std::move will be all that's needed. In the less common case you actually want a copy,
1129  create that explicitly first.
1130  */
1131  KCALENDARCORE_DEPRECATED_VERSION(
1132  5,
1133  95,
1134  "Use sortJournals(Journal::List &&journalList, JournalSortField sortField, SortDirection sortDirection); see API docs for details.")
1135  static Journal::List sortJournals(const Journal::List &journalList, JournalSortField sortField, SortDirection sortDirection);
1136 #endif
1137  /**
1138  Sort a list of Journals.
1139 
1140  @param journalList the list of journals that should be sorted. The list is sorted in place and returned.
1141  @param sortField specifies the JournalSortField.
1142  @param sortDirection specifies the SortDirection.
1143 
1144  @return a list of Journals sorted as specified.
1145  @since 5.95
1146  */
1147  static Journal::List sortJournals(Journal::List &&journalList, JournalSortField sortField, SortDirection sortDirection);
1148 
1149  /**
1150  Returns a sorted, filtered list of all Journals for this Calendar.
1151 
1152  @param sortField specifies the JournalSortField.
1153  @param sortDirection specifies the SortDirection.
1154 
1155  @return the list of all filtered Journals sorted as specified.
1156  */
1157  virtual Journal::List journals(JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const;
1158 
1159  /**
1160  Returns a filtered list of all Journals for on the specified date.
1161 
1162  @param date request filtered Journals for this QDate only.
1163 
1164  @return the list of filtered Journals for the specified date.
1165  */
1166  virtual Journal::List journals(const QDate &date) const;
1167 
1168  /**
1169  Returns a sorted, unfiltered list of all Journals for this Calendar.
1170 
1171  @param sortField specifies the JournalSortField.
1172  @param sortDirection specifies the SortDirection.
1173 
1174  @return the list of all unfiltered Journals sorted as specified.
1175  */
1176  virtual Journal::List rawJournals(JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0;
1177 
1178  /**
1179  Returns an unfiltered list of all Journals for on the specified date.
1180 
1181  @param date request unfiltered Journals for this QDate only.
1182 
1183  @return the list of unfiltered Journals for the specified date.
1184  */
1185  virtual Journal::List rawJournalsForDate(const QDate &date) const = 0;
1186 
1187  /**
1188  Returns the Journal associated with the given unique identifier.
1189 
1190  @param uid is a unique identifier string.
1191  @param recurrenceId is possible recurrenceId of journal, default is null
1192 
1193  @return a pointer to the Journal.
1194  A null pointer is returned if no such Journal exists.
1195  */
1196  virtual Journal::Ptr journal(const QString &uid, const QDateTime &recurrenceId = {}) const = 0;
1197 
1198  /**
1199  Returns the deleted Journal associated with the given unique identifier.
1200 
1201  @param uid is a unique identifier string.
1202  @param recurrenceId is possible recurrenceId of journal, default is null
1203 
1204  @return a pointer to the deleted Journal.
1205  A null pointer is returned if no such deleted Journal exists or if deletion tracking
1206  is disabled.
1207 
1208  @see deletionTracking()
1209  */
1210  virtual Journal::Ptr deletedJournal(const QString &uid, const QDateTime &recurrenceId = {}) const = 0;
1211 
1212  /**
1213  Returns a sorted, unfiltered list of all deleted Journals for this Calendar.
1214 
1215  @param sortField specifies the JournalSortField.
1216  @param sortDirection specifies the SortDirection.
1217 
1218  @return the list of all unfiltered deleted Journals sorted as specified. An empty list
1219  is returned if deletion tracking is disabled.
1220 
1221  @see deletionTracking()
1222  */
1223  virtual Journal::List deletedJournals(JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0;
1224 
1225  /**
1226  Returns a sorted, unfiltered list of all instances for this recurring Journal.
1227 
1228  @param journal journal to check for. Caller guarantees it's of type Journal.
1229  @param sortField specifies the JournalSortField.
1230  @param sortDirection specifies the SortDirection.
1231 
1232  @return the list of all unfiltered journal instances sorted as specified.
1233  */
1234  virtual Journal::List journalInstances(const Incidence::Ptr &journal,
1236  SortDirection sortDirection = SortDirectionAscending) const = 0;
1237 
1238  // Relations Specific Methods //
1239 
1240  /**
1241  Setup Relations for an Incidence.
1242  @param incidence is a pointer to the Incidence to have a Relation setup.
1243  */
1244  virtual void setupRelations(const Incidence::Ptr &incidence);
1245 
1246  /**
1247  Removes all Relations from an Incidence.
1248 
1249  @param incidence is a pointer to the Incidence to have a Relation removed.
1250  */
1251  virtual void removeRelations(const Incidence::Ptr &incidence);
1252 
1253  /**
1254  Checks if @p ancestor is an ancestor of @p incidence
1255 
1256  @param ancestor is the incidence we are testing to be an ancestor.
1257  @param incidence is the incidence we are testing to be descended from @p ancestor.
1258  */
1259  bool isAncestorOf(const Incidence::Ptr &ancestor, const Incidence::Ptr &incidence) const;
1260 
1261  /**
1262  Returns a list of incidences that have a relation of RELTYPE parent
1263  to incidence @p uid.
1264 
1265  @param uid The parent identifier whose children we want to obtain.
1266  */
1267  Incidence::List relations(const QString &uid) const;
1268 
1269  // Filter Specific Methods //
1270 
1271  /**
1272  Sets the calendar filter.
1273 
1274  @param filter a pointer to a CalFilter object which will be
1275  used to filter Calendar Incidences. The Calendar takes
1276  ownership of @p filter.
1277 
1278  @see filter()
1279  */
1280  void setFilter(CalFilter *filter);
1281 
1282  /**
1283  Returns the calendar filter.
1284 
1285  @return a pointer to the calendar CalFilter.
1286  A null pointer is returned if no such CalFilter exists.
1287 
1288  @see setFilter()
1289  */
1290  CalFilter *filter() const;
1291 
1292  // Alarm Specific Methods //
1293 
1294  /**
1295  Returns a list of Alarms within a time range for this Calendar.
1296 
1297  @param from is the starting timestamp.
1298  @param to is the ending timestamp.
1299  @param excludeBlockedAlarms if true, alarms belonging to blocked collections aren't returned.
1300 
1301  @return the list of Alarms for the for the specified time range.
1302  */
1303  virtual Alarm::List alarms(const QDateTime &from, const QDateTime &to, bool excludeBlockedAlarms = false) const = 0;
1304 
1305  /**
1306  Return a list of Alarms that occur before the specified timestamp.
1307 
1308  @param to is the ending timestamp.
1309  @return the list of Alarms occurring before the specified QDateTime.
1310  @since 5.77
1311  */
1312  Q_REQUIRED_RESULT Alarm::List alarmsTo(const QDateTime &to) const;
1313 
1314  // Observer Specific Methods //
1315 
1316  /**
1317  @class CalendarObserver
1318 
1319  The CalendarObserver class.
1320  */
1321  class KCALENDARCORE_EXPORT CalendarObserver // krazy:exclude=dpointer
1322  {
1323  public:
1324  /**
1325  Destructor.
1326  */
1327  virtual ~CalendarObserver();
1328 
1329  /**
1330  Notify the Observer that a Calendar has been modified.
1331 
1332  @param modified set if the calendar has been modified.
1333  @param calendar is a pointer to the Calendar object that
1334  is being observed.
1335  */
1336  virtual void calendarModified(bool modified, Calendar *calendar);
1337 
1338  /**
1339  Notify the Observer that an Incidence has been inserted.
1340  @param incidence is a pointer to the Incidence that was inserted.
1341  */
1342  virtual void calendarIncidenceAdded(const Incidence::Ptr &incidence);
1343 
1344  /**
1345  Notify the Observer that an Incidence has been modified.
1346  @param incidence is a pointer to the Incidence that was modified.
1347  */
1348  virtual void calendarIncidenceChanged(const Incidence::Ptr &incidence);
1349 
1350  /**
1351  Notify the Observer that an Incidence will be removed.
1352  @param incidence is a pointer to the Incidence that will be removed.
1353  */
1354  virtual void calendarIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence);
1355 
1356  /**
1357  Notify the Observer that an Incidence has been removed.
1358  @param incidence is a pointer to the Incidence that was removed.
1359  @param calendar is a pointer to the calendar where the incidence was part of,
1360  because the incidence was deleted, there is now way to determine the calendar
1361  @since 4.83.0
1362  */
1363  virtual void calendarIncidenceDeleted(const Incidence::Ptr &incidence, const Calendar *calendar);
1364 
1365  /**
1366  Notify the Observer that an addition of Incidence has been canceled.
1367  @param incidence is a pointer to the Incidence that was removed.
1368  */
1369  virtual void calendarIncidenceAdditionCanceled(const Incidence::Ptr &incidence);
1370  };
1371 
1372  /**
1373  Registers an Observer for this Calendar.
1374 
1375  @param observer is a pointer to an Observer object that will be
1376  watching this Calendar.
1377 
1378  @see unregisterObserver()
1379  */
1380  void registerObserver(CalendarObserver *observer);
1381 
1382  /**
1383  Unregisters an Observer for this Calendar.
1384 
1385  @param observer is a pointer to an Observer object that has been
1386  watching this Calendar.
1387 
1388  @see registerObserver()
1389  */
1390  void unregisterObserver(CalendarObserver *observer);
1391 
1392  using QObject::event; // prevent warning about hidden virtual method
1393 
1394 protected:
1395  /**
1396  The Observer interface. So far not implemented.
1397  @param uid is the UID for the Incidence that has been updated.
1398  @param recurrenceId is possible recurrenceid of incidence.
1399  */
1400  void incidenceUpdated(const QString &uid, const QDateTime &recurrenceId) override;
1401 
1402  /**
1403  Let Calendar subclasses set the time specification.
1404  @param timeZone is the time specification (time zone, etc.) for
1405  viewing Incidence dates.\n
1406  */
1407  virtual void doSetTimeZone(const QTimeZone &timeZone);
1408 
1409  /**
1410  Let Calendar subclasses notify that they inserted an Incidence.
1411  @param incidence is a pointer to the Incidence object that was inserted.
1412  */
1413  void notifyIncidenceAdded(const Incidence::Ptr &incidence);
1414 
1415  /**
1416  Let Calendar subclasses notify that they modified an Incidence.
1417  @param incidence is a pointer to the Incidence object that was modified.
1418  */
1419  void notifyIncidenceChanged(const Incidence::Ptr &incidence);
1420 
1421  /**
1422  Let Calendar subclasses notify that they will remove an Incidence.
1423  @param incidence is a pointer to the Incidence object that will be removed.
1424  */
1425  void notifyIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence);
1426 
1427  /**
1428  Let Calendar subclasses notify that they removed an Incidence.
1429  @param incidence is a pointer to the Incidence object that has been removed.
1430  */
1431  void notifyIncidenceDeleted(const Incidence::Ptr &incidence);
1432 
1433  /**
1434  Let Calendar subclasses notify that they canceled addition of an Incidence.
1435  @param incidence is a pointer to the Incidence object that addition as canceled.
1436  */
1437  void notifyIncidenceAdditionCanceled(const Incidence::Ptr &incidence);
1438 
1439  /**
1440  @copydoc
1441  CustomProperties::customPropertyUpdated()
1442  */
1443  void customPropertyUpdated() override;
1444 
1445  /**
1446  Let Calendar subclasses notify that they enabled an Observer.
1447 
1448  @param enabled if true tells the calendar that a subclass has
1449  enabled an Observer.
1450  */
1451  void setObserversEnabled(bool enabled);
1452 
1453  /**
1454  Appends alarms of incidence in interval to list of alarms.
1455 
1456  @param alarms is a List of Alarms to be appended onto.
1457  @param incidence is a pointer to an Incidence containing the Alarm
1458  to be appended.
1459  @param from is the lower range of the next Alarm repetition.
1460  @param to is the upper range of the next Alarm repetition.
1461  */
1462  void appendAlarms(Alarm::List &alarms, const Incidence::Ptr &incidence, const QDateTime &from, const QDateTime &to) const;
1463 
1464  /**
1465  Appends alarms of recurring events in interval to list of alarms.
1466 
1467  @param alarms is a List of Alarms to be appended onto.
1468  @param incidence is a pointer to an Incidence containing the Alarm
1469  to be appended.
1470  @param from is the lower range of the next Alarm repetition.
1471  @param to is the upper range of the next Alarm repetition.
1472  */
1473  void appendRecurringAlarms(Alarm::List &alarms, const Incidence::Ptr &incidence, const QDateTime &from, const QDateTime &to) const;
1474 
1475  /**
1476  Enables or disabled deletion tracking.
1477  Default is true.
1478  @see deletedEvent()
1479  @see deletedTodo()
1480  @see deletedJournal()
1481  @since 4.11
1482  */
1483  void setDeletionTracking(bool enable);
1484 
1485  /**
1486  Returns if deletion tracking is enabled.
1487  Default is true.
1488  @since 4.11
1489  */
1490  bool deletionTracking() const;
1491 
1492  /**
1493  * Sets the loading state of this calendar.
1494  * This is false by default and only needs to be called for calendars
1495  * that implement asynchronous loading.
1496  * @since 5.96
1497  * @see isLoading()
1498  */
1499  void setIsLoading(bool isLoading);
1500 
1501  /**
1502  @copydoc
1503  IncidenceBase::virtual_hook()
1504  */
1505  virtual void virtual_hook(int id, void *data);
1506 
1507 Q_SIGNALS:
1508  /**
1509  Emitted when setFilter() is called.
1510  @since 4.11
1511  */
1512  void filterChanged();
1513 
1514  /**
1515  * Emitted when the id changes.
1516  * @since 5.85
1517  * @see id()
1518  */
1519  void idChanged();
1520 
1521  /**
1522  * Emitted when the name changes.
1523  * @since 5.85
1524  * @see name()
1525  */
1526  void nameChanged();
1527 
1528  /**
1529  * Emitted when the icon name changes.
1530  * @since 5.85
1531  * @see icon()
1532  */
1533  void iconChanged();
1534 
1535  /**
1536  * Emitted when the AccessMode changes.
1537  * @since 5.85
1538  * @see accessMode()
1539  */
1540  void accessModeChanged();
1541 
1542  /**
1543  * Emitted when the owner changes.
1544  * @since 5.85
1545  * @see owner()
1546  */
1547  void ownerChanged();
1548 
1549  /**
1550  * Emitted when the loading state changed.
1551  * @since 5.96
1552  * @see isLoading()
1553  */
1554  void isLoadingChanged();
1555 
1556 private:
1557  friend class ICalFormat;
1558 
1559  //@cond PRIVATE
1560  class Private;
1561  Private *const d;
1562  //@endcond
1563 
1564  Q_DISABLE_COPY(Calendar)
1565 };
1566 
1567 }
1568 
1569 Q_DECLARE_METATYPE(KCalendarCore::Calendar::Ptr)
1570 
1571 #endif
@ TodoSortUnsorted
Do not sort Todos.
Definition: calendar.h:81
@ JournalSortDate
Sort Journals chronologically by date.
Definition: calendar.h:96
TodoSortField
Calendar Todo sort keys.
Definition: calendar.h:80
JournalSortField
Calendar Journal sort keys.
Definition: calendar.h:94
Namespace for all KCalendarCore types.
Definition: alarm.h:36
QSharedPointer< Calendar > Ptr
A shared pointer to a Calendar.
Definition: calendar.h:147
@ TodoSortCategories
Sort Todos by categories (tags)
Definition: calendar.h:88
Q_SCRIPTABLE Q_NOREPLY void start()
QVector< Ptr > List
List of alarms.
Definition: alarm.h:72
@ TodoSortPercentComplete
Sort Todos by percentage completed.
Definition: calendar.h:85
QSharedPointer< Journal > Ptr
A shared pointer to a Journal object.
Definition: journal.h:38
AccessMode
The calendar's access mode, i.e.
Definition: calendar.h:104
@ EventSortStartDate
Sort Events chronologically, by start date.
Definition: calendar.h:72
@ TodoSortSummary
Sort Todos alphabetically, by summary.
Definition: calendar.h:86
An abstract class that provides a common base for all calendar incidence classes.
Definition: incidencebase.h:98
Represents the main calendar class.
Definition: calendar.h:132
EventSortField
Calendar Event sort keys.
Definition: calendar.h:70
virtual bool event(QEvent *e)
QSharedPointer< Incidence > Ptr
A shared pointer to an Incidence.
Definition: incidence.h:121
@ EventSortUnsorted
Do not sort Events.
Definition: calendar.h:71
@ TodoSortStartDate
Sort Todos chronologically, by start date.
Definition: calendar.h:82
@ SortDirectionDescending
Sort in descending order (last to first)
Definition: calendar.h:64
QFuture< void > filter(Sequence &sequence, KeepFunctor filterFunction)
QSharedPointer< Todo > Ptr
A shared pointer to a Todo object.
Definition: todo.h:39
AKONADI_CALENDAR_EXPORT KCalendarCore::Event::Ptr event(const Akonadi::Item &item)
@ JournalSortUnsorted
Do not sort Journals.
Definition: calendar.h:95
SortDirection
Calendar Incidence sort directions.
Definition: calendar.h:62
@ TodoSortDueDate
Sort Todos chronologically, by due date.
Definition: calendar.h:83
iCalendar format implementation.
Definition: icalformat.h:44
QVector< Ptr > List
List of incidences.
Definition: incidence.h:126
AKONADI_CALENDAR_EXPORT KCalendarCore::Journal::Ptr journal(const Akonadi::Item &item)
@ EventSortEndDate
Sort Events chronologically, by end date.
Definition: calendar.h:73
@ EventSortSummary
Sort Events alphabetically, by summary.
Definition: calendar.h:74
@ JournalSortSummary
Sort Journals alphabetically, by summary.
Definition: calendar.h:97
@ TodoSortCreated
Sort Todos chronologically, by creation date.
Definition: calendar.h:87
@ SortDirectionAscending
Sort in ascending order (first to last)
Definition: calendar.h:63
Represents a person, by name and email address.
Definition: person.h:37
QVector< Ptr > List
List of events.
Definition: event.h:55
QVector< Ptr > List
List of journals.
Definition: journal.h:43
@ TodoSortPriority
Sort Todos by priority.
Definition: calendar.h:84
A class to manage custom calendar properties.
AKONADI_CALENDAR_EXPORT KCalendarCore::Todo::Ptr todo(const Akonadi::Item &item)
QSharedPointer< Event > Ptr
A shared pointer to an Event object.
Definition: event.h:50
QVector< Ptr > List
List of to-dos.
Definition: todo.h:44
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Wed Jun 29 2022 04:02:26 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.