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