KCalendarCore::Recurrence Class

Member Function Documentation

Recurrence::Recurrence()

Constructs an empty recurrence.

Recurrence::Recurrence(const KCalendarCore::Recurrence &r)

Copy constructor.

r instance to copy from

[override virtual noexcept] Recurrence::~Recurrence()

Destructor.

void Recurrence::addExRule(KCalendarCore::RecurrenceRule *exrule)

Add an exception rule to the recurrence.

exrule the exception rule to add

void Recurrence::addMonthlyDate(short day)

Adds a date (e.g. the 15th of each month) to the monthly day recurrence list.

day the date in the month to recur.

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

Adds a position (e.g. first monday) to the monthly recurrence rule.

pos the position in the month for the recurrence, with valid values being 1-5 (5 weeks max in a month).

days the 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.

void Recurrence::addObserver(KCalendarCore::Recurrence::RecurrenceObserver *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.

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

[since 5.87] void Recurrence::addRDateTimePeriod(const KCalendarCore::Period &period)

Add a RDATE defined as a PERIOD. The start date-time of the period is added to the recurring date time list, and will be listed by a call to rDateTimes(). Use then rDateTimePeriod() to fetch the associated period definition.

period a given RDATE in period definition.

This function was introduced in 5.87.

void Recurrence::addRRule(KCalendarCore::RecurrenceRule *rrule)

Add a recurrence rule to the recurrence.

rrule the recurrence rule to add

void Recurrence::addWeeklyDays(const QBitArray &days)

Adds days to the weekly day recurrence list.

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

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.

date the day of the month for the event

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.

day the 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.

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).

_rNum the month in which the event shall recur.

void Recurrence::addYearlyPos(short pos, const QBitArray &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.

pos the 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).

days the 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 file is to repeat every year on the 2nd Monday and Wednesday of the year.

bool Recurrence::allDay() const

Sets whether the recurrence has no time, just a date. All-day means – according to rfc2445 – that the event has no time associated. N.B. This property is derived by default from whether setStartDateTime() is called with a date-only or date/time parameter. Returns whether the recurrence has a time (false) or it is just a date (true).

See also setAllDay().

void Recurrence::clear()

Removes all recurrence and exception rules and dates.

QBitArray Recurrence::days() const

Returns week day mask (bit 0 = Monday).

void Recurrence::deleteExRule(KCalendarCore::RecurrenceRule *exrule)

Remove an exception rule from the recurrence and delete it.

exrule the exception rule to remove

void Recurrence::deleteRRule(KCalendarCore::RecurrenceRule *rrule)

Remove a recurrence rule from the recurrence and delete it.

rrule the recurrence rule to remove

void Recurrence::dump() const

Debug output.

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.

See also setDuration().

int Recurrence::durationTo(const QDate &date) const

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

int Recurrence::durationTo(const QDateTime &dt) const

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

QDate Recurrence::endDate() const

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

See also setEndDate().

QDateTime Recurrence::endDateTime() const

Returns the date/time of the last recurrence. An invalid date is returned if the recurrence has no end.

See also setEndDateTime().

int Recurrence::frequency() const

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

See also setFrequency().

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

Returns the start date/time of the earliest recurrence with a start date/time after the specified date/time. If the recurrence has no time, the next date after the specified date is returned.

preDateTime the date/time after which to find the recurrence.

Returns start date/time of next recurrence (strictly later than the given QDateTime), or invalid date if none.

QDateTime Recurrence::getPreviousDateTime(const QDateTime &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.

afterDateTime the date/time before which to find the recurrence.

Returns date/time of previous recurrence (strictly earlier than the given QDateTime), or invalid date if none.

QList<int> Recurrence::monthDays() const

Returns list of day numbers of a month.

QList<KCalendarCore::RecurrenceRule::WDayPos> Recurrence::monthPositions() const

Returns list of day positions in months.

[since 5.87] KCalendarCore::Period Recurrence::rDateTimePeriod(const QDateTime &rdate) const

Inquire if the given RDATE is associated to a PERIOD.

rdate a given RDATE in date time format.

Returns a Period, invalid if there is no period associated to rdate.

This function was introduced in 5.87.

bool Recurrence::recurReadOnly() const

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

See also setRecurReadOnly().

KCalendarCore::TimeList Recurrence::recurTimesOn(const QDate &date, const QTimeZone &timeZone) const

Returns a list of the times on the specified date at which the recurrence will occur. The returned times should be interpreted in the context of timeZone.

date the date for which to find the recurrence times

timeZone timeZone for date

ushort Recurrence::recurrenceType() const

Returns the event's recurrence status. See the enumeration at the top of this file for possible values.

[static] ushort Recurrence::recurrenceType(const KCalendarCore::RecurrenceRule *rrule)

Returns the recurrence status for a recurrence rule. See the enumeration at the top of this file for possible values.

rrule the recurrence rule to get the type for

bool Recurrence::recurs() const

Returns whether the event recurs at all.

bool Recurrence::recursAt(const QDateTime &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.

dt is the date/time to check.

bool Recurrence::recursOn(const QDate &date, const QTimeZone &timeZone) const

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

date is the date to check.

timeZone is the time zone for the date.

void Recurrence::removeExRule(KCalendarCore::RecurrenceRule *exrule)

Remove an exception rule from the recurrence.

exrule is not deleted; it is the responsibility of the caller to ensure that it is deleted.

exrule the exception rule to remove

void Recurrence::removeObserver(KCalendarCore::Recurrence::RecurrenceObserver *observer)

Removes an observer that was added with addObserver. If the given object was not an observer, it does nothing.

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

void Recurrence::removeRRule(KCalendarCore::RecurrenceRule *rrule)

Remove a recurrence rule from the recurrence.

rrule is not deleted; it is the responsibility of the caller to ensure that it is deleted.

rrule the recurrence rule to remove

void Recurrence::setAllDay(bool allDay)

Sets whether the dtstart is a all-day (i.e. has no time attached)

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

See also allDay().

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.

freq the frequency to recur, e.g. 2 is every other day

void Recurrence::setDuration(int duration)

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

See also duration().

void Recurrence::setEndDate(const QDate &endDate)

Sets the date of the last recurrence. The end time is set to the recurrence start time.

endDate the ending date after which to stop recurring. If the recurrence is not all-day, the end time will be 23:59.

See also endDate().

void Recurrence::setEndDateTime(const QDateTime &endDateTime)

Sets the date and time of the last recurrence.

endDateTime the ending date/time after which to stop recurring.

See also endDateTime().

void Recurrence::setFrequency(int freq)

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

See also frequency().

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.

freq the frequency to recur, e.g. 2 is every other hour

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.

freq the frequency to recur, e.g. 2 is every other minute

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.

freq the frequency to recur, e.g. 3 for every third month.

void Recurrence::setRecurReadOnly(bool readOnly)

Sets if recurrence is read-only (if readOnly is true) or can be changed (if readOnly is false).

See also recurReadOnly().

void Recurrence::setStartDateTime(const QDateTime &start, bool isAllDay)

Sets the start of the recurrence.

start the new start date or date/time of the recurrence.

isAllDay if true, the recurrence is set to all-day. Otherwise the recurrence is set to non-all-day.

See also startDateTime().

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.

freq the frequency to recur, e.g. every other week etc.

weekStart the first day of the week (Monday=1 .. Sunday=7, default is Monday).

void Recurrence::setWeekly(int freq, const QBitArray &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.

freq the frequency to recur, e.g. every other week etc.

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

weekStart the first day of the week (Monday=1 .. Sunday=7, default is Monday).

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.

freq the frequency to recur, e.g. 3 for every third year.

void Recurrence::shiftTimes(const QTimeZone &oldZone, const QTimeZone &newZone)

Shift the times of the recurrence so that they appear at the same clock time as before but in a new time zone. The shift is done from a viewing time zone rather than from the actual recurrence time zone.

For example, shifting a recurrence whose start time is 09:00 America/New York, using an old viewing time zone (oldZone) of Europe/London, to a new time zone (newZone) of Europe/Paris, will result in the time being shifted from 14:00 (which is the London time of the recurrence start) to 14:00 Paris time.

oldZone the time specification which provides the clock times

newZone the new time specification

QDate Recurrence::startDate() const

Return the start date/time of the recurrence

QDateTime Recurrence::startDateTime() const

Return the start date/time of the recurrence (Time for all-day recurrences will be 0:00). Returns the current start/time of the recurrence.

See also setStartDateTime().

QList<QDateTime> Recurrence::timesInInterval(const QDateTime &start, const QDateTime &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 QDateTime value. If you need further values, call the method again with a start time set to just after the last valid time returned.

start inclusive start of interval

end inclusive end of interval

Returns list of date/time values

void Recurrence::unsetRecurs()

Removes all recurrence rules. Recurrence dates and exceptions are not removed.

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)

QList<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.

QList<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.

QList<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.

QList<KCalendarCore::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.

bool Recurrence::operator!=(const KCalendarCore::Recurrence &r) const

Comparison operator for inequality.

r is the instance to compare with

Returns true if recurrences are the different, false if the same

bool Recurrence::operator==(const KCalendarCore::Recurrence &r) const

Comparison operator for equality.

r is the instance to compare with

Returns true if recurrences are the same, false otherwise