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

KDE's Doxygen guidelines are available online.