File indexing completed on 2024-05-05 07:53:36
0001 /* 0002 This file is part of the kcalcore library. 0003 0004 SPDX-FileCopyrightText: 1998 Preston Brown <pbrown@kde.org> 0005 SPDX-FileCopyrightText 2001, 2003, 2004 Cornelius Schumacher <schumacher@kde.org> 0006 SPDX-FileCopyrightText: 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com> 0007 SPDX-FileCopyrightText: 2006 David Jarvie <djarvie@kde.org> 0008 0009 SPDX-License-Identifier: LGPL-2.0-or-later 0010 */ 0011 /** 0012 @file 0013 This file is part of the API for handling calendar data and 0014 defines the Calendar class. 0015 0016 @author Preston Brown \<pbrown@kde.org\> 0017 @author Cornelius Schumacher \<schumacher@kde.org\> 0018 @author Reinhold Kainhofer \<reinhold@kainhofer.com\> 0019 @author David Jarvie \<djarvie@kde.org\> 0020 */ 0021 0022 /* 0023 0024 TODO: KDE5: 0025 0026 This API needs serious cleaning up: 0027 - Most (all) methods aren't async ( deleteIncidence(), addIncidence(), load(), save(), ... ) 0028 so it's not very easy to make a derived class that loads from akonadi. 0029 0030 - It has too many methods. Why do we need fooEvent()/fooJournal()/fooTodo() when fooIncidence() 0031 should be enough. 0032 0033 */ 0034 0035 #ifndef KCALCORE_CALENDAR_H 0036 #define KCALCORE_CALENDAR_H 0037 0038 #include "customproperties.h" 0039 #include "event.h" 0040 #include "incidence.h" 0041 #include "journal.h" 0042 #include "kcalendarcore_export.h" 0043 #include "todo.h" 0044 0045 #include <QDateTime> 0046 #include <QIcon> 0047 #include <QObject> 0048 #include <QTimeZone> 0049 0050 /** Namespace for all KCalendarCore types. */ 0051 namespace KCalendarCore 0052 { 0053 Q_NAMESPACE_EXPORT(KCALENDARCORE_EXPORT) 0054 0055 class CalFilter; 0056 class Person; 0057 class ICalFormat; 0058 0059 /** 0060 Calendar Incidence sort directions. 0061 */ 0062 enum SortDirection { 0063 SortDirectionAscending, /**< Sort in ascending order (first to last) */ 0064 SortDirectionDescending, /**< Sort in descending order (last to first) */ 0065 }; 0066 0067 /** 0068 Calendar Event sort keys. 0069 */ 0070 enum EventSortField { 0071 EventSortUnsorted, /**< Do not sort Events */ 0072 EventSortStartDate, /**< Sort Events chronologically, by start date */ 0073 EventSortEndDate, /**< Sort Events chronologically, by end date */ 0074 EventSortSummary, /**< Sort Events alphabetically, by summary */ 0075 }; 0076 0077 /** 0078 Calendar Todo sort keys. 0079 */ 0080 enum TodoSortField { 0081 TodoSortUnsorted, /**< Do not sort Todos */ 0082 TodoSortStartDate, /**< Sort Todos chronologically, by start date */ 0083 TodoSortDueDate, /**< Sort Todos chronologically, by due date */ 0084 TodoSortPriority, /**< Sort Todos by priority */ 0085 TodoSortPercentComplete, /**< Sort Todos by percentage completed */ 0086 TodoSortSummary, /**< Sort Todos alphabetically, by summary */ 0087 TodoSortCreated, /**< Sort Todos chronologically, by creation date */ 0088 TodoSortCategories, /**< Sort Todos by categories (tags) @since 5.83 */ 0089 }; 0090 0091 /** 0092 Calendar Journal sort keys. 0093 */ 0094 enum JournalSortField { 0095 JournalSortUnsorted, /**< Do not sort Journals */ 0096 JournalSortDate, /**< Sort Journals chronologically by date */ 0097 JournalSortSummary, /**< Sort Journals alphabetically, by summary */ 0098 }; 0099 0100 /** 0101 The calendar's access mode, i.e. whether it can be written to or is read only. 0102 @since 5.85 0103 */ 0104 enum AccessMode { 0105 ReadOnly, 0106 ReadWrite, 0107 }; 0108 Q_ENUM_NS(AccessMode) 0109 0110 /** 0111 @brief 0112 Represents the main calendar class. 0113 0114 A calendar contains information like incidences (events, to-dos, journals), 0115 alarms, time zones, and other useful information. 0116 0117 This is an abstract base class defining the interface to a calendar. 0118 It is implemented by subclasses like MemoryCalendar, which use different 0119 methods to store and access the data. 0120 0121 <b>Ownership of Incidences</b>: 0122 0123 Incidence ownership is handled by the following policy: as soon as an 0124 incidence (or any other subclass of IncidenceBase) is added to the 0125 Calendar by an add...() method it is owned by the Calendar object. 0126 The Calendar takes care of deleting the incidence using the delete...() 0127 methods. All Incidences returned by the query functions are returned 0128 as pointers so that changes to the returned Incidences are immediately 0129 visible in the Calendar. Do <em>Not</em> attempt to 'delete' any Incidence 0130 object you get from Calendar -- use the delete...() methods. 0131 */ 0132 class KCALENDARCORE_EXPORT Calendar : public QObject, public CustomProperties, public IncidenceBase::IncidenceObserver 0133 { 0134 Q_OBJECT 0135 Q_PROPERTY(QString productId READ productId WRITE setProductId) // clazy:exclude=qproperty-without-notify 0136 Q_PROPERTY(KCalendarCore::Person owner READ owner WRITE setOwner NOTIFY ownerChanged) 0137 Q_PROPERTY(QString id READ id WRITE setId NOTIFY idChanged) 0138 Q_PROPERTY(QString name READ name WRITE setName NOTIFY nameChanged) 0139 Q_PROPERTY(QIcon icon READ icon WRITE setIcon NOTIFY iconChanged) 0140 Q_PROPERTY(KCalendarCore::AccessMode accessMode READ accessMode WRITE setAccessMode NOTIFY accessModeChanged) 0141 Q_PROPERTY(bool isLoading READ isLoading NOTIFY isLoadingChanged) 0142 0143 public: 0144 /** 0145 A shared pointer to a Calendar 0146 */ 0147 typedef QSharedPointer<Calendar> Ptr; 0148 0149 /** 0150 Constructs a calendar with a specified time zone @p timeZone. 0151 The time zone is used as the default for creating or 0152 modifying incidences in the Calendar. The time zone does 0153 not alter existing incidences. 0154 0155 @param timeZone time specification 0156 */ 0157 explicit Calendar(const QTimeZone &timeZone); 0158 0159 /** 0160 Construct Calendar object using a time zone ID. 0161 The time zone ID is used as the default for creating or modifying 0162 incidences in the Calendar. The time zone does not alter existing 0163 incidences. 0164 0165 @param timeZoneId is a string containing a time zone ID, which is 0166 assumed to be valid. If no time zone is found, the viewing time 0167 specification is set to local time zone. 0168 @e Example: "Europe/Berlin" 0169 */ 0170 explicit Calendar(const QByteArray &timeZoneId); 0171 0172 /** 0173 Destroys the calendar. 0174 */ 0175 ~Calendar() override; 0176 0177 /** 0178 Sets the calendar Product ID to @p id. 0179 0180 @param id is a string containing the Product ID. 0181 0182 @see productId() const 0183 */ 0184 void setProductId(const QString &id); 0185 0186 /** 0187 Returns the calendar's Product ID. 0188 0189 @see setProductId() 0190 */ 0191 Q_REQUIRED_RESULT QString productId() const; 0192 0193 /** 0194 Sets the owner of the calendar to @p owner. 0195 0196 @param owner is a Person object. Must be a non-null pointer. 0197 0198 @see owner() 0199 */ 0200 void setOwner(const Person &owner); 0201 0202 /** 0203 Returns the owner of the calendar. 0204 0205 @return the owner Person object. 0206 0207 @see setOwner() 0208 */ 0209 Q_REQUIRED_RESULT Person owner() const; 0210 0211 /** 0212 Sets the default time specification zone used for creating 0213 or modifying incidences in the Calendar. 0214 0215 @param timeZone The time zone 0216 */ 0217 void setTimeZone(const QTimeZone &timeZone); 0218 0219 /** 0220 Get the time zone used for creating or 0221 modifying incidences in the Calendar. 0222 0223 @return time specification 0224 */ 0225 Q_REQUIRED_RESULT QTimeZone timeZone() const; 0226 0227 /** 0228 Sets the time zone ID used for creating or modifying incidences in the 0229 Calendar. This method has no effect on existing incidences. 0230 0231 @param timeZoneId is a string containing a time zone ID, which is 0232 assumed to be valid. The time zone ID is used to set the time zone 0233 for viewing Incidence date/times. If no time zone is found, the 0234 viewing time specification is set to local time zone. 0235 @e Example: "Europe/Berlin" 0236 @see setTimeZone() 0237 */ 0238 void setTimeZoneId(const QByteArray &timeZoneId); 0239 0240 /** 0241 Returns the time zone ID used for creating or modifying incidences in 0242 the calendar. 0243 0244 @return the string containing the time zone ID, or empty string if the 0245 creation/modification time specification is not a time zone. 0246 */ 0247 Q_REQUIRED_RESULT QByteArray timeZoneId() const; 0248 0249 /** 0250 Shifts the times of all incidences so that they appear at the same clock 0251 time as before but in a new time zone. The shift is done from a viewing 0252 time zone rather than from the actual incidence time zone. 0253 0254 For example, shifting an incidence whose start time is 09:00 America/New York, 0255 using an old viewing time zone (@p oldSpec) of Europe/London, to a new time 0256 zone (@p newSpec) of Europe/Paris, will result in the time being shifted 0257 from 14:00 (which is the London time of the incidence start) to 14:00 Paris 0258 time. 0259 0260 @param oldZone the time zone which provides the clock times 0261 @param newZone the new time zone 0262 */ 0263 void shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone); 0264 0265 /** 0266 Sets if the calendar has been modified. 0267 0268 @param modified is true if the calendar has been modified since open 0269 or last save. 0270 0271 @see isModified() 0272 */ 0273 void setModified(bool modified); 0274 0275 /** 0276 Determine the calendar's modification status. 0277 0278 @return true if the calendar has been modified since open or last save. 0279 0280 @see setModified() 0281 */ 0282 Q_REQUIRED_RESULT bool isModified() const; 0283 0284 /** 0285 * A unique identifier for this calendar. 0286 * @since 5.85 0287 * @see setId() 0288 */ 0289 QString id() const; 0290 0291 /** 0292 * set a unique identifier for this calendar. 0293 * @since 5.85 0294 * @see id() 0295 */ 0296 void setId(const QString &id); 0297 0298 /** 0299 * The user-visible name for this calendar. 0300 * @since 5.85 0301 * @see setName() 0302 */ 0303 QString name() const; 0304 0305 /** 0306 * Set the user-visible name for this calendar. 0307 * @since 5.85 0308 * @see name() 0309 */ 0310 void setName(const QString &name); 0311 0312 /** 0313 * This calendar's icon. 0314 * @since 5.85 0315 * @see setIconName() 0316 */ 0317 QIcon icon() const; 0318 0319 /** 0320 * Set this calendar's icon. 0321 * @since 5.85 0322 * @see icon() 0323 */ 0324 void setIcon(const QIcon &icon); 0325 0326 /** 0327 * This calendar's AccessMode, i.e. whether it is writable or read-only. 0328 * Defaults to ReadWrite. 0329 * @since 5.85 0330 * @see setAccessMode() 0331 */ 0332 AccessMode accessMode() const; 0333 0334 /** 0335 * Set this calendar's AccessMode, i.e. whether it is writable or read-only. 0336 * @since 5.85 0337 * @see accessMode() 0338 */ 0339 void setAccessMode(const AccessMode mode); 0340 0341 /** 0342 * Returns @c true if the calendar is still loading its data and thus 0343 * read access will not return complete (or even any) results. 0344 * @since 5.96 0345 */ 0346 bool isLoading() const; 0347 0348 /** 0349 Returns a list of all categories used by Incidences in this Calendar. 0350 0351 @return a QStringList containing all the categories. 0352 */ 0353 Q_REQUIRED_RESULT QStringList categories() const; 0354 0355 // Incidence Specific Methods // 0356 0357 /** 0358 Call this to tell the calendar that you're adding a batch of incidences. 0359 So it doesn't, for example, ask the destination for each incidence. 0360 0361 @see endBatchAdding() 0362 */ 0363 virtual void startBatchAdding(); 0364 0365 /** 0366 Tells the Calendar that you stopped adding a batch of incidences. 0367 0368 @see startBatchAdding() 0369 */ 0370 virtual void endBatchAdding(); 0371 0372 /** 0373 @return true if batch adding is in progress 0374 */ 0375 Q_REQUIRED_RESULT bool batchAdding() const; 0376 0377 /** 0378 Inserts an Incidence into the calendar. 0379 0380 @param incidence is a pointer to the Incidence to insert. 0381 0382 @return true if the Incidence was successfully inserted; false otherwise. 0383 0384 @see deleteIncidence() 0385 */ 0386 virtual bool addIncidence(const Incidence::Ptr &incidence); 0387 0388 /** 0389 Removes an Incidence from the calendar. 0390 0391 @param incidence is a pointer to the Incidence to remove. 0392 0393 @return true if the Incidence was successfully removed; false otherwise. 0394 0395 @see addIncidence() 0396 */ 0397 virtual bool deleteIncidence(const Incidence::Ptr &incidence); 0398 0399 /** 0400 Returns a filtered list of all Incidences for this Calendar. 0401 0402 @return the list of all filtered Incidences. 0403 */ 0404 virtual Incidence::List incidences() const; 0405 0406 /** 0407 Returns a filtered list of all Incidences which occur on the given date. 0408 0409 @param date request filtered Incidence list for this QDate only. 0410 0411 @return the list of filtered Incidences occurring on the specified date. 0412 */ 0413 virtual Incidence::List incidences(const QDate &date) const; 0414 0415 /** 0416 Returns an unfiltered list of all Incidences for this Calendar. 0417 0418 @return the list of all unfiltered Incidences. 0419 */ 0420 virtual Incidence::List rawIncidences() const; 0421 0422 /** 0423 Returns an unfiltered list of all exceptions of this recurring incidence. 0424 0425 @param incidence incidence to check 0426 0427 @return the list of all unfiltered exceptions. 0428 */ 0429 virtual Incidence::List instances(const Incidence::Ptr &incidence) const; 0430 0431 /** 0432 Returns the Incidence associated with the given unique identifier. 0433 0434 @param uid is a unique identifier string. 0435 @param recurrenceId is possible recurrenceid of incidence, default is null 0436 0437 @return a pointer to the Incidence. 0438 A null pointer is returned if no such Incidence exists. 0439 */ 0440 Incidence::Ptr incidence(const QString &uid, const QDateTime &recurrenceId = {}) const; 0441 0442 /** 0443 Delete all incidences that are instances of recurring incidence @p incidence. 0444 0445 @param incidence is a pointer to a deleted Incidence 0446 @return true if delete was successful; false otherwise 0447 */ 0448 virtual bool deleteIncidenceInstances(const Incidence::Ptr &incidence) = 0; 0449 0450 /** 0451 Returns the Incidence associated with the given scheduling identifier. 0452 0453 @param sid is a unique scheduling identifier string. 0454 0455 @return a pointer to the Incidence. 0456 A null pointer is returned if no such Incidence exists. 0457 */ 0458 virtual Incidence::Ptr incidenceFromSchedulingID(const QString &sid) const; 0459 0460 /** 0461 Searches all events and todos for an incidence with this 0462 scheduling identifier. Returns a list of matching results. 0463 0464 @param sid is a unique scheduling identifier string. 0465 */ 0466 virtual Incidence::List incidencesFromSchedulingID(const QString &sid) const; 0467 0468 /** 0469 Create a merged list of Events, Todos, and Journals. 0470 0471 @param events is an Event list to merge. 0472 @param todos is a Todo list to merge. 0473 @param journals is a Journal list to merge. 0474 0475 @return a list of merged Incidences. 0476 */ 0477 static Incidence::List mergeIncidenceList(const Event::List &events, const Todo::List &todos, const Journal::List &journals); 0478 0479 /** 0480 Flag that a change to a Calendar Incidence is starting. 0481 @param incidence is a pointer to the Incidence that will be changing. 0482 */ 0483 virtual bool beginChange(const Incidence::Ptr &incidence); 0484 0485 /** 0486 Flag that a change to a Calendar Incidence has completed. 0487 @param incidence is a pointer to the Incidence that was changed. 0488 */ 0489 virtual bool endChange(const Incidence::Ptr &incidence); 0490 0491 /** 0492 Creates an exception for an occurrence from a recurring Incidence. 0493 0494 The returned exception is not automatically inserted into the calendar. 0495 0496 @param incidence is a pointer to a recurring Incidence. 0497 @param recurrenceId specifies the specific occurrence for which the 0498 exception applies. 0499 @param thisAndFuture specifies if the exception applies only this specific 0500 occcurrence or also to all future occurrences. 0501 0502 @return a pointer to a new exception incidence with @param recurrenceId set. 0503 @since 4.11 0504 */ 0505 static Incidence::Ptr createException(const Incidence::Ptr &incidence, const QDateTime &recurrenceId, bool thisAndFuture = false); 0506 0507 // Event Specific Methods // 0508 0509 /** 0510 Inserts an Event into the calendar. 0511 0512 @param event is a pointer to the Event to insert. 0513 0514 @return true if the Event was successfully inserted; false otherwise. 0515 0516 @see deleteEvent() 0517 */ 0518 virtual bool addEvent(const Event::Ptr &event) = 0; 0519 0520 /** 0521 Removes an Event from the calendar. 0522 0523 @param event is a pointer to the Event to remove. 0524 0525 @return true if the Event was successfully remove; false otherwise. 0526 0527 @see addEvent() 0528 */ 0529 virtual bool deleteEvent(const Event::Ptr &event) = 0; 0530 0531 /** 0532 Delete all events that are instances of recurring event @p event. 0533 0534 @param event is a pointer to a deleted Event 0535 @return true if delete was successful; false otherwise 0536 */ 0537 virtual bool deleteEventInstances(const Event::Ptr &event) = 0; 0538 0539 /** 0540 Sort a list of Events. 0541 0542 @param eventList the list of events that should be sorted. The list is sorted in place and returned. 0543 @param sortField specifies the EventSortField. 0544 @param sortDirection specifies the SortDirection. 0545 0546 @return a list of Events sorted as specified. 0547 @since 5.95 0548 */ 0549 static Event::List sortEvents(Event::List &&eventList, EventSortField sortField, SortDirection sortDirection); 0550 0551 /** 0552 Returns a sorted, filtered list of all Events for this Calendar. 0553 0554 @param sortField specifies the EventSortField. 0555 @param sortDirection specifies the SortDirection. 0556 0557 @return the list of all filtered Events sorted as specified. 0558 */ 0559 virtual Event::List events(EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const; 0560 0561 /** 0562 Returns a filtered list of all Events which occur on the given timestamp. 0563 0564 @param dt request filtered Event list for this QDateTime only. 0565 0566 @return the list of filtered Events occurring on the specified timestamp. 0567 */ 0568 Q_REQUIRED_RESULT Event::List events(const QDateTime &dt) const; 0569 0570 /** 0571 Returns a filtered list of all Events occurring within a date range. 0572 0573 @param start is the starting date. 0574 @param end is the ending date. 0575 @param timeZone time zone to interpret @p start and @p end, 0576 or the calendar's default time zone if none is specified 0577 @param inclusive if true only Events which are completely included 0578 within the date range are returned. 0579 0580 @return the list of filtered Events occurring within the specified 0581 date range. 0582 */ 0583 Q_REQUIRED_RESULT Event::List events(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const; 0584 0585 /** 0586 Returns a sorted, filtered list of all Events which occur on the given 0587 date. The Events are sorted according to @a sortField and 0588 @a sortDirection. 0589 0590 @param date request filtered Event list for this QDate only. 0591 @param timeZone time zone to interpret @p start and @p end, 0592 or the calendar's default time zone if none is specified 0593 @param sortField specifies the EventSortField. 0594 @param sortDirection specifies the SortDirection. 0595 0596 @return the list of sorted, filtered Events occurring on @a date. 0597 */ 0598 Q_REQUIRED_RESULT Event::List events(const QDate &date, 0599 const QTimeZone &timeZone = {}, 0600 EventSortField sortField = EventSortUnsorted, 0601 SortDirection sortDirection = SortDirectionAscending) const; 0602 0603 /** 0604 Returns a sorted, unfiltered list of all Events for this Calendar. 0605 0606 @param sortField specifies the EventSortField. 0607 @param sortDirection specifies the SortDirection. 0608 0609 @return the list of all unfiltered Events sorted as specified. 0610 */ 0611 virtual Event::List rawEvents(EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 0612 0613 /** 0614 Returns an unfiltered list of all Events occurring within a date range. 0615 0616 @param start is the starting date 0617 @param end is the ending date 0618 @param timeZone time zone to interpret @p start and @p end, 0619 or the calendar's default time zone if none is specified 0620 @param inclusive if true only Events which are completely included 0621 within the date range are returned. 0622 0623 @return the list of unfiltered Events occurring within the specified 0624 date range. 0625 */ 0626 virtual Event::List rawEvents(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const = 0; 0627 0628 /** 0629 Returns a sorted, unfiltered list of all Events which occur on the given 0630 date. The Events are sorted according to @a sortField and 0631 @a sortDirection. 0632 0633 @param date request unfiltered Event list for this QDate only 0634 @param timeZone time zone to interpret @p date, 0635 or the calendar's default time zone if none is specified 0636 @param sortField specifies the EventSortField 0637 @param sortDirection specifies the SortDirection 0638 0639 @return the list of sorted, unfiltered Events occurring on @p date 0640 */ 0641 virtual Event::List rawEventsForDate(const QDate &date, 0642 const QTimeZone &timeZone = {}, 0643 EventSortField sortField = EventSortUnsorted, 0644 SortDirection sortDirection = SortDirectionAscending) const = 0; 0645 0646 /** 0647 Returns the Event associated with the given unique identifier. 0648 0649 @param uid is a unique identifier string. 0650 @param recurrenceId is possible recurrenceId of event, default is null 0651 0652 @return a pointer to the Event. 0653 A null pointer is returned if no such Event exists. 0654 */ 0655 virtual Event::Ptr event(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 0656 0657 /** 0658 Returns a sorted, unfiltered list of all possible instances for this recurring Event. 0659 0660 @param event event to check for. Caller guarantees it's of type Event. 0661 @param sortField specifies the EventSortField. 0662 @param sortDirection specifies the SortDirection. 0663 0664 @return the list of all unfiltered event instances sorted as specified. 0665 */ 0666 virtual Event::List 0667 eventInstances(const Incidence::Ptr &event, EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 0668 0669 // Todo Specific Methods // 0670 0671 /** 0672 Inserts a Todo into the calendar. 0673 0674 @param todo is a pointer to the Todo to insert. 0675 0676 @return true if the Todo was successfully inserted; false otherwise. 0677 0678 @see deleteTodo() 0679 */ 0680 virtual bool addTodo(const Todo::Ptr &todo) = 0; 0681 0682 /** 0683 Removes a Todo from the calendar. 0684 0685 @param todo is a pointer to the Todo to remove. 0686 0687 @return true if the Todo was successfully removed; false otherwise. 0688 0689 @see addTodo() 0690 */ 0691 virtual bool deleteTodo(const Todo::Ptr &todo) = 0; 0692 0693 /** 0694 Delete all to-dos that are instances of recurring to-do @p todo. 0695 @param todo is a pointer to a deleted Todo 0696 @return true if delete was successful; false otherwise 0697 */ 0698 virtual bool deleteTodoInstances(const Todo::Ptr &todo) = 0; 0699 0700 /** 0701 Sort a list of Todos. 0702 0703 @param todoList the list of todos that should be sorted. The list is sorted in place and returned. 0704 @param sortField specifies the TodoSortField. 0705 @param sortDirection specifies the SortDirection. 0706 0707 @return a list of Todos sorted as specified. 0708 0709 @since 5.95 0710 */ 0711 static Todo::List sortTodos(Todo::List &&todoList, TodoSortField sortField, SortDirection sortDirection); 0712 0713 /** 0714 Returns a sorted, filtered list of all Todos for this Calendar. 0715 0716 @param sortField specifies the TodoSortField. 0717 @param sortDirection specifies the SortDirection. 0718 0719 @return the list of all filtered Todos sorted as specified. 0720 */ 0721 virtual Todo::List todos(TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const; 0722 0723 /** 0724 Returns a filtered list of all Todos which are due on the specified date. 0725 0726 @param date request filtered Todos due on this QDate. 0727 0728 @return the list of filtered Todos due on the specified date. 0729 */ 0730 virtual Todo::List todos(const QDate &date) const; 0731 0732 /** 0733 Returns a filtered list of all Todos occurring within a date range. 0734 0735 @param start is the starting date 0736 @param end is the ending date 0737 @param timeZone time zone to interpret @p start and @p end, 0738 or the calendar's default time zone if none is specified 0739 @param inclusive if true only Todos which are completely included 0740 within the date range are returned. 0741 0742 @return the list of filtered Todos occurring within the specified 0743 date range. 0744 */ 0745 virtual Todo::List todos(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const; 0746 0747 /** 0748 Returns a sorted, unfiltered list of all Todos for this Calendar. 0749 0750 @param sortField specifies the TodoSortField. 0751 @param sortDirection specifies the SortDirection. 0752 0753 @return the list of all unfiltered Todos sorted as specified. 0754 */ 0755 virtual Todo::List rawTodos(TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 0756 0757 /** 0758 Returns an unfiltered list of all Todos which due on the specified date. 0759 0760 @param date request unfiltered Todos due on this QDate. 0761 0762 @return the list of unfiltered Todos due on the specified date. 0763 */ 0764 virtual Todo::List rawTodosForDate(const QDate &date) const = 0; 0765 0766 /** 0767 Returns an unfiltered list of all Todos occurring within a date range. 0768 0769 @param start is the starting date 0770 @param end is the ending date 0771 @param timeZone time zone to interpret @p start and @p end, 0772 or the calendar's default time zone if none is specified 0773 @param inclusive if true only Todos which are completely included 0774 within the date range are returned. 0775 0776 @return the list of unfiltered Todos occurring within the specified 0777 date range. 0778 */ 0779 virtual Todo::List rawTodos(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const = 0; 0780 0781 /** 0782 Returns the Todo associated with the given unique identifier. 0783 0784 @param uid is a unique identifier string. 0785 @param recurrenceId is possible recurrenceId of todo, default is null 0786 0787 @return a pointer to the Todo. 0788 A null pointer is returned if no such Todo exists. 0789 */ 0790 virtual Todo::Ptr todo(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 0791 0792 /** 0793 Returns a sorted, unfiltered list of all possible instances for this recurring Todo. 0794 0795 @param todo todo to check for. Caller guarantees it's of type Todo. 0796 @param sortField specifies the TodoSortField. 0797 @param sortDirection specifies the SortDirection. 0798 0799 @return the list of all unfiltered todo instances sorted as specified. 0800 */ 0801 virtual Todo::List 0802 todoInstances(const Incidence::Ptr &todo, TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 0803 0804 // Journal Specific Methods // 0805 0806 /** 0807 Inserts a Journal into the calendar. 0808 0809 @param journal is a pointer to the Journal to insert. 0810 0811 @return true if the Journal was successfully inserted; false otherwise. 0812 0813 @see deleteJournal() 0814 */ 0815 virtual bool addJournal(const Journal::Ptr &journal) = 0; 0816 0817 /** 0818 Removes a Journal from the calendar. 0819 0820 @param journal is a pointer to the Journal to remove. 0821 0822 @return true if the Journal was successfully removed; false otherwise. 0823 0824 @see addJournal() 0825 */ 0826 virtual bool deleteJournal(const Journal::Ptr &journal) = 0; 0827 0828 /** 0829 Delete all journals that are instances of recurring journal @p journal. 0830 0831 @param journal is a pointer to a deleted Journal 0832 @return true if delete was successful; false otherwise 0833 */ 0834 virtual bool deleteJournalInstances(const Journal::Ptr &journal) = 0; 0835 0836 /** 0837 Sort a list of Journals. 0838 0839 @param journalList the list of journals that should be sorted. The list is sorted in place and returned. 0840 @param sortField specifies the JournalSortField. 0841 @param sortDirection specifies the SortDirection. 0842 0843 @return a list of Journals sorted as specified. 0844 @since 5.95 0845 */ 0846 static Journal::List sortJournals(Journal::List &&journalList, JournalSortField sortField, SortDirection sortDirection); 0847 0848 /** 0849 Returns a sorted, filtered list of all Journals for this Calendar. 0850 0851 @param sortField specifies the JournalSortField. 0852 @param sortDirection specifies the SortDirection. 0853 0854 @return the list of all filtered Journals sorted as specified. 0855 */ 0856 virtual Journal::List journals(JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const; 0857 0858 /** 0859 Returns a filtered list of all Journals for on the specified date. 0860 0861 @param date request filtered Journals for this QDate only. 0862 0863 @return the list of filtered Journals for the specified date. 0864 */ 0865 virtual Journal::List journals(const QDate &date) const; 0866 0867 /** 0868 Returns a sorted, unfiltered list of all Journals for this Calendar. 0869 0870 @param sortField specifies the JournalSortField. 0871 @param sortDirection specifies the SortDirection. 0872 0873 @return the list of all unfiltered Journals sorted as specified. 0874 */ 0875 virtual Journal::List rawJournals(JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 0876 0877 /** 0878 Returns an unfiltered list of all Journals for on the specified date. 0879 0880 @param date request unfiltered Journals for this QDate only. 0881 0882 @return the list of unfiltered Journals for the specified date. 0883 */ 0884 virtual Journal::List rawJournalsForDate(const QDate &date) const = 0; 0885 0886 /** 0887 Returns the Journal associated with the given unique identifier. 0888 0889 @param uid is a unique identifier string. 0890 @param recurrenceId is possible recurrenceId of journal, default is null 0891 0892 @return a pointer to the Journal. 0893 A null pointer is returned if no such Journal exists. 0894 */ 0895 virtual Journal::Ptr journal(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 0896 0897 /** 0898 Returns a sorted, unfiltered list of all instances for this recurring Journal. 0899 0900 @param journal journal to check for. Caller guarantees it's of type Journal. 0901 @param sortField specifies the JournalSortField. 0902 @param sortDirection specifies the SortDirection. 0903 0904 @return the list of all unfiltered journal instances sorted as specified. 0905 */ 0906 virtual Journal::List journalInstances(const Incidence::Ptr &journal, 0907 JournalSortField sortField = JournalSortUnsorted, 0908 SortDirection sortDirection = SortDirectionAscending) const = 0; 0909 0910 // Filter Specific Methods // 0911 0912 /** 0913 Sets the calendar filter. 0914 0915 @param filter a pointer to a CalFilter object which will be 0916 used to filter Calendar Incidences. The Calendar takes 0917 ownership of @p filter. 0918 0919 @see filter() 0920 */ 0921 void setFilter(CalFilter *filter); 0922 0923 /** 0924 Returns the calendar filter. 0925 0926 @return a pointer to the calendar CalFilter. 0927 A null pointer is returned if no such CalFilter exists. 0928 0929 @see setFilter() 0930 */ 0931 CalFilter *filter() const; 0932 0933 // Alarm Specific Methods // 0934 0935 /** 0936 Returns a list of Alarms within a time range for this Calendar. 0937 0938 @param from is the starting timestamp. 0939 @param to is the ending timestamp. 0940 @param excludeBlockedAlarms if true, alarms belonging to blocked collections aren't returned. 0941 0942 @return the list of Alarms for the for the specified time range. 0943 */ 0944 virtual Alarm::List alarms(const QDateTime &from, const QDateTime &to, bool excludeBlockedAlarms = false) const = 0; 0945 0946 /** 0947 Return a list of Alarms that occur before the specified timestamp. 0948 0949 @param to is the ending timestamp. 0950 @return the list of Alarms occurring before the specified QDateTime. 0951 @since 5.77 0952 */ 0953 Q_REQUIRED_RESULT Alarm::List alarmsTo(const QDateTime &to) const; 0954 0955 // Observer Specific Methods // 0956 0957 /** 0958 @class CalendarObserver 0959 0960 The CalendarObserver class. 0961 */ 0962 class KCALENDARCORE_EXPORT CalendarObserver // krazy:exclude=dpointer 0963 { 0964 public: 0965 /** 0966 Destructor. 0967 */ 0968 virtual ~CalendarObserver(); 0969 0970 /** 0971 Notify the Observer that a Calendar has been modified. 0972 0973 @param modified set if the calendar has been modified. 0974 @param calendar is a pointer to the Calendar object that 0975 is being observed. 0976 */ 0977 virtual void calendarModified(bool modified, Calendar *calendar); 0978 0979 /** 0980 Notify the Observer that an Incidence has been inserted. 0981 @param incidence is a pointer to the Incidence that was inserted. 0982 */ 0983 virtual void calendarIncidenceAdded(const Incidence::Ptr &incidence); 0984 0985 /** 0986 Notify the Observer that an Incidence has been modified. 0987 @param incidence is a pointer to the Incidence that was modified. 0988 */ 0989 virtual void calendarIncidenceChanged(const Incidence::Ptr &incidence); 0990 0991 /** 0992 Notify the Observer that an Incidence will be removed. 0993 @param incidence is a pointer to the Incidence that will be removed. 0994 */ 0995 virtual void calendarIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence); 0996 0997 /** 0998 Notify the Observer that an Incidence has been removed. 0999 @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 1035 protected: 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 1131 Q_SIGNALS: 1132 /** 1133 Emitted when setFilter() is called. 1134 @since 4.11 1135 */ 1136 void filterChanged(); 1137 1138 /** 1139 * Emitted when the id changes. 1140 * @since 5.85 1141 * @see id() 1142 */ 1143 void idChanged(); 1144 1145 /** 1146 * Emitted when the name changes. 1147 * @since 5.85 1148 * @see name() 1149 */ 1150 void nameChanged(); 1151 1152 /** 1153 * Emitted when the icon name changes. 1154 * @since 5.85 1155 * @see icon() 1156 */ 1157 void iconChanged(); 1158 1159 /** 1160 * Emitted when the AccessMode changes. 1161 * @since 5.85 1162 * @see accessMode() 1163 */ 1164 void accessModeChanged(); 1165 1166 /** 1167 * Emitted when the owner changes. 1168 * @since 5.85 1169 * @see owner() 1170 */ 1171 void ownerChanged(); 1172 1173 /** 1174 * Emitted when the loading state changed. 1175 * @since 5.96 1176 * @see isLoading() 1177 */ 1178 void isLoadingChanged(); 1179 1180 private: 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 1193 Q_DECLARE_METATYPE(KCalendarCore::Calendar::Ptr) 1194 1195 #endif