1/*
2 This file is part of the kcal 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#ifndef KCAL_CALENDAR_H
36#define KCAL_CALENDAR_H
37
38#include <QtCore/QObject>
39#include <QtCore/QString>
40#include <QtCore/QList>
41#include <QtCore/QMultiHash>
42
43#include <kdatetime.h>
44
45#include "customproperties.h"
46#include "event.h"
47#include "todo.h"
48#include "journal.h"
49#include "kcalversion.h"
50
51namespace KCal {
52
53class ICalTimeZone;
54class ICalTimeZones;
55class CalFilter;
56class Person;
57
58/**
59 Calendar Incidence sort directions.
60*/
61enum SortDirection {
62 SortDirectionAscending, /**< Sort in ascending order (first to last) */
63 SortDirectionDescending /**< Sort in descending order (last to first) */
64};
65
66/**
67 Calendar Event sort keys.
68*/
69enum EventSortField {
70 EventSortUnsorted, /**< Do not sort Events */
71 EventSortStartDate, /**< Sort Events chronologically, by start date */
72 EventSortEndDate, /**< Sort Events chronologically, by end date */
73 EventSortSummary /**< Sort Events alphabetically, by summary */
74};
75
76/**
77 Calendar Todo sort keys.
78*/
79enum TodoSortField {
80 TodoSortUnsorted, /**< Do not sort Todos */
81 TodoSortStartDate, /**< Sort Todos chronologically, by start date */
82 TodoSortDueDate, /**< Sort Todos chronologically, by due date */
83 TodoSortPriority, /**< Sort Todos by priority */
84 TodoSortPercentComplete, /**< Sort Todos by percentage completed */
85 TodoSortSummary /**< Sort Todos alphabetically, by summary */
86};
87
88/**
89 Calendar Journal sort keys.
90*/
91enum JournalSortField {
92 JournalSortUnsorted, /**< Do not sort Journals */
93 JournalSortDate, /**< Sort Journals chronologically by date */
94 JournalSortSummary /**< Sort Journals alphabetically, by summary */
95};
96
97/**
98 @brief
99 Represents the main calendar class.
100
101 A calendar contains information like incidences (events, to-dos, journals),
102 alarms, time zones, and other useful information.
103
104 This is an abstract base class defining the interface to a calendar.
105 It is implemented by subclasses like CalendarLocal, which use different
106 methods to store and access the data.
107
108 <b>Ownership of Incidences</b>:
109
110 Incidence ownership is handled by the following policy: as soon as an
111 incidence (or any other subclass of IncidenceBase) is added to the
112 Calendar by an add...() method it is owned by the Calendar object.
113 The Calendar takes care of deleting the incidence using the delete...()
114 methods. All Incidences returned by the query functions are returned
115 as pointers so that changes to the returned Incidences are immediately
116 visible in the Calendar. Do <em>Not</em> attempt to 'delete' any Incidence
117 object you get from Calendar -- use the delete...() methods.
118*/
119class KCAL_DEPRECATED_EXPORT Calendar : public QObject, public CustomProperties,
120 public IncidenceBase::IncidenceObserver
121{
122 Q_OBJECT
123
124 public:
125
126 /**
127 Constructs a calendar with a specified time zone @p timeZoneid.
128 The time specification is used as the default for creating or
129 modifying incidences in the Calendar. The time specification does
130 not alter existing incidences.
131
132 The constructor also calls setViewTimeSpec(@p timeSpec).
133
134 @param timeSpec time specification
135 */
136 explicit Calendar( const KDateTime::Spec &timeSpec );
137
138 /**
139 Construct Calendar object using a time zone ID.
140 The time zone ID is used as the default for creating or modifying
141 incidences in the Calendar. The time zone does not alter existing
142 incidences.
143
144 The constructor also calls setViewTimeZoneId(@p timeZoneId).
145
146 @param timeZoneId is a string containing a time zone ID, which is
147 assumed to be valid. If no time zone is found, the viewing time
148 specification is set to local clock time.
149 @e Example: "Europe/Berlin"
150 */
151 explicit Calendar( const QString &timeZoneId );
152
153 /**
154 Destroys the calendar.
155 */
156 virtual ~Calendar();
157
158 /**
159 Sets the calendar Product ID to @p id.
160
161 @param id is a string containing the Product ID.
162
163 @see productId() const
164 */
165 void setProductId( const QString &id );
166
167 /**
168 Returns the calendar's Product ID.
169
170 @see setProductId()
171 */
172 QString productId() const;
173
174 /**
175 Sets the owner of the calendar to @p owner.
176
177 @param owner is a Person object.
178
179 @see owner()
180 */
181 void setOwner( const Person &owner );
182
183 /**
184 Returns the owner of the calendar.
185
186 @return the owner Person object.
187
188 @see setOwner()
189 */
190 Person owner() const;
191
192 /**
193 Sets the default time specification (time zone, etc.) used for creating
194 or modifying incidences in the Calendar.
195
196 The method also calls setViewTimeSpec(@p timeSpec).
197
198 @param timeSpec time specification
199 */
200 void setTimeSpec( const KDateTime::Spec &timeSpec );
201
202 /**
203 Get the time specification (time zone etc.) used for creating or
204 modifying incidences in the Calendar.
205
206 @return time specification
207 */
208 KDateTime::Spec timeSpec() const;
209
210 /**
211 Sets the time zone ID used for creating or modifying incidences in the
212 Calendar. This method has no effect on existing incidences.
213
214 The method also calls setViewTimeZoneId(@p timeZoneId).
215
216 @param timeZoneId is a string containing a time zone ID, which is
217 assumed to be valid. The time zone ID is used to set the time zone
218 for viewing Incidence date/times. If no time zone is found, the
219 viewing time specification is set to local clock time.
220 @e Example: "Europe/Berlin"
221 @see setTimeSpec()
222 */
223 void setTimeZoneId( const QString &timeZoneId );
224
225 /**
226 Returns the time zone ID used for creating or modifying incidences in
227 the calendar.
228
229 @return the string containing the time zone ID, or empty string if the
230 creation/modification time specification is not a time zone.
231 */
232 QString timeZoneId() const;
233
234 /**
235 Notes the time specification which the client application intends to
236 use for viewing the incidences in this calendar. This is simply a
237 convenience method which makes a note of the new time zone so that
238 it can be read back by viewTimeSpec(). The client application must
239 convert date/time values to the desired time zone itself.
240
241 The time specification is not used in any way by the Calendar or its
242 incidences; it is solely for use by the client application.
243
244 @param timeSpec time specification
245
246 @see viewTimeSpec()
247 */
248 void setViewTimeSpec( const KDateTime::Spec &timeSpec ) const;
249
250 /**
251 Notes the time zone Id which the client application intends to use for
252 viewing the incidences in this calendar. This is simply a convenience
253 method which makes a note of the new time zone so that it can be read
254 back by viewTimeId(). The client application must convert date/time
255 values to the desired time zone itself.
256
257 The Id is not used in any way by the Calendar or its incidences.
258 It is solely for use by the client application.
259
260 @param timeZoneId is a string containing a time zone ID, which is
261 assumed to be valid. The time zone ID is used to set the time zone
262 for viewing Incidence date/times. If no time zone is found, the
263 viewing time specification is set to local clock time.
264 @e Example: "Europe/Berlin"
265
266 @see viewTimeZoneId()
267 */
268 void setViewTimeZoneId( const QString &timeZoneId ) const;
269
270 /**
271 Returns the time specification used for viewing the incidences in
272 this calendar. This simply returns the time specification last
273 set by setViewTimeSpec().
274 @see setViewTimeSpec().
275 */
276 KDateTime::Spec viewTimeSpec() const;
277
278 /**
279 Returns the time zone Id used for viewing the incidences in this
280 calendar. This simply returns the time specification last set by
281 setViewTimeSpec().
282 @see setViewTimeZoneId().
283 */
284 QString viewTimeZoneId() const;
285
286 /**
287 Shifts the times of all incidences so that they appear at the same clock
288 time as before but in a new time zone. The shift is done from a viewing
289 time zone rather than from the actual incidence time zone.
290
291 For example, shifting an incidence whose start time is 09:00 America/New York,
292 using an old viewing time zone (@p oldSpec) of Europe/London, to a new time
293 zone (@p newSpec) of Europe/Paris, will result in the time being shifted
294 from 14:00 (which is the London time of the incidence start) to 14:00 Paris
295 time.
296
297 @param oldSpec the time specification which provides the clock times
298 @param newSpec the new time specification
299
300 @see isLocalTime()
301 */
302 void shiftTimes( const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec );
303
304 /**
305 Returns the time zone collection used by the calendar.
306
307 @return the time zones collection.
308
309 @see setLocalTime()
310 */
311 ICalTimeZones *timeZones() const;
312
313 /**
314 Set the time zone collection used by the calendar.
315
316 @param zones time zones collection. Important: all time zones references
317 in the calendar must be included in the collection.
318 */
319 void setTimeZones( const ICalTimeZones &zones );
320
321 /**
322 Sets if the calendar has been modified.
323
324 @param modified is true if the calendar has been modified since open
325 or last save.
326
327 @see isModified()
328 */
329 void setModified( bool modified );
330
331 /**
332 Determine the calendar's modification status.
333
334 @return true if the calendar has been modified since open or last save.
335
336 @see setModified()
337 */
338 bool isModified() const;
339
340 /**
341 Clears out the current calendar, freeing all used memory etc.
342 */
343 virtual void close() = 0;
344
345 /**
346 Syncs changes in memory to persistent storage.
347
348 @return true if the save was successful; false otherwise.
349 */
350 virtual bool save() = 0;
351
352 /**
353 Loads the calendar contents from storage. This requires that the
354 calendar has been previously loaded (initialized).
355
356 @return true if the reload was successful; otherwise false.
357 */
358 virtual bool reload() = 0;
359
360 /**
361 Determine if the calendar is currently being saved.
362
363 @return true if the calendar is currently being saved; false otherwise.
364 */
365 virtual bool isSaving();
366
367 /**
368 Returns a list of all categories used by Incidences in this Calendar.
369
370 @return a QStringList containing all the categories.
371 */
372 QStringList categories();
373
374 // Incidence Specific Methods //
375
376 /**
377 Inserts an Incidence into the calendar.
378
379 @param incidence is a pointer to the Incidence to insert.
380
381 @return true if the Incidence was successfully inserted; false otherwise.
382
383 @see deleteIncidence()
384 */
385 virtual bool addIncidence( Incidence *incidence );
386
387 /**
388 Removes an Incidence from the calendar.
389
390 @param incidence is a pointer to the Incidence to remove.
391
392 @return true if the Incidence was successfully removed; false otherwise.
393
394 @see addIncidence()
395 */
396 virtual bool deleteIncidence( Incidence *incidence );
397
398 /**
399 Returns a filtered list of all Incidences for this Calendar.
400
401 @return the list of all filtered Incidences.
402 */
403 virtual Incidence::List incidences();
404
405 /**
406 Returns a filtered list of all Incidences which occur on the given date.
407
408 @param date request filtered Incidence list for this QDate only.
409
410 @return the list of filtered Incidences occurring on the specified date.
411 */
412 virtual Incidence::List incidences( const QDate &date );
413
414 /**
415 Returns an unfiltered list of all Incidences for this Calendar.
416
417 @return the list of all unfiltered Incidences.
418 */
419 virtual Incidence::List rawIncidences();
420
421 /**
422 Returns the Incidence associated with the given unique identifier.
423
424 @param uid is a unique identifier string.
425
426 @return a pointer to the Incidence.
427 A null pointer is returned if no such Incidence exists.
428 */
429 Incidence *incidence( const QString &uid );
430
431 /**
432 Returns the Incidence associated with the given scheduling identifier.
433
434 @param sid is a unique scheduling identifier string.
435
436 @return a pointer to the Incidence.
437 A null pointer is returned if no such Incidence exists.
438 */
439 Incidence *incidenceFromSchedulingID( const QString &sid );
440
441 /**
442 Searches all events and todos for an incidence with this
443 scheduling identifiere. Returns a list of matching results.
444
445 @param sid is a unique scheduling identifier string.
446 */
447 Incidence::List incidencesFromSchedulingID( const QString &sid );
448
449 /**
450 Create a merged list of Events, Todos, and Journals.
451
452 @param events is an Event list to merge.
453 @param todos is a Todo list to merge.
454 @param journals is a Journal list to merge.
455
456 @return a list of merged Incidences.
457 */
458 static Incidence::List mergeIncidenceList( const Event::List &events,
459 const Todo::List &todos,
460 const Journal::List &journals );
461
462 /**
463 Flag that a change to a Calendar Incidence is starting.
464
465 @param incidence is a pointer to the Incidence that will be changing.
466 */
467 virtual bool beginChange( Incidence *incidence );
468
469 /**
470 Flag that a change to a Calendar Incidence has completed.
471
472 @param incidence is a pointer to the Incidence that was changed.
473 */
474 virtual bool endChange( Incidence *incidence );
475
476 /**
477 Dissociate an Incidence from a recurring Incidence.
478 By default, only one single Incidence for the specified @a date
479 will be dissociated and returned. If @a single is false, then
480 the recurrence will be split at @a date, the old Incidence will
481 have its recurrence ending at @a date and the new Incidence
482 will have all recurrences past the @a date.
483
484 @param incidence is a pointer to a recurring Incidence.
485 @param date is the QDate within the recurring Incidence on which
486 the dissociation will be performed.
487 @param spec is the spec in which the @a date is formulated.
488 @param single is a flag meaning that a new Incidence should be created
489 from the recurring Incidences after @a date.
490
491 @return a pointer to a new recurring Incidence if @a single is false.
492 */
493 Incidence *dissociateOccurrence( Incidence *incidence, const QDate &date,
494 const KDateTime::Spec &spec,
495 bool single = true );
496
497 // Event Specific Methods //
498
499 /**
500 Inserts an Event into the calendar.
501
502 @param event is a pointer to the Event to insert.
503
504 @return true if the Event was successfully inserted; false otherwise.
505
506 @see deleteEvent()
507 */
508 virtual bool addEvent( Event *event ) = 0;
509
510 /**
511 Removes an Event from the calendar.
512
513 @param event is a pointer to the Event to remove.
514
515 @return true if the Event was successfully remove; false otherwise.
516
517 @see addEvent(), deleteAllEvents()
518 */
519 virtual bool deleteEvent( Event *event ) = 0;
520
521 /**
522 Removes all Events from the calendar.
523 @see deleteEvent()
524 */
525 virtual void deleteAllEvents() = 0;
526
527 /**
528 Sort a list of Events.
529
530 @param eventList is a pointer to a list of Events.
531 @param sortField specifies the EventSortField.
532 @param sortDirection specifies the SortDirection.
533
534 @return a list of Events sorted as specified.
535 */
536 static Event::List sortEvents( Event::List *eventList,
537 EventSortField sortField,
538 SortDirection sortDirection );
539
540 /**
541 Sort a list of Events that occur on a specified date.
542
543 @param eventList is a pointer to a list of Events occurring on @p date.
544 @param date is the date.
545 @param timeSpec time specification for @p date.
546 @param sortField specifies the EventSortField.
547 @param sortDirection specifies the SortDirection.
548
549 @return a list of Events sorted as specified.
550
551 @since 4.5
552 */
553 static Event::List sortEventsForDate( Event::List *eventList,
554 const QDate &date,
555 const KDateTime::Spec &timeSpec,
556 EventSortField sortField,
557 SortDirection sortDirection );
558
559 /**
560 Returns a sorted, filtered list of all Events for this Calendar.
561
562 @param sortField specifies the EventSortField.
563 @param sortDirection specifies the SortDirection.
564
565 @return the list of all filtered Events sorted as specified.
566 */
567 virtual Event::List events(
568 EventSortField sortField = EventSortUnsorted,
569 SortDirection sortDirection = SortDirectionAscending );
570
571 /**
572 Returns a filtered list of all Events which occur on the given timestamp.
573
574 @param dt request filtered Event list for this KDateTime only.
575
576 @return the list of filtered Events occurring on the specified timestamp.
577 */
578 Event::List events( const KDateTime &dt );
579
580 /**
581 Returns a filtered list of all Events occurring within a date range.
582
583 @param start is the starting date.
584 @param end is the ending date.
585 @param timeSpec time zone etc. to interpret @p start and @p end,
586 or the calendar's default time spec if none is specified
587 @param inclusive if true only Events which are completely included
588 within the date range are returned.
589
590 @return the list of filtered Events occurring within the specified
591 date range.
592 */
593 Event::List events( const QDate &start, const QDate &end,
594 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
595 bool inclusive = false );
596
597 /**
598 Returns a sorted, filtered list of all Events which occur on the given
599 date. The Events are sorted according to @a sortField and
600 @a sortDirection.
601
602 @param date request filtered Event list for this QDate only.
603 @param timeSpec time zone etc. to interpret @p start and @p end,
604 or the calendar's default time spec if none is specified
605 @param sortField specifies the EventSortField.
606 @param sortDirection specifies the SortDirection.
607
608 @return the list of sorted, filtered Events occurring on @a date.
609 */
610 Event::List events(
611 const QDate &date,
612 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
613 EventSortField sortField = EventSortUnsorted,
614 SortDirection sortDirection = SortDirectionAscending );
615
616 /**
617 Returns a sorted, unfiltered list of all Events for this Calendar.
618
619 @param sortField specifies the EventSortField.
620 @param sortDirection specifies the SortDirection.
621
622 @return the list of all unfiltered Events sorted as specified.
623 */
624 virtual Event::List rawEvents(
625 EventSortField sortField = EventSortUnsorted,
626 SortDirection sortDirection = SortDirectionAscending ) = 0;
627
628 /**
629 Returns an unfiltered list of all Events which occur on the given
630 timestamp.
631
632 @param dt request unfiltered Event list for this KDateTime only.
633
634 @return the list of unfiltered Events occurring on the specified
635 timestamp.
636 */
637 virtual Event::List rawEventsForDate( const KDateTime &dt ) = 0;
638
639 /**
640 Returns an unfiltered list of all Events occurring within a date range.
641
642 @param start is the starting date
643 @param end is the ending date
644 @param timeSpec time zone etc. to interpret @p start and @p end,
645 or the calendar's default time spec if none is specified
646 @param inclusive if true only Events which are completely included
647 within the date range are returned.
648
649 @return the list of unfiltered Events occurring within the specified
650 date range.
651 */
652 virtual Event::List rawEvents( const QDate &start, const QDate &end,
653 const KDateTime::Spec &timeSpec = KDateTime::Spec(),
654 bool inclusive = false ) = 0;
655
656 /**
657 Returns a sorted, unfiltered list of all Events which occur on the given
658 date. The Events are sorted according to @a sortField and
659 @a sortDirection.
660
661 @param date request unfiltered Event list for this QDate only
662 @param timeSpec time zone etc. to interpret @p date,
663 or the calendar's default time spec if none is specified
664 @param sortField specifies the EventSortField
665 @param sortDirection specifies the SortDirection
666
667 @return the list of sorted, unfiltered Events occurring on @p date
668 */
669 virtual Event::List rawEventsForDate(
670 const QDate &date, const KDateTime::Spec &timeSpec = KDateTime::Spec(),
671 EventSortField sortField = EventSortUnsorted,
672 SortDirection sortDirection = SortDirectionAscending ) = 0;
673
674 /**
675 Returns the Event associated with the given unique identifier.
676
677 @param uid is a unique identifier string.
678
679 @return a pointer to the Event.
680 A null pointer is returned if no such Event exists.
681 */
682 virtual Event *event( const QString &uid ) = 0;
683
684 // Todo Specific Methods //
685
686 /**
687 Inserts a Todo into the calendar.
688
689 @param todo is a pointer to the Todo to insert.
690
691 @return true if the Todo was successfully inserted; false otherwise.
692
693 @see deleteTodo()
694 */
695 virtual bool addTodo( Todo *todo ) = 0;
696
697 /**
698 Removes a Todo from the calendar.
699
700 @param todo is a pointer to the Todo to remove.
701
702 @return true if the Todo was successfully removed; false otherwise.
703
704 @see addTodo(), deleteAllTodos()
705 */
706 virtual bool deleteTodo( Todo *todo ) = 0;
707
708 /**
709 Removes all To-dos from the calendar.
710 @see deleteTodo()
711 */
712 virtual void deleteAllTodos() = 0;
713
714 /**
715 Sort a list of Todos.
716
717 @param todoList is a pointer to a list of Todos.
718 @param sortField specifies the TodoSortField.
719 @param sortDirection specifies the SortDirection.
720
721 @return a list of Todos sorted as specified.
722 */
723 static Todo::List sortTodos( Todo::List *todoList,
724 TodoSortField sortField,
725 SortDirection sortDirection );
726
727 /**
728 Returns a sorted, filtered list of all Todos for this Calendar.
729
730 @param sortField specifies the TodoSortField.
731 @param sortDirection specifies the SortDirection.
732
733 @return the list of all filtered Todos sorted as specified.
734 */
735 virtual Todo::List todos(
736 TodoSortField sortField = TodoSortUnsorted,
737 SortDirection sortDirection = SortDirectionAscending );
738
739 /**
740 Returns a filtered list of all Todos which are due on the specified date.
741
742 @param date request filtered Todos due on this QDate.
743
744 @return the list of filtered Todos due on the specified date.
745 */
746 virtual Todo::List todos( const QDate &date );
747
748 /**
749 Returns a sorted, unfiltered list of all Todos for this Calendar.
750
751 @param sortField specifies the TodoSortField.
752 @param sortDirection specifies the SortDirection.
753
754 @return the list of all unfiltered Todos sorted as specified.
755 */
756 virtual Todo::List rawTodos(
757 TodoSortField sortField = TodoSortUnsorted,
758 SortDirection sortDirection = SortDirectionAscending ) = 0;
759
760 /**
761 Returns an unfiltered list of all Todos which due on the specified date.
762
763 @param date request unfiltered Todos due on this QDate.
764
765 @return the list of unfiltered Todos due on the specified date.
766 */
767 virtual Todo::List rawTodosForDate( const QDate &date ) = 0;
768
769 /**
770 Returns the Todo associated with the given unique identifier.
771
772 @param uid is a unique identifier string.
773
774 @return a pointer to the Todo.
775 A null pointer is returned if no such Todo exists.
776 */
777 virtual Todo *todo( const QString &uid ) = 0;
778
779 // Journal Specific Methods //
780
781 /**
782 Inserts a Journal into the calendar.
783
784 @param journal is a pointer to the Journal to insert.
785
786 @return true if the Journal was successfully inserted; false otherwise.
787
788 @see deleteJournal()
789 */
790 virtual bool addJournal( Journal *journal ) = 0;
791
792 /**
793 Removes a Journal from the calendar.
794
795 @param journal is a pointer to the Journal to remove.
796
797 @return true if the Journal was successfully removed; false otherwise.
798
799 @see addJournal(), deleteAllJournals()
800 */
801 virtual bool deleteJournal( Journal *journal ) = 0;
802
803 /**
804 Removes all Journals from the calendar.
805 @see deleteJournal()
806 */
807 virtual void deleteAllJournals() = 0;
808
809 /**
810 Sort a list of Journals.
811
812 @param journalList is a pointer to a list of Journals.
813 @param sortField specifies the JournalSortField.
814 @param sortDirection specifies the SortDirection.
815
816 @return a list of Journals sorted as specified.
817 */
818 static Journal::List sortJournals( Journal::List *journalList,
819 JournalSortField sortField,
820 SortDirection sortDirection );
821 /**
822 Returns a sorted, filtered list of all Journals for this Calendar.
823
824 @param sortField specifies the JournalSortField.
825 @param sortDirection specifies the SortDirection.
826
827 @return the list of all filtered Journals sorted as specified.
828 */
829 virtual Journal::List journals(
830 JournalSortField sortField = JournalSortUnsorted,
831 SortDirection sortDirection = SortDirectionAscending );
832
833 /**
834 Returns a filtered list of all Journals for on the specified date.
835
836 @param date request filtered Journals for this QDate only.
837
838 @return the list of filtered Journals for the specified date.
839 */
840 virtual Journal::List journals( const QDate &date );
841
842 /**
843 Returns a sorted, unfiltered list of all Journals for this Calendar.
844
845 @param sortField specifies the JournalSortField.
846 @param sortDirection specifies the SortDirection.
847
848 @return the list of all unfiltered Journals sorted as specified.
849 */
850 virtual Journal::List rawJournals(
851 JournalSortField sortField = JournalSortUnsorted,
852 SortDirection sortDirection = SortDirectionAscending ) = 0;
853
854 /**
855 Returns an unfiltered list of all Journals for on the specified date.
856
857 @param date request unfiltered Journals for this QDate only.
858
859 @return the list of unfiltered Journals for the specified date.
860 */
861 virtual Journal::List rawJournalsForDate( const QDate &date ) = 0;
862
863 /**
864 Returns the Journal associated with the given unique identifier.
865
866 @param uid is a unique identifier string.
867
868 @return a pointer to the Journal.
869 A null pointer is returned if no such Journal exists.
870 */
871 virtual Journal *journal( const QString &uid ) = 0;
872
873 /**
874 Emits the beginBatchAdding() signal.
875
876 This should be called before adding a batch of incidences with
877 addIncidence( Incidence *), addTodo( Todo *), addEvent( Event *)
878 or addJournal( Journal *). Some Calendars are connected to this
879 signal, e.g: CalendarResources uses it to know a series of
880 incidenceAdds are related so the user isn't prompted multiple
881 times which resource to save the incidence to
882
883 @since 4.4
884 */
885 void beginBatchAdding();
886
887 /**
888 Emits the endBatchAdding() signal.
889
890 Used with beginBatchAdding(). Should be called after
891 adding all incidences.
892
893 @since 4.4
894 */
895 void endBatchAdding();
896
897 // Relations Specific Methods //
898
899 /**
900 Setup Relations for an Incidence.
901
902 @param incidence is a pointer to the Incidence to have a
903 Relation setup.
904 */
905 virtual void setupRelations( Incidence *incidence );
906
907 /**
908 Removes all Relations from an Incidence.
909
910 @param incidence is a pointer to the Incidence to have a
911 Relation removed.
912 */
913 virtual void removeRelations( Incidence *incidence );
914
915 /**
916 Checks if @p ancestor is an ancestor of @p incidence
917
918 @param ancestor the incidence we are testing to be an ancestor
919 @param incidence the incidence we are testing to be descended from @p ancestor
920 */
921 bool isAncestorOf( Incidence *ancestor, Incidence *incidence );
922
923 // Filter Specific Methods //
924
925 /**
926 Sets the calendar filter.
927
928 @param filter a pointer to a CalFilter object which will be
929 used to filter Calendar Incidences. The Calendar takes
930 ownership of @p filter.
931
932 @see filter()
933 */
934 void setFilter( CalFilter *filter );
935
936 /**
937 Returns the calendar filter.
938
939 @return a pointer to the calendar CalFilter.
940 A null pointer is returned if no such CalFilter exists.
941
942 @see setFilter()
943 */
944 CalFilter *filter();
945
946 // Alarm Specific Methods //
947
948 /**
949 Returns a list of Alarms within a time range for this Calendar.
950
951 @param from is the starting timestamp.
952 @param to is the ending timestamp.
953
954 @return the list of Alarms for the for the specified time range.
955 */
956 virtual Alarm::List alarms( const KDateTime &from,
957 const KDateTime &to ) = 0;
958
959 // Observer Specific Methods //
960
961 /**
962 @class CalendarObserver
963
964 The CalendarObserver class.
965 */
966 class KCAL_DEPRECATED_EXPORT CalendarObserver //krazy:exclude=dpointer
967 {
968 public:
969 /**
970 Destructor.
971 */
972 virtual ~CalendarObserver() {}
973
974 /**
975 Notify the Observer that a Calendar has been modified.
976
977 @param modified set if the calendar has been modified.
978 @param calendar is a pointer to the Calendar object that
979 is being observed.
980 */
981 virtual void calendarModified( bool modified, Calendar *calendar );
982
983 /**
984 Notify the Observer that an Incidence has been inserted.
985
986 @param incidence is a pointer to the Incidence that was inserted.
987 */
988 virtual void calendarIncidenceAdded( Incidence *incidence );
989
990 /**
991 Notify the Observer that an Incidence has been modified.
992
993 @param incidence is a pointer to the Incidence that was modified.
994 */
995 virtual void calendarIncidenceChanged( Incidence *incidence );
996
997 /**
998 Notify the Observer that an Incidence has been removed.
999
1000 @param incidence is a pointer to the Incidence that was removed.
1001 */
1002 virtual void calendarIncidenceDeleted( Incidence *incidence );
1003 };
1004
1005 /**
1006 Registers an Observer for this Calendar.
1007
1008 @param observer is a pointer to an Observer object that will be
1009 watching this Calendar.
1010
1011 @see unregisterObserver()
1012 */
1013 void registerObserver( CalendarObserver *observer );
1014
1015 /**
1016 Unregisters an Observer for this Calendar.
1017
1018 @param observer is a pointer to an Observer object that has been
1019 watching this Calendar.
1020
1021 @see registerObserver()
1022 */
1023 void unregisterObserver( CalendarObserver *observer );
1024
1025 using QObject::event; // prevent warning about hidden virtual method
1026
1027 Q_SIGNALS:
1028 /**
1029 Signals that the calendar has been modified.
1030 */
1031 void calendarChanged();
1032
1033 /**
1034 Signals that the calendar has been saved.
1035 */
1036 void calendarSaved();
1037
1038 /**
1039 Signals that the calendar has been loaded into memory.
1040 */
1041 void calendarLoaded();
1042
1043 /**
1044 @see beginBatchAdding()
1045 @since 4.4
1046 */
1047 void batchAddingBegins();
1048
1049 /**
1050 @see endBatchAdding()
1051 @since 4.4
1052 */
1053 void batchAddingEnds();
1054
1055 protected:
1056 /**
1057 The Observer interface. So far not implemented.
1058
1059 @param incidenceBase is a pointer an IncidenceBase object.
1060 */
1061 void incidenceUpdated( IncidenceBase *incidenceBase );
1062
1063 /**
1064 Let Calendar subclasses set the time specification.
1065
1066 @param timeSpec is the time specification (time zone, etc.) for
1067 viewing Incidence dates.\n
1068 */
1069 virtual void doSetTimeSpec( const KDateTime::Spec &timeSpec );
1070
1071 /**
1072 Let Calendar subclasses notify that they inserted an Incidence.
1073
1074 @param incidence is a pointer to the Incidence object that was inserted.
1075 */
1076 void notifyIncidenceAdded( Incidence *incidence );
1077
1078 /**
1079 Let Calendar subclasses notify that they modified an Incidence.
1080
1081 @param incidence is a pointer to the Incidence object that was modified.
1082 */
1083 void notifyIncidenceChanged( Incidence *incidence );
1084
1085 /**
1086 Let Calendar subclasses notify that they removed an Incidence.
1087
1088 @param incidence is a pointer to the Incidence object that was removed.
1089 */
1090 void notifyIncidenceDeleted( Incidence *incidence );
1091
1092 /**
1093 @copydoc
1094 CustomProperties::customPropertyUpdated()
1095 */
1096 virtual void customPropertyUpdated();
1097
1098 /**
1099 Let Calendar subclasses notify that they enabled an Observer.
1100
1101 @param enabled if true tells the calendar that a subclass has
1102 enabled an Observer.
1103 */
1104 void setObserversEnabled( bool enabled );
1105
1106 /**
1107 Appends alarms of incidence in interval to list of alarms.
1108
1109 @param alarms is a List of Alarms to be appended onto.
1110 @param incidence is a pointer to an Incidence containing the Alarm
1111 to be appended.
1112 @param from is the lower range of the next Alarm repitition.
1113 @param to is the upper range of the next Alarm repitition.
1114 */
1115 void appendAlarms( Alarm::List &alarms, Incidence *incidence,
1116 const KDateTime &from, const KDateTime &to );
1117
1118 /**
1119 Appends alarms of recurring events in interval to list of alarms.
1120
1121 @param alarms is a List of Alarms to be appended onto.
1122 @param incidence is a pointer to an Incidence containing the Alarm
1123 to be appended.
1124 @param from is the lower range of the next Alarm repitition.
1125 @param to is the upper range of the next Alarm repitition.
1126 */
1127 void appendRecurringAlarms( Alarm::List &alarms, Incidence *incidence,
1128 const KDateTime &from, const KDateTime &to );
1129
1130 private:
1131 //@cond PRIVATE
1132 class Private;
1133 Private *const d;
1134 //@endcond
1135
1136 Q_DISABLE_COPY( Calendar )
1137};
1138
1139}
1140
1141#endif
1142