libkcal

#include <recurrence.h>

Inherits KCal::RecurrenceRule::Observer.

Public Types

enum  {
  rNone = 0 , rMinutely = 0x001 , rHourly = 0x0002 , rDaily = 0x0003 ,
  rWeekly = 0x0004 , rMonthlyPos = 0x0005 , rMonthlyDay = 0x0006 , rYearlyMonth = 0x0007 ,
  rYearlyDay = 0x0008 , rYearlyPos = 0x0009 , rOther = 0x000A , rMax =0x00FF
}
 

Public Member Functions

 Recurrence (const Recurrence &)
 
bool operator== (const Recurrence &) const
 
bool operator!= (const Recurrence &r) const
 
TQDateTime startDateTime () const
 
TQDate startDate () const
 
void setStartDateTime (const TQDateTime &start)
 
void setStartDate (const TQDate &start)
 
bool doesFloat () const
 
void setFloats (bool floats)
 
void setRecurReadOnly (bool readOnly)
 
bool recurReadOnly () const
 
bool doesRecur () const
 
ushort recurrenceType () const
 
bool recursOn (const TQDate &qd) const
 
bool recursAt (const TQDateTime &) const
 
void unsetRecurs ()
 
void clear ()
 
TQValueList< TQTime > recurTimesOn (const TQDate &date) const
 
DateTimeList timesInInterval (const TQDateTime &start, const TQDateTime &end) const
 
TQDateTime getNextDateTime (const TQDateTime &preDateTime) const
 
TQDateTime getPreviousDateTime (const TQDateTime &afterDateTime) const
 
int frequency () const
 
void setFrequency (int freq)
 
int duration () const
 
void setDuration (int duration)
 
int durationTo (const TQDateTime &) const
 
int durationTo (const TQDate &date) const
 
TQDateTime endDateTime () const
 
TQDate endDate () const
 
void setEndDate (const TQDate &endDate)
 
void setEndDateTime (const TQDateTime &endDateTime)
 
void setMinutely (int freq)
 
void setHourly (int freq)
 
void setDaily (int freq)
 
void setWeekly (int freq, int weekStart=1)
 
void setWeekly (int freq, const TQBitArray &days, int weekStart=1)
 
void addWeeklyDays (const TQBitArray &days)
 
int weekStart () const
 
TQBitArray days () const
 
void setMonthly (int freq)
 
void addMonthlyPos (short pos, const TQBitArray &days)
 
void addMonthlyPos (short pos, ushort day)
 
void addMonthlyDate (short day)
 
TQValueList< RecurrenceRule::WDayPosmonthPositions () const
 
TQValueList< int > monthDays () const
 
void setYearly (int freq)
 
void addYearlyDay (int day)
 
void addYearlyDate (int date)
 
void addYearlyMonth (short _rNum)
 
void addYearlyPos (short pos, const TQBitArray &days)
 
TQValueList< int > yearDays () const
 
TQValueList< int > yearDates () const
 
TQValueList< int > yearMonths () const
 
TQValueList< RecurrenceRule::WDayPosyearPositions () const
 
void dump () const
 
RecurrenceRule::List rRules () const
 
void addRRule (RecurrenceRule *rrule)
 
void removeRRule (RecurrenceRule *rrule)
 
RecurrenceRule::List exRules () const
 
void addExRule (RecurrenceRule *exrule)
 
void removeExRule (RecurrenceRule *exrule)
 
DateTimeList rDateTimes () const
 
DateList rDates () const
 
void setRDateTimes (const DateTimeList &rdates)
 
void setRDates (const DateList &rdates)
 
void addRDateTime (const TQDateTime &rdate)
 
void addRDate (const TQDate &rdate)
 
DateTimeList exDateTimes () const
 
DateList exDates () const
 
void setExDateTimes (const DateTimeList &exdates)
 
void setExDates (const DateList &exdates)
 
void addExDateTime (const TQDateTime &exdate)
 
void addExDate (const TQDate &exdate)
 
RecurrenceRuledefaultRRule (bool create=false) const
 
RecurrenceRuledefaultRRuleConst () const
 
void updated ()
 
void addObserver (Observer *observer)
 
void removeObserver (Observer *observer)
 
void recurrenceChanged (RecurrenceRule *)
 

Static Public Member Functions

static ushort recurrenceType (const RecurrenceRule *rrule)
 

Static Public Attributes

static const TQDate MAX_DATE
 

Protected Member Functions

RecurrenceRulesetNewRecurrenceType (RecurrenceRule::PeriodType type, int freq)
 

Detailed Description

This class represents a recurrence rule for a calendar incidence.

It manages all recurrence rules, recurrence date/times, exception rules and exception date times that can appear inside calendar items. Each recurrence rule and exception rule is represented as an object of type RecurrenceRule.

For the simple case where at most one recurrence rule is present, this class provides shortcut methods to set the type: setMinutely() setHourly() setDaily() setWeekly() setMonthly() setYearly() to set/get general information about the recurrence: setEndDate() setEndDateTime() duration() durationTo() setDuration() frequency() setFrequency() and to set/get specific information about the recurrence within the interval: days() monthDays() monthPositions() yearDays() yearDates() yearMonths() yearPositions() addMonthlyPos() addMonthlyDate() addYearlyDay() addYearlyDate() addYearlyPos() addYearlyMonth() These are all available so that you don't have to work on the RecurrenceRule objects themselves. In other words, in that simple situation the interface stays almost the same compared to the old Recurrence class, which allowed only one recurrence rule.

As soon as your recurrence consists of multiple recurrence rules or exception rules, you cannot use the methods mentioned above any more (since each rule will have a different type and different settings). If you still call any of them, the set*ly methods will remove all rules and add one rule with the specified type. The add* and the other set* methods will change only the first recurrence rule, but leave the others untouched.

Definition at line 89 of file recurrence.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

enumeration for describing how an event recurs, if at all.

Definition at line 100 of file recurrence.h.

Member Function Documentation

◆ addMonthlyDate()

void Recurrence::addMonthlyDate ( short  day)

Adds a date (e.g.

the 15th of each month) to the monthly day recurrence list.

Parameters
daythe date in the month to recur.

Definition at line 657 of file recurrence.cpp.

◆ addMonthlyPos()

void Recurrence::addMonthlyPos ( short  pos,
const TQBitArray &  days 
)

Adds a position (e.g.

first monday) to the monthly recurrence rule.

Parameters
posthe position in the month for the recurrence, with valid values being 1-5 (5 weeks max in a month).
daysthe days for the position to recur on (bit 0 = Monday). Example: pos = 2, and bits 0 and 2 are set in days: the rule is to repeat every 2nd Monday and Wednesday in the month.

Definition at line 615 of file recurrence.cpp.

◆ addObserver()

void Recurrence::addObserver ( Observer *  observer)

Installs an observer.

Whenever some setting of this recurrence object is changed, the recurrenceUpdated( Recurrence* ) method of each observer will be called to inform it of changes.

Parameters
observerthe Recurrence::Observer-derived object, which will be installed as an observer of this object.

Definition at line 113 of file recurrence.cpp.

◆ addWeeklyDays()

void Recurrence::addWeeklyDays ( const TQBitArray &  days)

Adds days to the weekly day recurrence list.

Parameters
daysa 7 bit array indicating which days on which to recur (bit 0 = Monday).

Definition at line 604 of file recurrence.cpp.

◆ addYearlyDate()

void Recurrence::addYearlyDate ( int  date)

Adds date within a yearly recurrence.

The month(s) for the recurrence can be specified with addYearlyMonth(), otherwise the month of the start date is used.

By default infinite recurrence is used. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

Parameters
datethe day of the month for the event

Definition at line 693 of file recurrence.cpp.

◆ addYearlyDay()

void Recurrence::addYearlyDay ( int  day)

Adds day number of year within a yearly recurrence.

By default infinite recurrence is used. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

Parameters
daythe day of the year for the event. E.g. if day is 60, this means Feb 29 in leap years and March 1 in non-leap years.

Definition at line 679 of file recurrence.cpp.

◆ addYearlyMonth()

void Recurrence::addYearlyMonth ( short  _rNum)

Adds month in yearly recurrence.

You can specify specific day numbers within the months (by calling addYearlyDate()) or specific day positions within the month (by calling addYearlyPos).

Parameters
_rNumthe month in which the event shall recur.

Definition at line 706 of file recurrence.cpp.

◆ addYearlyPos()

void Recurrence::addYearlyPos ( short  pos,
const TQBitArray &  days 
)

Adds position within month/year within a yearly recurrence.

If months are specified (via addYearlyMonth()), the parameters are understood as position within these months, otherwise within the year.

By default infinite recurrence is used. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

Parameters
posthe position in the month/year for the recurrence, with valid values being 1 to 53 and -1 to -53 (53 weeks max in a year).
daysthe days for the position to recur on (bit 0 = Monday). Example: pos = 2, and bits 0 and 2 are set in days If months are specified (via addYearlyMonth), e.g. March, the rule is to repeat every year on the 2nd Monday and Wednesday of March. If no months are specified, the fule is to repeat every year on the 2nd Monday and Wednesday of the year.

Definition at line 699 of file recurrence.cpp.

◆ clear()

void Recurrence::clear ( )

Removes all recurrence and exception rules and dates.

Definition at line 431 of file recurrence.cpp.

◆ days()

TQBitArray Recurrence::days ( ) const

Returns week day mask (bit 0 = Monday).

Definition at line 494 of file recurrence.cpp.

◆ doesFloat()

bool KCal::Recurrence::doesFloat ( ) const
inline

Set whether the recurrence has no time, just a date.

Floating means – according to rfc2445 – that the event has no time associated. N.B. This property is derived by default from whether setStartDateTime() or setStartDate() is called.

Returns
whether the recurrence has a time (false) or it is just a date (true).

Definition at line 132 of file recurrence.h.

◆ doesRecur()

bool Recurrence::doesRecur ( ) const

Returns whether the event recurs at all.

Definition at line 184 of file recurrence.cpp.

◆ dump()

void Recurrence::dump ( ) const

Debug output.

Definition at line 1126 of file recurrence.cpp.

◆ duration()

int Recurrence::duration ( ) const

Returns -1 if the event recurs infinitely, 0 if the end date is set, otherwise the total number of recurrences, including the initial occurrence.

Definition at line 395 of file recurrence.cpp.

◆ durationTo() [1/2]

int KCal::Recurrence::durationTo ( const TQDate &  date) const
inline

Returns the number of recurrences up to and including the date specified.

Definition at line 214 of file recurrence.h.

◆ durationTo() [2/2]

int Recurrence::durationTo ( const TQDateTime &  datetime) const

Returns the number of recurrences up to and including the date/time specified.

Definition at line 407 of file recurrence.cpp.

◆ endDate()

TQDate Recurrence::endDate ( ) const

Returns the date of the last recurrence.

Calculates the cumulative end of the whole recurrence (rdates and rrules).

An invalid date is returned if the recurrence has no end.

If any rrule is infinite, or the recurrence doesn't have any rrules or rdates, an invalid date is returned.

Definition at line 371 of file recurrence.cpp.

◆ endDateTime()

TQDateTime Recurrence::endDateTime ( ) const

Returns the date/time of the last recurrence.

Calculates the cumulative end of the whole recurrence (rdates and rrules).

An invalid date is returned if the recurrence has no end.

If any rrule is infinite, or the recurrence doesn't have any rrules or rdates, an invalid date is returned.

Definition at line 351 of file recurrence.cpp.

◆ frequency()

int Recurrence::frequency ( ) const

Returns frequency of recurrence, in terms of the recurrence time period type.

Definition at line 465 of file recurrence.cpp.

◆ getNextDateTime()

TQDateTime Recurrence::getNextDateTime ( const TQDateTime &  preDateTime) const

Returns the date and time of the next recurrence, after the specified date/time.

If the recurrence has no time, the next date after the specified date is returned.

Parameters
preDateTimethe date/time after which to find the recurrence.
Returns
date/time of next recurrence (strictly later than the given TQDateTiem), or invalid date if none.

Definition at line 837 of file recurrence.cpp.

◆ getPreviousDateTime()

TQDateTime Recurrence::getPreviousDateTime ( const TQDateTime &  afterDateTime) const

Returns the date and time of the last previous recurrence, before the specified date/time.

If a time later than 00:00:00 is specified and the recurrence has no time, 00:00:00 on the specified date is returned if that date recurs.

Parameters
afterDateTimethe date/time before which to find the recurrence.
Returns
date/time of previous recurrence (strictly earlier than the given TQDateTime), or invalid date if none.

Definition at line 912 of file recurrence.cpp.

◆ monthDays()

TQValueList< int > Recurrence::monthDays ( ) const

Returns list of day numbers of a month.

Definition at line 515 of file recurrence.cpp.

◆ monthPositions()

TQValueList< RecurrenceRule::WDayPos > Recurrence::monthPositions ( ) const

Returns list of day positions in months.

Definition at line 523 of file recurrence.cpp.

◆ recurReadOnly()

bool KCal::Recurrence::recurReadOnly ( ) const
inline

Returns true if the recurrence is read-only, or false if it can be changed.

Definition at line 141 of file recurrence.h.

◆ recurrenceType() [1/2]

ushort Recurrence::recurrenceType ( ) const

Returns the event's recurrence status.

See the enumeration at the top of this file for possible values.

Definition at line 189 of file recurrence.cpp.

◆ recurrenceType() [2/2]

ushort Recurrence::recurrenceType ( const RecurrenceRule rrule)
static

Returns the recurrence status for a recurrence rule.

See the enumeration at the top of this file for possible values.

Definition at line 197 of file recurrence.cpp.

◆ recursAt()

bool Recurrence::recursAt ( const TQDateTime &  dt) const

Returns true if the date/time specified is one at which the event will recur.

Times are rounded down to the nearest minute to determine the result.

Definition at line 328 of file recurrence.cpp.

◆ recursOn()

bool Recurrence::recursOn ( const TQDate &  qd) const

Returns true if the date specified is one on which the event will recur.

Definition at line 268 of file recurrence.cpp.

◆ recurTimesOn()

TimeList Recurrence::recurTimesOn ( const TQDate &  date) const

Returns a list of the times on the specified date at which the recurrence will occur.

Parameters
datethe date for which to find the recurrence times.

Definition at line 721 of file recurrence.cpp.

◆ removeObserver()

void Recurrence::removeObserver ( Observer *  observer)

Removes an observer that was added with addObserver.

If the given object was not an observer, it does nothing.

Parameters
observerthe Recurrence::Observer-derived object to be removed from the list of observers of this object.

Definition at line 119 of file recurrence.cpp.

◆ setDaily()

void Recurrence::setDaily ( int  freq)

Sets an event to recur daily.

By default infinite recurrence is used. The minute and second of the recurrence is taken from the start date (if you need to change them, you will have to modify the defaultRRule's byMinute list manually. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

This method clears all recurrence rules and adds one rule with a daily recurrence. All other recurrence components (recurrence date/times, exception date/times and exception rules) are not modified.

Parameters
freqthe frequency to recur, e.g. 2 is every other day

Definition at line 584 of file recurrence.cpp.

◆ setDuration()

void Recurrence::setDuration ( int  duration)

Sets the total number of times the event is to occur, including both the first and last.

Definition at line 415 of file recurrence.cpp.

◆ setEndDate()

void Recurrence::setEndDate ( const TQDate &  endDate)

Sets the date of the last recurrence.

The end time is set to the recurrence start time.

Parameters
endDatethe ending date after which to stop recurring. If the incidence is not floating, the end time will be 23:59.

Definition at line 378 of file recurrence.cpp.

◆ setEndDateTime()

void Recurrence::setEndDateTime ( const TQDateTime &  endDateTime)

Sets the date and time of the last recurrence.

Parameters
endDateTimethe ending date/time after which to stop recurring.

Definition at line 386 of file recurrence.cpp.

◆ setFloats()

void Recurrence::setFloats ( bool  floats)

Sets whether the dtstart is a floating time (i.e.

has no time attached)

Parameters
floatsIf the recurrence is for all-day item (true) or has a time associated (false).

Definition at line 133 of file recurrence.cpp.

◆ setFrequency()

void Recurrence::setFrequency ( int  freq)

Sets the frequency of recurrence, in terms of the recurrence time period type.

Definition at line 474 of file recurrence.cpp.

◆ setHourly()

void Recurrence::setHourly ( int  freq)

Sets an event to recur hourly.

By default infinite recurrence is used. The minute of the recurrence is taken from the start date (if you need to change it, you will have to modify the defaultRRule's byMinute list manually. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

This method clears all recurrence rules and adds one rule with a hourly recurrence. All other recurrence components (recurrence date/times, exception date/times and exception rules) are not modified.

Parameters
freqthe frequency to recur, e.g. 2 is every other hour

Definition at line 578 of file recurrence.cpp.

◆ setMinutely()

void Recurrence::setMinutely ( int  freq)

Sets an event to recur minutely.

By default infinite recurrence is used. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

This method clears all recurrence rules and adds one rule with a minutely recurrence. All other recurrence components (recurrence date/times, exception date/times and exception rules) are not modified.

Parameters
freqthe frequency to recur, e.g. 2 is every other minute

Definition at line 572 of file recurrence.cpp.

◆ setMonthly()

void Recurrence::setMonthly ( int  freq)

Sets an event to recur monthly.

By default infinite recurrence is used. The date of the monthly recurrence will be taken from the start date unless you explicitly add one or more recurrence dates with addMonthlyDate or a recurrence position in the month (e.g. first monday) using addMonthlyPos. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

This method clears all recurrence rules and adds one rule with a monthly recurrence. All other recurrence components (recurrence date/times, exception date/times and exception rules) are not modified.

Parameters
freqthe frequency to recur, e.g. 3 for every third month.

Definition at line 609 of file recurrence.cpp.

◆ setRecurReadOnly()

void KCal::Recurrence::setRecurReadOnly ( bool  readOnly)
inline

Set if recurrence is read-only or can be changed.

Definition at line 139 of file recurrence.h.

◆ setStartDate()

void Recurrence::setStartDate ( const TQDate &  start)

Set start of recurrence, as a date.

Also sets the incidence to floating.

Parameters
startThe new start date of the incidence.

Definition at line 459 of file recurrence.cpp.

◆ setStartDateTime()

void Recurrence::setStartDateTime ( const TQDateTime &  start)

Set start of recurrence, as a date and time.

Also sets the incidence to non-floating.

Parameters
startthe new start date/time of the incidence.

Definition at line 444 of file recurrence.cpp.

◆ setWeekly() [1/2]

void Recurrence::setWeekly ( int  freq,
const TQBitArray &  days,
int  weekStart = 1 
)

Sets an event to recur weekly.

By default infinite recurrence is used. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

This method clears all recurrence rules and adds one rule with a weekly recurrence. All other recurrence components (recurrence date/times, exception date/times and exception rules) are not modified.

Parameters
freqthe frequency to recur, e.g. every other week etc.
daysa 7 bit array indicating which days on which to recur (bit 0 = Monday).
weekStartthe first day of the week (Monday=1 .. Sunday=7, default is Monday).

Definition at line 598 of file recurrence.cpp.

◆ setWeekly() [2/2]

void Recurrence::setWeekly ( int  freq,
int  weekStart = 1 
)

Sets an event to recur weekly.

By default infinite recurrence is used. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

This method clears all recurrence rules and adds one rule with a weekly recurrence. All other recurrence components (recurrence date/times, exception date/times and exception rules) are not modified.

Parameters
freqthe frequency to recur, e.g. every other week etc.
weekStartthe first day of the week (Monday=1 .. Sunday=7, default is Monday).

Definition at line 590 of file recurrence.cpp.

◆ setYearly()

void Recurrence::setYearly ( int  freq)

Sets an event to recur yearly.

By default, this will recur every year on the same date (e.g. every year on April 15 if the start date was April 15). The day of the year can be specified with addYearlyDay(). The day of the month can be specified with addYearlyByDate If both a month and a day ar specified with addYearlyMonth and addYearlyDay, the day is understood as day number within the month.

A position (e.g. 3rd Sunday of year/month, or last Friday of year/month) can be specified with addYearlyPos. Again, if a month is specified, this position is understood as within that month, otherwise within the year.

By default infinite recurrence is used. To set an end date use the method setEndDate and to set the number of occurrences use setDuration.

This method clears all recurrence rules and adds one rule with a yearly recurrence. All other recurrence components (recurrence date/times, exception date/times and exception rules) are not modified.

Parameters
freqthe frequency to recur, e.g. 3 for every third year.

Definition at line 671 of file recurrence.cpp.

◆ startDate()

TQDate KCal::Recurrence::startDate ( ) const
inline

Return the start date/time of the recurrence.

Definition at line 116 of file recurrence.h.

◆ startDateTime()

TQDateTime Recurrence::startDateTime ( ) const

Return the start date/time of the recurrence (Time for floating incidences will be 0:00).

Returns
the current start/time of the recurrence.

Definition at line 126 of file recurrence.cpp.

◆ timesInInterval()

DateTimeList Recurrence::timesInInterval ( const TQDateTime &  start,
const TQDateTime &  end 
) const

Returns a list of all the times at which the recurrence will occur between two specified times.

There is a (large) maximum limit to the number of times returned. If due to this limit the list is incomplete, this is indicated by the last entry being set to an invalid TQDateTime value. If you need further values, call the method again with a start time set to just after the last valid time returned.

Parameters
startinclusive start of interval
endinclusive end of interval
Returns
list of date/time values

Definition at line 771 of file recurrence.cpp.

◆ unsetRecurs()

void Recurrence::unsetRecurs ( )

Removes all recurrence rules.

Recurrence dates and exceptions are not removed.

Definition at line 424 of file recurrence.cpp.

◆ weekStart()

int Recurrence::weekStart ( ) const

Returns the first day of the week.

Uses only the first RRULE if present (i.e. a second RRULE as well as all EXRULES are ignored!

Returns
Weekday of the first day of the week (Monday=1 .. Sunday=7)

Definition at line 486 of file recurrence.cpp.

◆ yearDates()

TQValueList< int > Recurrence::yearDates ( ) const

Returns the dates within a yearly recurrence.

Returns
the days of the month for the event. E.g. if the list contains 13, this means the recurrence happens on the 13th of the month. The months for the recurrence can be obtained through yearlyMonths(). If this list is empty, the month of the start date is used.

Definition at line 540 of file recurrence.cpp.

◆ yearDays()

TQValueList< int > Recurrence::yearDays ( ) const

Returns the day numbers within a yearly recurrence.

Returns
the days of the year for the event. E.g. if the list contains 60, this means the recurrence happens on day 60 of the year, i.e. on Feb 29 in leap years and March 1 in non-leap years.

Definition at line 533 of file recurrence.cpp.

◆ yearMonths()

TQValueList< int > Recurrence::yearMonths ( ) const

Returns the months within a yearly recurrence.

Returns
the months for the event. E.g. if the list contains 11, this means the recurrence happens in November. The days for the recurrence can be obtained either through yearDates() if they are given as dates within the month or through yearlyPositions() if they are given as positions within the month. If none is specified, the date of the start date is used.

Definition at line 545 of file recurrence.cpp.

◆ yearPositions()

TQValueList< RecurrenceRule::WDayPos > Recurrence::yearPositions ( ) const

Returns the positions within a yearly recurrence.

Returns
the positions for the event, either within a month (if months are set through addYearlyMonth()) or within the year. E.g. if the list contains {Pos=3, Day=5}, this means the third friday. If a month is set this position is understoodas third Friday in the given months, otherwise as third Friday of the year. Returns list of day positions in months, for a recursYearlyPos recurrence rule.

Definition at line 552 of file recurrence.cpp.

Member Data Documentation

◆ MAX_DATE

const TQDate KCal::Recurrence::MAX_DATE
static

Upper date limit for recurrences.

Definition at line 447 of file recurrence.h.


The documentation for this class was generated from the following files: