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

KDE's Doxygen guidelines are available online.