File indexing completed on 2024-05-05 12:10:38
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 Clears out the current calendar, freeing all used memory etc. 0350 */ 0351 virtual void close() = 0; 0352 0353 /** 0354 Syncs changes in memory to persistent storage. 0355 0356 @return true if the save was successful; false otherwise. 0357 Base implementation returns true. 0358 @deprecated since 5.106, non-functional and unused 0359 */ 0360 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "non-functional, will be removed in KF6.") virtual bool save(); 0361 0362 /** 0363 Loads the calendar contents from storage. This requires that the 0364 calendar has been previously loaded (initialized). 0365 0366 @return true if the reload was successful; otherwise false. 0367 Base implementation returns true. 0368 @deprecated since 5.106, non-functional and unused 0369 */ 0370 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "non-functional, will be removed in KF6.") virtual bool reload(); 0371 0372 /** 0373 Determine if the calendar is currently being saved. 0374 0375 @return true if the calendar is currently being saved; false otherwise. 0376 @deprecated since 5.106, non-functional and unused 0377 */ 0378 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "non-functional, will be removed in KF6.") virtual bool isSaving() const; 0379 0380 /** 0381 Returns a list of all categories used by Incidences in this Calendar. 0382 0383 @return a QStringList containing all the categories. 0384 */ 0385 Q_REQUIRED_RESULT QStringList categories() const; 0386 0387 // Incidence Specific Methods // 0388 0389 /** 0390 Call this to tell the calendar that you're adding a batch of incidences. 0391 So it doesn't, for example, ask the destination for each incidence. 0392 0393 @see endBatchAdding() 0394 */ 0395 virtual void startBatchAdding(); 0396 0397 /** 0398 Tells the Calendar that you stopped adding a batch of incidences. 0399 0400 @see startBatchAdding() 0401 */ 0402 virtual void endBatchAdding(); 0403 0404 /** 0405 @return true if batch adding is in progress 0406 */ 0407 Q_REQUIRED_RESULT bool batchAdding() const; 0408 0409 /** 0410 Inserts an Incidence into the calendar. 0411 0412 @param incidence is a pointer to the Incidence to insert. 0413 0414 @return true if the Incidence was successfully inserted; false otherwise. 0415 0416 @see deleteIncidence() 0417 */ 0418 virtual bool addIncidence(const Incidence::Ptr &incidence); 0419 0420 /** 0421 Removes an Incidence from the calendar. 0422 0423 @param incidence is a pointer to the Incidence to remove. 0424 0425 @return true if the Incidence was successfully removed; false otherwise. 0426 0427 @see addIncidence() 0428 */ 0429 virtual bool deleteIncidence(const Incidence::Ptr &incidence); 0430 0431 /** 0432 Returns a filtered list of all Incidences for this Calendar. 0433 0434 @return the list of all filtered Incidences. 0435 */ 0436 virtual Incidence::List incidences() const; 0437 0438 /** 0439 Returns a filtered list of all Incidences which occur on the given date. 0440 0441 @param date request filtered Incidence list for this QDate only. 0442 0443 @return the list of filtered Incidences occurring on the specified date. 0444 */ 0445 virtual Incidence::List incidences(const QDate &date) const; 0446 0447 /** 0448 Returns an unfiltered list of all Incidences for this Calendar. 0449 0450 @return the list of all unfiltered Incidences. 0451 */ 0452 virtual Incidence::List rawIncidences() const; 0453 0454 /** 0455 Returns an unfiltered list of all exceptions of this recurring incidence. 0456 0457 @param incidence incidence to check 0458 0459 @return the list of all unfiltered exceptions. 0460 */ 0461 virtual Incidence::List instances(const Incidence::Ptr &incidence) const; 0462 0463 // Notebook Specific Methods // 0464 0465 /** 0466 Clears notebook associations from hash-tables for incidences. 0467 Called when in-memory content of the calendar is cleared. 0468 @deprecated since 5.106 0469 */ 0470 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0471 virtual void clearNotebookAssociations(); 0472 0473 /** 0474 Associate notebook for an incidence. 0475 0476 @param incidence incidence 0477 @param notebook notebook uid 0478 0479 @return true if the operation was successful; false otherwise. 0480 @deprecated since 5.106 0481 */ 0482 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0483 virtual bool setNotebook(const Incidence::Ptr &incidence, const QString ¬ebook); 0484 0485 /** 0486 Get incidence's notebook. 0487 0488 @param incidence incidence 0489 0490 @return notebook uid 0491 @deprecated since 5.106 0492 */ 0493 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0494 virtual QString notebook(const Incidence::Ptr &incidence) const; 0495 0496 /** 0497 Get incidence's notebook. 0498 0499 @param uid is a unique identifier string 0500 0501 @return notebook uid 0502 @deprecated since 5.106 0503 */ 0504 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0505 virtual QString notebook(const QString &uid) const; 0506 0507 /** 0508 List all uids of notebooks currently in the memory. 0509 0510 @return list of uids of notebooks 0511 @deprecated since 5.106 0512 */ 0513 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0514 virtual QStringList notebooks() const; 0515 0516 /** 0517 Check if calendar knows about the given notebook. 0518 This means that it will be saved by one of the attached storages. 0519 0520 @param notebook notebook uid 0521 @return true if calendar has valid notebook 0522 @deprecated since 5.106 0523 */ 0524 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0525 Q_REQUIRED_RESULT bool hasValidNotebook(const QString ¬ebook) const; 0526 0527 /** 0528 Add notebook information into calendar. 0529 Is usually called by storages only. 0530 0531 @param notebook notebook uid 0532 @param isVisible notebook visibility 0533 @return true if operation succeeded 0534 @see isVisible() 0535 @deprecated since 5.106 0536 */ 0537 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0538 Q_REQUIRED_RESULT bool addNotebook(const QString ¬ebook, bool isVisible); 0539 0540 /** 0541 Update notebook information in calendar. 0542 Is usually called by storages only. 0543 0544 @param notebook notebook uid 0545 @param isVisible notebook visibility 0546 @return true if operation succeeded 0547 @see isVisible() 0548 @deprecated since 5.106 0549 */ 0550 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0551 Q_REQUIRED_RESULT bool updateNotebook(const QString ¬ebook, bool isVisible); 0552 0553 /** 0554 Delete notebook information from calendar. 0555 Is usually called by storages only. 0556 0557 @param notebook notebook uid 0558 @return true if operation succeeded 0559 @see isVisible() 0560 @deprecated since 5.106 0561 */ 0562 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0563 Q_REQUIRED_RESULT bool deleteNotebook(const QString ¬ebook); 0564 0565 /** 0566 set DefaultNotebook information to calendar. 0567 0568 @param notebook notebook uid 0569 @return true if operation was successful; false otherwise. 0570 @deprecated since 5.106 0571 */ 0572 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0573 Q_REQUIRED_RESULT bool setDefaultNotebook(const QString ¬ebook); 0574 0575 /** 0576 Get uid of default notebook. 0577 0578 @return notebook uid 0579 @deprecated since 5.106 0580 */ 0581 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0582 Q_REQUIRED_RESULT QString defaultNotebook() const; 0583 0584 /** 0585 Check if incidence is visible. 0586 @param incidence is a pointer to the Incidence to check for visibility. 0587 @return true if incidence is visible, false otherwise 0588 @deprecated since 5.106 0589 */ 0590 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0591 Q_REQUIRED_RESULT bool isVisible(const Incidence::Ptr &incidence) const; 0592 0593 /** 0594 Check if notebook is visible. 0595 @param notebook notebook uid. 0596 @return true if notebook is visible, false otherwise 0597 @deprecated since 5.106 0598 */ 0599 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0600 Q_REQUIRED_RESULT bool isVisible(const QString ¬ebook) const; 0601 0602 /** 0603 List all notebook incidences in the memory. 0604 0605 @param notebook is the notebook uid. 0606 @return a list of incidences for the notebook. 0607 @deprecated since 5.106 0608 */ 0609 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0610 virtual Incidence::List incidences(const QString ¬ebook) const; 0611 0612 /** 0613 List all possible duplicate incidences. 0614 0615 @param incidence is the incidence to check. 0616 @return a list of duplicate incidences. 0617 @deprecated since 5.106 0618 */ 0619 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "notebook support is going to be removed in KF6") 0620 virtual Incidence::List duplicates(const Incidence::Ptr &incidence); 0621 0622 /** 0623 Returns the Incidence associated with the given unique identifier. 0624 0625 @param uid is a unique identifier string. 0626 @param recurrenceId is possible recurrenceid of incidence, default is null 0627 0628 @return a pointer to the Incidence. 0629 A null pointer is returned if no such Incidence exists. 0630 */ 0631 Incidence::Ptr incidence(const QString &uid, const QDateTime &recurrenceId = {}) const; 0632 0633 /** 0634 Returns the deleted Incidence associated with the given unique identifier. 0635 0636 @param uid is a unique identifier string. 0637 @param recurrenceId is possible recurrenceid of incidence, default is null 0638 0639 @return a pointer to the Incidence. 0640 A null pointer is returned if no such Incidence exists. 0641 */ 0642 Incidence::Ptr deleted(const QString &uid, const QDateTime &recurrenceId = {}) const; 0643 0644 /** 0645 Delete all incidences that are instances of recurring incidence @p incidence. 0646 0647 @param incidence is a pointer to a deleted Incidence 0648 @return true if delete was successful; false otherwise 0649 */ 0650 virtual bool deleteIncidenceInstances(const Incidence::Ptr &incidence) = 0; 0651 0652 /** 0653 Returns the Incidence associated with the given scheduling identifier. 0654 0655 @param sid is a unique scheduling identifier string. 0656 0657 @return a pointer to the Incidence. 0658 A null pointer is returned if no such Incidence exists. 0659 */ 0660 virtual Incidence::Ptr incidenceFromSchedulingID(const QString &sid) const; 0661 0662 /** 0663 Searches all events and todos for an incidence with this 0664 scheduling identifier. Returns a list of matching results. 0665 0666 @param sid is a unique scheduling identifier string. 0667 */ 0668 virtual Incidence::List incidencesFromSchedulingID(const QString &sid) const; 0669 0670 /** 0671 Create a merged list of Events, Todos, and Journals. 0672 0673 @param events is an Event list to merge. 0674 @param todos is a Todo list to merge. 0675 @param journals is a Journal list to merge. 0676 0677 @return a list of merged Incidences. 0678 */ 0679 static Incidence::List mergeIncidenceList(const Event::List &events, const Todo::List &todos, const Journal::List &journals); 0680 0681 /** 0682 Flag that a change to a Calendar Incidence is starting. 0683 @param incidence is a pointer to the Incidence that will be changing. 0684 */ 0685 virtual bool beginChange(const Incidence::Ptr &incidence); 0686 0687 /** 0688 Flag that a change to a Calendar Incidence has completed. 0689 @param incidence is a pointer to the Incidence that was changed. 0690 */ 0691 virtual bool endChange(const Incidence::Ptr &incidence); 0692 0693 /** 0694 Creates an exception for an occurrence from a recurring Incidence. 0695 0696 The returned exception is not automatically inserted into the calendar. 0697 0698 @param incidence is a pointer to a recurring Incidence. 0699 @param recurrenceId specifies the specific occurrence for which the 0700 exception applies. 0701 @param thisAndFuture specifies if the exception applies only this specific 0702 occcurrence or also to all future occurrences. 0703 0704 @return a pointer to a new exception incidence with @param recurrenceId set. 0705 @since 4.11 0706 */ 0707 static Incidence::Ptr createException(const Incidence::Ptr &incidence, const QDateTime &recurrenceId, bool thisAndFuture = false); 0708 0709 // Event Specific Methods // 0710 0711 /** 0712 Inserts an Event into the calendar. 0713 0714 @param event is a pointer to the Event to insert. 0715 0716 @return true if the Event was successfully inserted; false otherwise. 0717 0718 @see deleteEvent() 0719 */ 0720 virtual bool addEvent(const Event::Ptr &event) = 0; 0721 0722 /** 0723 Removes an Event from the calendar. 0724 0725 @param event is a pointer to the Event to remove. 0726 0727 @return true if the Event was successfully remove; false otherwise. 0728 0729 @see addEvent() 0730 */ 0731 virtual bool deleteEvent(const Event::Ptr &event) = 0; 0732 0733 /** 0734 Delete all events that are instances of recurring event @p event. 0735 0736 @param event is a pointer to a deleted Event 0737 @return true if delete was successful; false otherwise 0738 */ 0739 virtual bool deleteEventInstances(const Event::Ptr &event) = 0; 0740 0741 #if KCALENDARCORE_ENABLE_DEPRECATED_SINCE(5, 95) 0742 /** 0743 Sort a list of Events. 0744 0745 @param eventList is a pointer to a list of Events. 0746 @param sortField specifies the EventSortField. 0747 @param sortDirection specifies the SortDirection. 0748 0749 @return a list of Events sorted as specified. 0750 0751 @deprecated since 5.95 Use the sortEvents(Event::List &&eventList, EventSortField sortField, SortDirection sortDirection) 0752 overload instead. In the common case that you are sorting a list in-place, wrapping the @p eventList 0753 argument with std::move will be all that's needed. In the less common case you actually want a copy, 0754 create that explicitly first. 0755 */ 0756 KCALENDARCORE_DEPRECATED_VERSION( 0757 5, 0758 95, 0759 "Use sortEvents(Event::List &&eventList, EventSortField sortField, SortDirection sortDirection); see API docs for details.") 0760 static Event::List sortEvents(const Event::List &eventList, EventSortField sortField, SortDirection sortDirection); 0761 #endif 0762 /** 0763 Sort a list of Events. 0764 0765 @param eventList the list of events that should be sorted. The list is sorted in place and returned. 0766 @param sortField specifies the EventSortField. 0767 @param sortDirection specifies the SortDirection. 0768 0769 @return a list of Events sorted as specified. 0770 @since 5.95 0771 */ 0772 static Event::List sortEvents(Event::List &&eventList, EventSortField sortField, SortDirection sortDirection); 0773 0774 /** 0775 Returns a sorted, filtered list of all Events for this Calendar. 0776 0777 @param sortField specifies the EventSortField. 0778 @param sortDirection specifies the SortDirection. 0779 0780 @return the list of all filtered Events sorted as specified. 0781 */ 0782 virtual Event::List events(EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const; 0783 0784 /** 0785 Returns a filtered list of all Events which occur on the given timestamp. 0786 0787 @param dt request filtered Event list for this QDateTime only. 0788 0789 @return the list of filtered Events occurring on the specified timestamp. 0790 */ 0791 Q_REQUIRED_RESULT Event::List events(const QDateTime &dt) const; 0792 0793 /** 0794 Returns a filtered list of all Events occurring within a date range. 0795 0796 @param start is the starting date. 0797 @param end is the ending date. 0798 @param timeZone time zone to interpret @p start and @p end, 0799 or the calendar's default time zone if none is specified 0800 @param inclusive if true only Events which are completely included 0801 within the date range are returned. 0802 0803 @return the list of filtered Events occurring within the specified 0804 date range. 0805 */ 0806 Q_REQUIRED_RESULT Event::List events(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const; 0807 0808 /** 0809 Returns a sorted, filtered list of all Events which occur on the given 0810 date. The Events are sorted according to @a sortField and 0811 @a sortDirection. 0812 0813 @param date request filtered Event list for this QDate only. 0814 @param timeZone time zone to interpret @p start and @p end, 0815 or the calendar's default time zone if none is specified 0816 @param sortField specifies the EventSortField. 0817 @param sortDirection specifies the SortDirection. 0818 0819 @return the list of sorted, filtered Events occurring on @a date. 0820 */ 0821 Q_REQUIRED_RESULT Event::List events(const QDate &date, 0822 const QTimeZone &timeZone = {}, 0823 EventSortField sortField = EventSortUnsorted, 0824 SortDirection sortDirection = SortDirectionAscending) const; 0825 0826 /** 0827 Returns a sorted, unfiltered list of all Events for this Calendar. 0828 0829 @param sortField specifies the EventSortField. 0830 @param sortDirection specifies the SortDirection. 0831 0832 @return the list of all unfiltered Events sorted as specified. 0833 */ 0834 virtual Event::List rawEvents(EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 0835 0836 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 95) 0837 /** 0838 Returns an unfiltered list of all Events which occur on the given 0839 timestamp. 0840 0841 @param dt request unfiltered Event list for this QDateTime only. 0842 0843 @return the list of unfiltered Events occurring on the specified 0844 timestamp. 0845 0846 @deprecated since 5.95 use rawEventsForDate(dt.date(), dt.timeZone()) overload instead. 0847 */ 0848 KCALENDARCORE_DEPRECATED_VERSION(5, 95, "Use rawEventsForDate(dt.date(), dt.timeZone()) insead") 0849 virtual Event::List rawEventsForDate(const QDateTime &dt) const = 0; 0850 #endif 0851 0852 /** 0853 Returns an unfiltered list of all Events occurring within a date range. 0854 0855 @param start is the starting date 0856 @param end is the ending date 0857 @param timeZone time zone to interpret @p start and @p end, 0858 or the calendar's default time zone if none is specified 0859 @param inclusive if true only Events which are completely included 0860 within the date range are returned. 0861 0862 @return the list of unfiltered Events occurring within the specified 0863 date range. 0864 */ 0865 virtual Event::List rawEvents(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const = 0; 0866 0867 /** 0868 Returns a sorted, unfiltered list of all Events which occur on the given 0869 date. The Events are sorted according to @a sortField and 0870 @a sortDirection. 0871 0872 @param date request unfiltered Event list for this QDate only 0873 @param timeZone time zone to interpret @p date, 0874 or the calendar's default time zone if none is specified 0875 @param sortField specifies the EventSortField 0876 @param sortDirection specifies the SortDirection 0877 0878 @return the list of sorted, unfiltered Events occurring on @p date 0879 */ 0880 virtual Event::List rawEventsForDate(const QDate &date, 0881 const QTimeZone &timeZone = {}, 0882 EventSortField sortField = EventSortUnsorted, 0883 SortDirection sortDirection = SortDirectionAscending) const = 0; 0884 0885 /** 0886 Returns the Event associated with the given unique identifier. 0887 0888 @param uid is a unique identifier string. 0889 @param recurrenceId is possible recurrenceId of event, default is null 0890 0891 @return a pointer to the Event. 0892 A null pointer is returned if no such Event exists. 0893 */ 0894 virtual Event::Ptr event(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 0895 0896 /** 0897 Returns the deleted Event associated with the given unique identifier. 0898 0899 @param uid is a unique identifier string. 0900 @param recurrenceId is possible recurrenceId of event, default is null 0901 0902 @return a pointer to the deleted Event. 0903 A null pointer is returned if no such deleted Event exists, or if deletion tracking 0904 is disabled. 0905 0906 @see deletionTracking() 0907 */ 0908 virtual Event::Ptr deletedEvent(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 0909 0910 /** 0911 Returns a sorted, unfiltered list of all deleted Events for this Calendar. 0912 0913 @param sortField specifies the EventSortField. 0914 @param sortDirection specifies the SortDirection. 0915 0916 @return the list of all unfiltered deleted Events sorted as specified. An empty list 0917 is returned if deletion tracking is disabled. 0918 0919 @see deletionTracking() 0920 */ 0921 virtual Event::List deletedEvents(EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 0922 0923 /** 0924 Returns a sorted, unfiltered list of all possible instances for this recurring Event. 0925 0926 @param event event to check for. Caller guarantees it's of type Event. 0927 @param sortField specifies the EventSortField. 0928 @param sortDirection specifies the SortDirection. 0929 0930 @return the list of all unfiltered event instances sorted as specified. 0931 */ 0932 virtual Event::List 0933 eventInstances(const Incidence::Ptr &event, EventSortField sortField = EventSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 0934 0935 // Todo Specific Methods // 0936 0937 /** 0938 Inserts a Todo into the calendar. 0939 0940 @param todo is a pointer to the Todo to insert. 0941 0942 @return true if the Todo was successfully inserted; false otherwise. 0943 0944 @see deleteTodo() 0945 */ 0946 virtual bool addTodo(const Todo::Ptr &todo) = 0; 0947 0948 /** 0949 Removes a Todo from the calendar. 0950 0951 @param todo is a pointer to the Todo to remove. 0952 0953 @return true if the Todo was successfully removed; false otherwise. 0954 0955 @see addTodo() 0956 */ 0957 virtual bool deleteTodo(const Todo::Ptr &todo) = 0; 0958 0959 /** 0960 Delete all to-dos that are instances of recurring to-do @p todo. 0961 @param todo is a pointer to a deleted Todo 0962 @return true if delete was successful; false otherwise 0963 */ 0964 virtual bool deleteTodoInstances(const Todo::Ptr &todo) = 0; 0965 0966 #if KCALENDARCORE_ENABLE_DEPRECATED_SINCE(5, 95) 0967 /** 0968 Sort a list of Todos. 0969 0970 @param todoList is a pointer to a list of Todos. 0971 @param sortField specifies the TodoSortField. 0972 @param sortDirection specifies the SortDirection. 0973 0974 @return a list of Todos sorted as specified. 0975 0976 @deprecated since 5.95 Use the sortTodos(Todo::List &&todoList, TodoSortField sortField, SortDirection sortDirection) 0977 overload instead. In the common case that you are sorting a list in-place, wrapping the @p todoList 0978 argument with std::move will be all that's needed. In the less common case you actually want a copy, 0979 create that explicitly first. 0980 */ 0981 KCALENDARCORE_DEPRECATED_VERSION(5, 0982 95, 0983 "Use sortTodos(Todo::List &&todoList, TodoSortField sortField, SortDirection sortDirection); see API docs for details.") 0984 static Todo::List sortTodos(const Todo::List &todoList, TodoSortField sortField, SortDirection sortDirection); 0985 #endif 0986 /** 0987 Sort a list of Todos. 0988 0989 @param todoList the list of todos that should be sorted. The list is sorted in place and returned. 0990 @param sortField specifies the TodoSortField. 0991 @param sortDirection specifies the SortDirection. 0992 0993 @return a list of Todos sorted as specified. 0994 0995 @since 5.95 0996 */ 0997 static Todo::List sortTodos(Todo::List &&todoList, TodoSortField sortField, SortDirection sortDirection); 0998 0999 /** 1000 Returns a sorted, filtered list of all Todos for this Calendar. 1001 1002 @param sortField specifies the TodoSortField. 1003 @param sortDirection specifies the SortDirection. 1004 1005 @return the list of all filtered Todos sorted as specified. 1006 */ 1007 virtual Todo::List todos(TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const; 1008 1009 /** 1010 Returns a filtered list of all Todos which are due on the specified date. 1011 1012 @param date request filtered Todos due on this QDate. 1013 1014 @return the list of filtered Todos due on the specified date. 1015 */ 1016 virtual Todo::List todos(const QDate &date) const; 1017 1018 /** 1019 Returns a filtered list of all Todos occurring within a date range. 1020 1021 @param start is the starting date 1022 @param end is the ending date 1023 @param timeZone time zone to interpret @p start and @p end, 1024 or the calendar's default time zone if none is specified 1025 @param inclusive if true only Todos which are completely included 1026 within the date range are returned. 1027 1028 @return the list of filtered Todos occurring within the specified 1029 date range. 1030 */ 1031 virtual Todo::List todos(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const; 1032 1033 /** 1034 Returns a sorted, unfiltered list of all Todos for this Calendar. 1035 1036 @param sortField specifies the TodoSortField. 1037 @param sortDirection specifies the SortDirection. 1038 1039 @return the list of all unfiltered Todos sorted as specified. 1040 */ 1041 virtual Todo::List rawTodos(TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 1042 1043 /** 1044 Returns an unfiltered list of all Todos which due on the specified date. 1045 1046 @param date request unfiltered Todos due on this QDate. 1047 1048 @return the list of unfiltered Todos due on the specified date. 1049 */ 1050 virtual Todo::List rawTodosForDate(const QDate &date) const = 0; 1051 1052 /** 1053 Returns an unfiltered list of all Todos occurring within a date range. 1054 1055 @param start is the starting date 1056 @param end is the ending date 1057 @param timeZone time zone to interpret @p start and @p end, 1058 or the calendar's default time zone if none is specified 1059 @param inclusive if true only Todos which are completely included 1060 within the date range are returned. 1061 1062 @return the list of unfiltered Todos occurring within the specified 1063 date range. 1064 */ 1065 virtual Todo::List rawTodos(const QDate &start, const QDate &end, const QTimeZone &timeZone = {}, bool inclusive = false) const = 0; 1066 1067 /** 1068 Returns the Todo associated with the given unique identifier. 1069 1070 @param uid is a unique identifier string. 1071 @param recurrenceId is possible recurrenceId of todo, default is null 1072 1073 @return a pointer to the Todo. 1074 A null pointer is returned if no such Todo exists. 1075 */ 1076 virtual Todo::Ptr todo(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 1077 1078 /** 1079 Returns the deleted Todo associated with the given unique identifier. 1080 1081 @param uid is a unique identifier string. 1082 @param recurrenceId is possible recurrenceId of todo, default is null 1083 1084 @return a pointer to the deleted Todo. 1085 A null pointer is returned if no such deleted Todo exists or if deletion tracking 1086 is disabled. 1087 1088 @see deletionTracking() 1089 */ 1090 virtual Todo::Ptr deletedTodo(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 1091 1092 /** 1093 Returns a sorted, unfiltered list of all deleted Todos for this Calendar. 1094 1095 @param sortField specifies the TodoSortField. 1096 @param sortDirection specifies the SortDirection. 1097 1098 @return the list of all unfiltered deleted Todos sorted as specified. An empty list 1099 is returned if deletion tracking is disabled. 1100 1101 @see deletionTracking() 1102 */ 1103 virtual Todo::List deletedTodos(TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 1104 1105 /** 1106 Returns a sorted, unfiltered list of all possible instances for this recurring Todo. 1107 1108 @param todo todo to check for. Caller guarantees it's of type Todo. 1109 @param sortField specifies the TodoSortField. 1110 @param sortDirection specifies the SortDirection. 1111 1112 @return the list of all unfiltered todo instances sorted as specified. 1113 */ 1114 virtual Todo::List 1115 todoInstances(const Incidence::Ptr &todo, TodoSortField sortField = TodoSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 1116 1117 // Journal Specific Methods // 1118 1119 /** 1120 Inserts a Journal into the calendar. 1121 1122 @param journal is a pointer to the Journal to insert. 1123 1124 @return true if the Journal was successfully inserted; false otherwise. 1125 1126 @see deleteJournal() 1127 */ 1128 virtual bool addJournal(const Journal::Ptr &journal) = 0; 1129 1130 /** 1131 Removes a Journal from the calendar. 1132 1133 @param journal is a pointer to the Journal to remove. 1134 1135 @return true if the Journal was successfully removed; false otherwise. 1136 1137 @see addJournal() 1138 */ 1139 virtual bool deleteJournal(const Journal::Ptr &journal) = 0; 1140 1141 /** 1142 Delete all journals that are instances of recurring journal @p journal. 1143 1144 @param journal is a pointer to a deleted Journal 1145 @return true if delete was successful; false otherwise 1146 */ 1147 virtual bool deleteJournalInstances(const Journal::Ptr &journal) = 0; 1148 1149 #if KCALENDARCORE_ENABLE_DEPRECATED_SINCE(5, 95) 1150 /** 1151 Sort a list of Journals. 1152 1153 @param journalList is a pointer to a list of Journals. 1154 @param sortField specifies the JournalSortField. 1155 @param sortDirection specifies the SortDirection. 1156 1157 @return a list of Journals sorted as specified. 1158 1159 @deprecated since 5.95 Use the sortJournals(Journal::List &&journalList, JournalSortField sortField, SortDirection sortDirection) 1160 overload instead. In the common case that you are sorting a list in-place, wrapping the @p journalList 1161 argument with std::move will be all that's needed. In the less common case you actually want a copy, 1162 create that explicitly first. 1163 */ 1164 KCALENDARCORE_DEPRECATED_VERSION( 1165 5, 1166 95, 1167 "Use sortJournals(Journal::List &&journalList, JournalSortField sortField, SortDirection sortDirection); see API docs for details.") 1168 static Journal::List sortJournals(const Journal::List &journalList, JournalSortField sortField, SortDirection sortDirection); 1169 #endif 1170 /** 1171 Sort a list of Journals. 1172 1173 @param journalList the list of journals that should be sorted. The list is sorted in place and returned. 1174 @param sortField specifies the JournalSortField. 1175 @param sortDirection specifies the SortDirection. 1176 1177 @return a list of Journals sorted as specified. 1178 @since 5.95 1179 */ 1180 static Journal::List sortJournals(Journal::List &&journalList, JournalSortField sortField, SortDirection sortDirection); 1181 1182 /** 1183 Returns a sorted, filtered list of all Journals for this Calendar. 1184 1185 @param sortField specifies the JournalSortField. 1186 @param sortDirection specifies the SortDirection. 1187 1188 @return the list of all filtered Journals sorted as specified. 1189 */ 1190 virtual Journal::List journals(JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const; 1191 1192 /** 1193 Returns a filtered list of all Journals for on the specified date. 1194 1195 @param date request filtered Journals for this QDate only. 1196 1197 @return the list of filtered Journals for the specified date. 1198 */ 1199 virtual Journal::List journals(const QDate &date) const; 1200 1201 /** 1202 Returns a sorted, unfiltered list of all Journals for this Calendar. 1203 1204 @param sortField specifies the JournalSortField. 1205 @param sortDirection specifies the SortDirection. 1206 1207 @return the list of all unfiltered Journals sorted as specified. 1208 */ 1209 virtual Journal::List rawJournals(JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 1210 1211 /** 1212 Returns an unfiltered list of all Journals for on the specified date. 1213 1214 @param date request unfiltered Journals for this QDate only. 1215 1216 @return the list of unfiltered Journals for the specified date. 1217 */ 1218 virtual Journal::List rawJournalsForDate(const QDate &date) const = 0; 1219 1220 /** 1221 Returns the Journal associated with the given unique identifier. 1222 1223 @param uid is a unique identifier string. 1224 @param recurrenceId is possible recurrenceId of journal, default is null 1225 1226 @return a pointer to the Journal. 1227 A null pointer is returned if no such Journal exists. 1228 */ 1229 virtual Journal::Ptr journal(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 1230 1231 /** 1232 Returns the deleted Journal associated with the given unique identifier. 1233 1234 @param uid is a unique identifier string. 1235 @param recurrenceId is possible recurrenceId of journal, default is null 1236 1237 @return a pointer to the deleted Journal. 1238 A null pointer is returned if no such deleted Journal exists or if deletion tracking 1239 is disabled. 1240 1241 @see deletionTracking() 1242 */ 1243 virtual Journal::Ptr deletedJournal(const QString &uid, const QDateTime &recurrenceId = {}) const = 0; 1244 1245 /** 1246 Returns a sorted, unfiltered list of all deleted Journals for this Calendar. 1247 1248 @param sortField specifies the JournalSortField. 1249 @param sortDirection specifies the SortDirection. 1250 1251 @return the list of all unfiltered deleted Journals sorted as specified. An empty list 1252 is returned if deletion tracking is disabled. 1253 1254 @see deletionTracking() 1255 */ 1256 virtual Journal::List deletedJournals(JournalSortField sortField = JournalSortUnsorted, SortDirection sortDirection = SortDirectionAscending) const = 0; 1257 1258 /** 1259 Returns a sorted, unfiltered list of all instances for this recurring Journal. 1260 1261 @param journal journal to check for. Caller guarantees it's of type Journal. 1262 @param sortField specifies the JournalSortField. 1263 @param sortDirection specifies the SortDirection. 1264 1265 @return the list of all unfiltered journal instances sorted as specified. 1266 */ 1267 virtual Journal::List journalInstances(const Incidence::Ptr &journal, 1268 JournalSortField sortField = JournalSortUnsorted, 1269 SortDirection sortDirection = SortDirectionAscending) const = 0; 1270 1271 // Relations Specific Methods // 1272 1273 /** 1274 Setup Relations for an Incidence. 1275 @param incidence is a pointer to the Incidence to have a Relation setup. 1276 @deprecated since 5.106 1277 */ 1278 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "Relation API is going to be removed in KF6.") 1279 virtual void setupRelations(const Incidence::Ptr &incidence); 1280 1281 /** 1282 Removes all Relations from an Incidence. 1283 1284 @param incidence is a pointer to the Incidence to have a Relation removed. 1285 @deprecated since 5.106 1286 */ 1287 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "Relation API is going to be removed in KF6.") 1288 virtual void removeRelations(const Incidence::Ptr &incidence); 1289 1290 /** 1291 Checks if @p ancestor is an ancestor of @p incidence 1292 1293 @param ancestor is the incidence we are testing to be an ancestor. 1294 @param incidence is the incidence we are testing to be descended from @p ancestor. 1295 @deprecated since 5.106 1296 */ 1297 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "Relation API is going to be removed in KF6.") 1298 bool isAncestorOf(const Incidence::Ptr &ancestor, const Incidence::Ptr &incidence) const; 1299 1300 /** 1301 Returns a list of incidences that have a relation of RELTYPE parent 1302 to incidence @p uid. 1303 1304 @param uid The parent identifier whose children we want to obtain. 1305 @deprecated since 5.106 1306 */ 1307 KCALENDARCORE_DEPRECATED_VERSION(5, 106, "Relation API is going to be removed in KF6.") 1308 Incidence::List relations(const QString &uid) const; 1309 1310 // Filter Specific Methods // 1311 1312 /** 1313 Sets the calendar filter. 1314 1315 @param filter a pointer to a CalFilter object which will be 1316 used to filter Calendar Incidences. The Calendar takes 1317 ownership of @p filter. 1318 1319 @see filter() 1320 */ 1321 void setFilter(CalFilter *filter); 1322 1323 /** 1324 Returns the calendar filter. 1325 1326 @return a pointer to the calendar CalFilter. 1327 A null pointer is returned if no such CalFilter exists. 1328 1329 @see setFilter() 1330 */ 1331 CalFilter *filter() const; 1332 1333 // Alarm Specific Methods // 1334 1335 /** 1336 Returns a list of Alarms within a time range for this Calendar. 1337 1338 @param from is the starting timestamp. 1339 @param to is the ending timestamp. 1340 @param excludeBlockedAlarms if true, alarms belonging to blocked collections aren't returned. 1341 1342 @return the list of Alarms for the for the specified time range. 1343 */ 1344 virtual Alarm::List alarms(const QDateTime &from, const QDateTime &to, bool excludeBlockedAlarms = false) const = 0; 1345 1346 /** 1347 Return a list of Alarms that occur before the specified timestamp. 1348 1349 @param to is the ending timestamp. 1350 @return the list of Alarms occurring before the specified QDateTime. 1351 @since 5.77 1352 */ 1353 Q_REQUIRED_RESULT Alarm::List alarmsTo(const QDateTime &to) const; 1354 1355 // Observer Specific Methods // 1356 1357 /** 1358 @class CalendarObserver 1359 1360 The CalendarObserver class. 1361 */ 1362 class KCALENDARCORE_EXPORT CalendarObserver // krazy:exclude=dpointer 1363 { 1364 public: 1365 /** 1366 Destructor. 1367 */ 1368 virtual ~CalendarObserver(); 1369 1370 /** 1371 Notify the Observer that a Calendar has been modified. 1372 1373 @param modified set if the calendar has been modified. 1374 @param calendar is a pointer to the Calendar object that 1375 is being observed. 1376 */ 1377 virtual void calendarModified(bool modified, Calendar *calendar); 1378 1379 /** 1380 Notify the Observer that an Incidence has been inserted. 1381 @param incidence is a pointer to the Incidence that was inserted. 1382 */ 1383 virtual void calendarIncidenceAdded(const Incidence::Ptr &incidence); 1384 1385 /** 1386 Notify the Observer that an Incidence has been modified. 1387 @param incidence is a pointer to the Incidence that was modified. 1388 */ 1389 virtual void calendarIncidenceChanged(const Incidence::Ptr &incidence); 1390 1391 /** 1392 Notify the Observer that an Incidence will be removed. 1393 @param incidence is a pointer to the Incidence that will be removed. 1394 */ 1395 virtual void calendarIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence); 1396 1397 /** 1398 Notify the Observer that an Incidence has been removed. 1399 @param incidence is a pointer to the Incidence that was removed. 1400 @param calendar is a pointer to the calendar where the incidence was part of, 1401 because the incidence was deleted, there is now way to determine the calendar 1402 @since 4.83.0 1403 */ 1404 virtual void calendarIncidenceDeleted(const Incidence::Ptr &incidence, const Calendar *calendar); 1405 1406 /** 1407 Notify the Observer that an addition of Incidence has been canceled. 1408 @param incidence is a pointer to the Incidence that was removed. 1409 */ 1410 virtual void calendarIncidenceAdditionCanceled(const Incidence::Ptr &incidence); 1411 }; 1412 1413 /** 1414 Registers an Observer for this Calendar. 1415 1416 @param observer is a pointer to an Observer object that will be 1417 watching this Calendar. 1418 1419 @see unregisterObserver() 1420 */ 1421 void registerObserver(CalendarObserver *observer); 1422 1423 /** 1424 Unregisters an Observer for this Calendar. 1425 1426 @param observer is a pointer to an Observer object that has been 1427 watching this Calendar. 1428 1429 @see registerObserver() 1430 */ 1431 void unregisterObserver(CalendarObserver *observer); 1432 1433 using QObject::event; // prevent warning about hidden virtual method 1434 1435 protected: 1436 /** 1437 The Observer interface. So far not implemented. 1438 @param uid is the UID for the Incidence that has been updated. 1439 @param recurrenceId is possible recurrenceid of incidence. 1440 */ 1441 void incidenceUpdated(const QString &uid, const QDateTime &recurrenceId) override; 1442 1443 /** 1444 Let Calendar subclasses set the time specification. 1445 @param timeZone is the time specification (time zone, etc.) for 1446 viewing Incidence dates.\n 1447 */ 1448 virtual void doSetTimeZone(const QTimeZone &timeZone); 1449 1450 /** 1451 Let Calendar subclasses notify that they inserted an Incidence. 1452 @param incidence is a pointer to the Incidence object that was inserted. 1453 */ 1454 void notifyIncidenceAdded(const Incidence::Ptr &incidence); 1455 1456 /** 1457 Let Calendar subclasses notify that they modified an Incidence. 1458 @param incidence is a pointer to the Incidence object that was modified. 1459 */ 1460 void notifyIncidenceChanged(const Incidence::Ptr &incidence); 1461 1462 /** 1463 Let Calendar subclasses notify that they will remove an Incidence. 1464 @param incidence is a pointer to the Incidence object that will be removed. 1465 */ 1466 void notifyIncidenceAboutToBeDeleted(const Incidence::Ptr &incidence); 1467 1468 /** 1469 Let Calendar subclasses notify that they removed an Incidence. 1470 @param incidence is a pointer to the Incidence object that has been removed. 1471 */ 1472 void notifyIncidenceDeleted(const Incidence::Ptr &incidence); 1473 1474 /** 1475 Let Calendar subclasses notify that they canceled addition of an Incidence. 1476 @param incidence is a pointer to the Incidence object that addition as canceled. 1477 */ 1478 void notifyIncidenceAdditionCanceled(const Incidence::Ptr &incidence); 1479 1480 /** 1481 @copydoc 1482 CustomProperties::customPropertyUpdated() 1483 */ 1484 void customPropertyUpdated() override; 1485 1486 /** 1487 Let Calendar subclasses notify that they enabled an Observer. 1488 1489 @param enabled if true tells the calendar that a subclass has 1490 enabled an Observer. 1491 */ 1492 void setObserversEnabled(bool enabled); 1493 1494 /** 1495 Appends alarms of incidence in interval to list of alarms. 1496 1497 @param alarms is a List of Alarms to be appended onto. 1498 @param incidence is a pointer to an Incidence containing the Alarm 1499 to be appended. 1500 @param from is the lower range of the next Alarm repetition. 1501 @param to is the upper range of the next Alarm repetition. 1502 */ 1503 void appendAlarms(Alarm::List &alarms, const Incidence::Ptr &incidence, const QDateTime &from, const QDateTime &to) const; 1504 1505 /** 1506 Appends alarms of recurring events in interval to list of alarms. 1507 1508 @param alarms is a List of Alarms to be appended onto. 1509 @param incidence is a pointer to an Incidence containing the Alarm 1510 to be appended. 1511 @param from is the lower range of the next Alarm repetition. 1512 @param to is the upper range of the next Alarm repetition. 1513 */ 1514 void appendRecurringAlarms(Alarm::List &alarms, const Incidence::Ptr &incidence, const QDateTime &from, const QDateTime &to) const; 1515 1516 /** 1517 Enables or disabled deletion tracking. 1518 Default is true. 1519 @see deletedEvent() 1520 @see deletedTodo() 1521 @see deletedJournal() 1522 @since 4.11 1523 */ 1524 void setDeletionTracking(bool enable); 1525 1526 /** 1527 Returns if deletion tracking is enabled. 1528 Default is true. 1529 @since 4.11 1530 */ 1531 bool deletionTracking() const; 1532 1533 /** 1534 * Sets the loading state of this calendar. 1535 * This is false by default and only needs to be called for calendars 1536 * that implement asynchronous loading. 1537 * @since 5.96 1538 * @see isLoading() 1539 */ 1540 void setIsLoading(bool isLoading); 1541 1542 /** 1543 @copydoc 1544 IncidenceBase::virtual_hook() 1545 */ 1546 virtual void virtual_hook(int id, void *data); 1547 1548 Q_SIGNALS: 1549 /** 1550 Emitted when setFilter() is called. 1551 @since 4.11 1552 */ 1553 void filterChanged(); 1554 1555 /** 1556 * Emitted when the id changes. 1557 * @since 5.85 1558 * @see id() 1559 */ 1560 void idChanged(); 1561 1562 /** 1563 * Emitted when the name changes. 1564 * @since 5.85 1565 * @see name() 1566 */ 1567 void nameChanged(); 1568 1569 /** 1570 * Emitted when the icon name changes. 1571 * @since 5.85 1572 * @see icon() 1573 */ 1574 void iconChanged(); 1575 1576 /** 1577 * Emitted when the AccessMode changes. 1578 * @since 5.85 1579 * @see accessMode() 1580 */ 1581 void accessModeChanged(); 1582 1583 /** 1584 * Emitted when the owner changes. 1585 * @since 5.85 1586 * @see owner() 1587 */ 1588 void ownerChanged(); 1589 1590 /** 1591 * Emitted when the loading state changed. 1592 * @since 5.96 1593 * @see isLoading() 1594 */ 1595 void isLoadingChanged(); 1596 1597 private: 1598 friend class ICalFormat; 1599 1600 //@cond PRIVATE 1601 class Private; 1602 Private *const d; 1603 //@endcond 1604 1605 Q_DISABLE_COPY(Calendar) 1606 }; 1607 1608 } 1609 1610 Q_DECLARE_METATYPE(KCalendarCore::Calendar::Ptr) 1611 1612 #endif