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 | |
51 | namespace KCal { |
52 | |
53 | class ICalTimeZone; |
54 | class ICalTimeZones; |
55 | class CalFilter; |
56 | class Person; |
57 | |
58 | /** |
59 | Calendar Incidence sort directions. |
60 | */ |
61 | enum 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 | */ |
69 | enum 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 | */ |
79 | enum 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 | */ |
91 | enum 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 | */ |
119 | class 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 | |