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