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 Cornelius Schumacher <schumacher@kde.org>
6 Copyright (c) 2002,2006 David Jarvie <software@astrojar.org.uk>
7 Copyright (C) 2005 Reinhold Kainhofer <reinhold@kainhofer.com>
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#ifndef KCAL_RECURRENCE_H
25#define KCAL_RECURRENCE_H
26
27#include "kcal_export.h"
28#include "recurrencerule.h"
29
30#include <kdatetime.h>
31
32#include <QtCore/QString>
33#include <QtCore/QBitArray>
34#include <QtCore/QList>
35
36namespace KCal {
37
38class RecurrenceRule;
39
40/**
41 This class represents a recurrence rule for a calendar incidence.
42
43 It manages all recurrence rules, recurrence date/times, exception rules
44 and exception date times that can appear inside calendar items.
45 Each recurrence rule and exception rule is represented as an object
46 of type RecurrenceRule.
47
48 For the simple case where at most one recurrence
49 rule is present, this class provides shortcut methods to set the type:
50 setMinutely()
51 setHourly()
52 setDaily()
53 setWeekly()
54 setMonthly()
55 setYearly()
56 to set/get general information about the recurrence:
57 setEndDate()
58 setEndDateTime()
59 duration()
60 durationTo()
61 setDuration()
62 frequency()
63 setFrequency()
64 and to set/get specific information about the recurrence within the interval:
65 days()
66 monthDays()
67 monthPositions()
68 yearDays()
69 yearDates()
70 yearMonths()
71 yearPositions()
72 addMonthlyPos()
73 addMonthlyDate()
74 addYearlyDay()
75 addYearlyDate()
76 addYearlyPos()
77 addYearlyMonth()
78 These are all available so that you don't have to work on the RecurrenceRule
79 objects themselves.
80 In other words, in that simple situation the interface stays almost the
81 same compared to the old Recurrence class, which allowed only one
82 recurrence rule.
83
84 As soon as your recurrence consists of multiple recurrence rules or exception
85 rules, you cannot use the methods mentioned above any more (since each rule
86 will have a different type and different settings). If you still call
87 any of them, the set*ly methods will remove all rules and add one rule with
88 the specified type. The add* and the other set* methods will change only
89 the first recurrence rule, but leave the others untouched.
90*/
91class KCAL_DEPRECATED_EXPORT Recurrence : public RecurrenceRule::RuleObserver
92{
93 public:
94 class RecurrenceObserver
95 {
96 public:
97 virtual ~RecurrenceObserver() {}
98 /** This method will be called on each change of the recurrence object */
99 virtual void recurrenceUpdated( Recurrence *r ) = 0;
100 };
101
102 /** enumeration for describing how an event recurs, if at all. */
103 enum {
104 rNone = 0,
105 rMinutely = 0x001,
106 rHourly = 0x0002,
107 rDaily = 0x0003,
108 rWeekly = 0x0004,
109 rMonthlyPos = 0x0005,
110 rMonthlyDay = 0x0006,
111 rYearlyMonth = 0x0007,
112 rYearlyDay = 0x0008,
113 rYearlyPos = 0x0009,
114 rOther = 0x000A,
115 rMax=0x00FF
116 };
117
118 /**
119 * Constructs an empty recurrence.
120 */
121 Recurrence();
122 /**
123 * Copy constructor.
124 *
125 * @param r instance to copy from
126 */
127 Recurrence( const Recurrence &r );
128 /**
129 * Destructor.
130 */
131 virtual ~Recurrence();
132
133 /**
134 * Comparison operator for equality.
135 *
136 * @param r instance to compare with
137 * @return true if recurrences are the same, false otherwise
138 */
139 bool operator==( const Recurrence &r ) const;
140 /**
141 * Comparison operator for inequality.
142 *
143 * @param r instance to compare with
144 * @return true if recurrences are the different, false if the same
145 */
146 bool operator!=( const Recurrence &r ) const { return !operator==(r); }
147
148 /**
149 * Assignment operator.
150 *
151 * @param r the recurrence which will be assigned to this.
152 & @since 4.5
153 */
154 Recurrence &operator=( const Recurrence &r );
155
156 /** Return the start date/time of the recurrence (Time for all-day recurrences will be 0:00).
157 @return the current start/time of the recurrence. */
158 KDateTime startDateTime() const;
159 /** Return the start date/time of the recurrence */
160 QDate startDate() const;
161 /** Set start of recurrence.
162 If @p start is date-only, the recurrence is set to all-day. Otherwise, the
163 start is set to a date and time, and the recurrence is set to non-all-day.
164 @param start the new start date or date/time of the recurrence.
165 */
166 void setStartDateTime( const KDateTime &start );
167
168 /** Set whether the recurrence has no time, just a date.
169 * All-day means -- according to rfc2445 -- that the event has no time
170 * associated.
171 * N.B. This property is derived by default from whether setStartDateTime() is
172 * called with a date-only or date/time parameter.
173 * @return whether the recurrence has a time (false) or it is just a date (true). */
174 bool allDay() const;
175 /** Sets whether the dtstart is a all-day (i.e. has no time attached)
176 @param allDay If the recurrence is for all-day item (true) or has a time associated (false).
177 */
178 void setAllDay( bool allDay );
179
180 /** Set if recurrence is read-only or can be changed. */
181 void setRecurReadOnly( bool readOnly );
182
183 /** Returns true if the recurrence is read-only, or false if it can be changed. */
184 bool recurReadOnly() const;
185
186 /** Returns whether the event recurs at all. */
187 bool recurs() const;
188
189 /** Returns the event's recurrence status. See the enumeration at the top
190 * of this file for possible values. */
191 ushort recurrenceType() const;
192
193 /** Returns the recurrence status for a recurrence rule.
194 * See the enumeration at the top of this file for possible values.
195 *
196 * @param rrule the recurrence rule to get the type for
197 */
198 static ushort recurrenceType( const RecurrenceRule *rrule );
199
200 /**
201 Returns true if the date specified is one on which the event will recur.
202
203 @param date date to check.
204 @param timeSpec time specification for @p date.
205 */
206 bool recursOn( const QDate &date, const KDateTime::Spec &timeSpec ) const;
207
208 /**
209 Returns true if the date/time specified is one at which the event will
210 recur. Times are rounded down to the nearest minute to determine the
211 result.
212
213 @param dt is the date/time to check.
214 */
215 bool recursAt( const KDateTime &dt ) const;
216
217 /**
218 Removes all recurrence rules. Recurrence dates and exceptions are
219 not removed.
220 */
221 void unsetRecurs();
222
223 /**
224 Removes all recurrence and exception rules and dates.
225 */
226 void clear();
227
228 /** Returns a list of the times on the specified date at which the
229 * recurrence will occur. The returned times should be interpreted in the
230 * context of @p timeSpec.
231 * @param date the date for which to find the recurrence times
232 * @param timeSpec time specification for @p date
233 */
234 TimeList recurTimesOn( const QDate &date, const KDateTime::Spec &timeSpec ) const;
235
236 /** Returns a list of all the times at which the recurrence will occur
237 * between two specified times.
238 *
239 * There is a (large) maximum limit to the number of times returned. If due to
240 * this limit the list is incomplete, this is indicated by the last entry being
241 * set to an invalid KDateTime value. If you need further values, call the
242 * method again with a start time set to just after the last valid time returned.
243 *
244 * @param start inclusive start of interval
245 * @param end inclusive end of interval
246 * @return list of date/time values
247 */
248 DateTimeList timesInInterval( const KDateTime &start, const KDateTime &end ) const;
249
250 /** Returns the date and time of the next recurrence, after the specified date/time.
251 * If the recurrence has no time, the next date after the specified date is returned.
252 * @param preDateTime the date/time after which to find the recurrence.
253 * @return date/time of next recurrence (strictly later than the given
254 * KDateTime), or invalid date if none.
255 */
256 KDateTime getNextDateTime( const KDateTime &preDateTime ) const;
257
258 /** Returns the date and time of the last previous recurrence, before the specified date/time.
259 * If a time later than 00:00:00 is specified and the recurrence has no time, 00:00:00 on
260 * the specified date is returned if that date recurs.
261 *
262 * @param afterDateTime the date/time before which to find the recurrence.
263 * @return date/time of previous recurrence (strictly earlier than the given
264 * KDateTime), or invalid date if none.
265 */
266 KDateTime getPreviousDateTime( const KDateTime &afterDateTime ) const;
267
268 /** Returns frequency of recurrence, in terms of the recurrence time period type. */
269 int frequency() const;
270
271 /** Sets the frequency of recurrence, in terms of the recurrence time period type. */
272 void setFrequency( int freq );
273
274 /**
275 * Returns -1 if the event recurs infinitely, 0 if the end date is set,
276 * otherwise the total number of recurrences, including the initial occurrence.
277 */
278 int duration() const;
279
280 /** Sets the total number of times the event is to occur, including both the
281 * first and last. */
282 void setDuration( int duration );
283
284 /** Returns the number of recurrences up to and including the date/time specified.
285 * @warning This function can be very time consuming - use it sparingly!
286 */
287 int durationTo( const KDateTime &dt ) const;
288
289 /** Returns the number of recurrences up to and including the date specified.
290 * @warning This function can be very time consuming - use it sparingly!
291 */
292 int durationTo( const QDate &date ) const;
293
294 /** Returns the date/time of the last recurrence.
295 * An invalid date is returned if the recurrence has no end.
296 */
297 KDateTime endDateTime() const;
298
299 /** Returns the date of the last recurrence.
300 * An invalid date is returned if the recurrence has no end.
301 */
302 QDate endDate() const;
303
304 /** Sets the date of the last recurrence. The end time is set to the recurrence start time.
305 * @param endDate the ending date after which to stop recurring. If the
306 * recurrence is not all-day, the end time will be 23:59.*/
307 void setEndDate( const QDate &endDate );
308
309 /** Sets the date and time of the last recurrence.
310 * @param endDateTime the ending date/time after which to stop recurring. */
311 void setEndDateTime( const KDateTime &endDateTime );
312
313 /**
314 Shift the times of the recurrence so that they appear at the same clock
315 time as before but in a new time zone. The shift is done from a viewing
316 time zone rather than from the actual recurrence time zone.
317
318 For example, shifting a recurrence whose start time is 09:00 America/New York,
319 using an old viewing time zone (@p oldSpec) of Europe/London, to a new time
320 zone (@p newSpec) of Europe/Paris, will result in the time being shifted
321 from 14:00 (which is the London time of the recurrence start) to 14:00 Paris
322 time.
323
324 @param oldSpec the time specification which provides the clock times
325 @param newSpec the new time specification
326 */
327 void shiftTimes( const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec );
328
329 /** Sets an event to recur minutely. By default infinite recurrence is used.
330 To set an end date use the method setEndDate and to set the number
331 of occurrences use setDuration.
332
333 This method clears all recurrence rules and adds one rule with a
334 minutely recurrence. All other recurrence components (recurrence
335 date/times, exception date/times and exception rules) are not
336 modified.
337 * @param freq the frequency to recur, e.g. 2 is every other minute
338 */
339 void setMinutely( int freq );
340
341 /** Sets an event to recur hourly. By default infinite recurrence is used.
342 The minute of the recurrence is taken from the start date (if you
343 need to change it, you will have to modify the defaultRRule's
344 byMinute list manually.
345 To set an end date use the method setEndDate and to set the number
346 of occurrences use setDuration.
347
348 This method clears all recurrence rules and adds one rule with a
349 hourly recurrence. All other recurrence components (recurrence
350 date/times, exception date/times and exception rules) are not
351 modified.
352 * @param freq the frequency to recur, e.g. 2 is every other hour
353 */
354 void setHourly( int freq );
355
356 /** Sets an event to recur daily. By default infinite recurrence is used.
357 The minute and second of the recurrence is taken from the start date
358 (if you need to change them, you will have to modify the defaultRRule's
359 byMinute list manually.
360 To set an end date use the method setEndDate and to set the number
361 of occurrences use setDuration.
362
363 This method clears all recurrence rules and adds one rule with a
364 daily recurrence. All other recurrence components (recurrence
365 date/times, exception date/times and exception rules) are not
366 modified.
367 * @param freq the frequency to recur, e.g. 2 is every other day
368 */
369 void setDaily( int freq );
370
371 /** Sets an event to recur weekly. By default infinite recurrence is used.
372 To set an end date use the method setEndDate and to set the number
373 of occurrences use setDuration.
374
375 This method clears all recurrence rules and adds one rule with a
376 weekly recurrence. All other recurrence components (recurrence
377 date/times, exception date/times and exception rules) are not
378 modified.
379 * @param freq the frequency to recur, e.g. every other week etc.
380 * @param weekStart the first day of the week (Monday=1 .. Sunday=7, default is Monday).
381 */
382 void setWeekly( int freq, int weekStart = 1 );
383 /** Sets an event to recur weekly. By default infinite recurrence is used.
384 To set an end date use the method setEndDate and to set the number
385 of occurrences use setDuration.
386
387 This method clears all recurrence rules and adds one rule with a
388 weekly recurrence. All other recurrence components (recurrence
389 date/times, exception date/times and exception rules) are not
390 modified.
391 * @param freq the frequency to recur, e.g. every other week etc.
392 * @param days a 7 bit array indicating which days on which to recur (bit 0 = Monday).
393 * @param weekStart the first day of the week (Monday=1 .. Sunday=7, default is Monday).
394 */
395 void setWeekly( int freq, const QBitArray &days, int weekStart = 1 );
396
397 /** Adds days to the weekly day recurrence list.
398 * @param days a 7 bit array indicating which days on which to recur (bit 0 = Monday).
399 */
400 void addWeeklyDays( const QBitArray &days );
401 /** Returns the first day of the week. Uses only the
402 * first RRULE if present (i.e. a second RRULE as well as all EXRULES are
403 * ignored!
404 * @return Weekday of the first day of the week (Monday=1 .. Sunday=7)
405 */
406 int weekStart() const;
407
408 /** Returns week day mask (bit 0 = Monday). */
409 QBitArray days() const; // Emulate the old behavior
410
411 /** Sets an event to recur monthly. By default infinite recurrence is used.
412 The date of the monthly recurrence will be taken from the start date
413 unless you explicitly add one or more recurrence dates with
414 addMonthlyDate or a recurrence position in the month (e.g. first
415 monday) using addMonthlyPos.
416 To set an end date use the method setEndDate and to set the number
417 of occurrences use setDuration.
418
419 This method clears all recurrence rules and adds one rule with a
420 monthly recurrence. All other recurrence components (recurrence
421 date/times, exception date/times and exception rules) are not
422 modified.
423 * @param freq the frequency to recur, e.g. 3 for every third month.
424 */
425 void setMonthly( int freq );
426
427 /** Adds a position (e.g. first monday) to the monthly recurrence rule.
428 * @param pos the position in the month for the recurrence, with valid
429 * values being 1-5 (5 weeks max in a month).
430 * @param days the days for the position to recur on (bit 0 = Monday).
431 * Example: pos = 2, and bits 0 and 2 are set in days:
432 * the rule is to repeat every 2nd Monday and Wednesday in the month.
433 */
434 void addMonthlyPos( short pos, const QBitArray &days );
435 void addMonthlyPos( short pos, ushort day );
436
437 /** Adds a date (e.g. the 15th of each month) to the monthly day
438 * recurrence list.
439 * @param day the date in the month to recur.
440 */
441 void addMonthlyDate( short day );
442
443 /** Returns list of day positions in months. */
444 QList<RecurrenceRule::WDayPos> monthPositions() const;
445
446 /** Returns list of day numbers of a month. */
447 // Emulate old behavior
448 QList<int> monthDays() const;
449
450 /** Sets an event to recur yearly. By default, this will recur every year
451 * on the same date (e.g. every year on April 15 if the start date was
452 * April 15).
453 * The day of the year can be specified with addYearlyDay().
454 * The day of the month can be specified with addYearlyByDate
455 * If both a month and a day ar specified with addYearlyMonth and
456 * addYearlyDay, the day is understood as day number within the month.
457 *
458 * A position (e.g. 3rd Sunday of year/month, or last Friday of year/month)
459 * can be specified with addYearlyPos. Again, if a month is specified,
460 * this position is understood as within that month, otherwise within
461 * the year.
462 *
463 * By default infinite recurrence is used. To set an end date use the
464 * method setEndDate and to set the number of occurrences use setDuration.
465
466 This method clears all recurrence rules and adds one rule with a
467 yearly recurrence. All other recurrence components (recurrence
468 date/times, exception date/times and exception rules) are not
469 modified.
470 * @param freq the frequency to recur, e.g. 3 for every third year.
471 */
472 void setYearly( int freq );
473
474 /** Adds day number of year within a yearly recurrence.
475 * By default infinite recurrence is used. To set an end date use the
476 * method setEndDate and to set the number of occurrences use setDuration.
477 * @param day the day of the year for the event. E.g. if day is 60, this
478 * means Feb 29 in leap years and March 1 in non-leap years.
479 */
480 void addYearlyDay( int day );
481
482 /** Adds date within a yearly recurrence. The month(s) for the recurrence
483 * can be specified with addYearlyMonth(), otherwise the month of the
484 * start date is used.
485 *
486 * By default infinite recurrence is used. To set an end date use the
487 * method setEndDate and to set the number of occurrences use setDuration.
488 * @param date the day of the month for the event
489 */
490 void addYearlyDate( int date );
491
492 /** Adds month in yearly recurrence. You can specify specific day numbers
493 * within the months (by calling addYearlyDate()) or specific day positions
494 * within the month (by calling addYearlyPos).
495 * @param _rNum the month in which the event shall recur.
496 */
497 void addYearlyMonth( short _rNum );
498
499 /** Adds position within month/year within a yearly recurrence. If months
500 * are specified (via addYearlyMonth()), the parameters are understood as
501 * position within these months, otherwise within the year.
502 *
503 * By default infinite recurrence is used.
504 * To set an end date use the method setEndDate and to set the number
505 * of occurrences use setDuration.
506 * @param pos the position in the month/year for the recurrence, with valid
507 * values being 1 to 53 and -1 to -53 (53 weeks max in a year).
508 * @param days the days for the position to recur on (bit 0 = Monday).
509 * Example: pos = 2, and bits 0 and 2 are set in days
510 * If months are specified (via addYearlyMonth), e.g. March, the rule is
511 * to repeat every year on the 2nd Monday and Wednesday of March.
512 * If no months are specified, the fule is to repeat every year on the
513 * 2nd Monday and Wednesday of the year.
514 */
515 void addYearlyPos( short pos, const QBitArray &days );
516
517 /** Returns the day numbers within a yearly recurrence.
518 * @return the days of the year for the event. E.g. if the list contains
519 * 60, this means the recurrence happens on day 60 of the year, i.e.
520 * on Feb 29 in leap years and March 1 in non-leap years.
521 */
522 QList<int> yearDays() const;
523
524 /** Returns the dates within a yearly recurrence.
525 * @return the days of the month for the event. E.g. if the list contains
526 * 13, this means the recurrence happens on the 13th of the month.
527 * The months for the recurrence can be obtained through
528 * yearlyMonths(). If this list is empty, the month of the start
529 * date is used.
530 */
531 QList<int> yearDates() const;
532
533 /** Returns the months within a yearly recurrence.
534 * @return the months for the event. E.g. if the list contains
535 * 11, this means the recurrence happens in November.
536 * The days for the recurrence can be obtained either through
537 * yearDates() if they are given as dates within the month or
538 * through yearlyPositions() if they are given as positions within the
539 * month. If none is specified, the date of the start date is used.
540 */
541 QList<int> yearMonths() const;
542
543 /** Returns the positions within a yearly recurrence.
544 * @return the positions for the event, either within a month (if months
545 * are set through addYearlyMonth()) or within the year.
546 * E.g. if the list contains {Pos=3, Day=5}, this means the third
547 * friday. If a month is set this position is understoodas third
548 * Friday in the given months, otherwise as third Friday of the
549 * year.
550 */
551 /** Returns list of day positions in months, for a recursYearlyPos recurrence rule. */
552 QList<RecurrenceRule::WDayPos> yearPositions() const;
553
554 /** Upper date limit for recurrences */
555 static const QDate MAX_DATE;
556
557 /**
558 Debug output.
559 */
560 void dump() const;
561
562 // RRULE
563 RecurrenceRule::List rRules() const;
564 /**
565 Add a recurrence rule to the recurrence.
566 @param rrule the recurrence rule to add
567 */
568 void addRRule( RecurrenceRule *rrule );
569
570 /**
571 Remove a recurrence rule from the recurrence.
572 @p rrule is not deleted; it is the responsibility of the caller
573 to ensure that it is deleted.
574 @param rrule the recurrence rule to remove
575 */
576 void removeRRule( RecurrenceRule *rrule );
577
578 /**
579 Remove a recurrence rule from the recurrence and delete it.
580 @param rrule the recurrence rule to remove
581 */
582 void deleteRRule( RecurrenceRule *rrule );
583
584 // EXRULE
585 RecurrenceRule::List exRules() const;
586
587 /**
588 Add an exception rule to the recurrence.
589 @param exrule the exception rule to add
590 */
591 void addExRule( RecurrenceRule *exrule );
592
593 /**
594 Remove an exception rule from the recurrence.
595 @p exrule is not deleted; it is the responsibility of the caller
596 to ensure that it is deleted.
597 @param exrule the exception rule to remove
598 */
599 void removeExRule( RecurrenceRule *exrule );
600
601 /**
602 Remove an exception rule from the recurrence and delete it.
603 @param exrule the exception rule to remove
604 */
605 void deleteExRule( RecurrenceRule *exrule );
606
607 // RDATE
608 DateTimeList rDateTimes() const;
609 DateList rDates() const;
610 void setRDateTimes( const DateTimeList &rdates );
611 void setRDates( const DateList &rdates );
612 void addRDateTime( const KDateTime &rdate );
613 void addRDate( const QDate &rdate );
614
615 // ExDATE
616 DateTimeList exDateTimes() const;
617 DateList exDates() const;
618 void setExDateTimes( const DateTimeList &exdates );
619 void setExDates( const DateList &exdates );
620 void addExDateTime( const KDateTime &exdate );
621 void addExDate( const QDate &exdate );
622
623 RecurrenceRule *defaultRRule( bool create = false ) const;
624 RecurrenceRule *defaultRRuleConst() const;
625 void updated();
626
627 /**
628 Installs an observer. Whenever some setting of this recurrence
629 object is changed, the recurrenceUpdated( Recurrence* ) method
630 of each observer will be called to inform it of changes.
631 @param observer the Recurrence::Observer-derived object, which
632 will be installed as an observer of this object.
633 */
634 void addObserver( RecurrenceObserver *observer );
635 /**
636 Removes an observer that was added with addObserver. If the
637 given object was not an observer, it does nothing.
638 @param observer the Recurrence::Observer-derived object to
639 be removed from the list of observers of this object.
640 */
641 void removeObserver( RecurrenceObserver *observer );
642
643 void recurrenceChanged( RecurrenceRule * );
644
645 protected:
646 RecurrenceRule *setNewRecurrenceType( RecurrenceRule::PeriodType type, int freq );
647
648 private:
649 //@cond PRIVATE
650 class Private;
651 Private *const d;
652 //@endcond
653};
654
655}
656
657#endif
658