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