KAlarmCal::KARecurrence

#include <karecurrence.h>

Public Types

enum  Feb29Type { Feb29_Feb28, Feb29_Mar1, Feb29_None }
 
enum  Type {
  NO_RECUR, MINUTELY, DAILY, WEEKLY,
  MONTHLY_POS, MONTHLY_DAY, ANNUAL_DATE, ANNUAL_POS
}
 

Public Member Functions

 KARecurrence (const KCalendarCore::Recurrence &r)
 
 KARecurrence (const KARecurrence &r)
 
void addExDate (const QDate &exdate)
 
void addExDateTime (const KADateTime &exdate)
 
void addMonthlyDate (short day)
 
void addMonthlyPos (short pos, const QBitArray &days)
 
void addMonthlyPos (short pos, ushort day)
 
void addWeeklyDays (const QBitArray &days)
 
void addYearlyDate (int date)
 
void addYearlyDay (int day)
 
void addYearlyMonth (short month)
 
void addYearlyPos (short pos, const QBitArray &days)
 
bool allDay () const
 
void clear ()
 
QBitArray days () const
 
KCalendarCore::RecurrenceRuledefaultRRuleConst () const
 
int duration () const
 
int durationTo (const KADateTime &dt) const
 
int durationTo (const QDate &date) const
 
QDate endDate () const
 
KADateTime endDateTime () const
 
KCalendarCore::DateList exDates () const
 
KCalendarCore::DateTimeList exDateTimes () const
 
Feb29Type feb29Type () const
 
void fix ()
 
int frequency () const
 
KADateTime getNextDateTime (const KADateTime &preDateTime) const
 
KADateTime getPreviousDateTime (const KADateTime &afterDateTime) const
 
bool init (KCalendarCore::RecurrenceRule::PeriodType t, int freq, int count, const KADateTime &start, const KADateTime &end)
 
bool init (KCalendarCore::RecurrenceRule::PeriodType t, int freq, int count, const KADateTime &start, const KADateTime &end, Feb29Type f29)
 
KCalendarCore::Duration longestInterval () const
 
QList< int > monthDays () const
 
QList< KCalendarCore::RecurrenceRule::WDayPosmonthPositions () const
 
bool operator!= (const KARecurrence &r) const
 
KARecurrenceoperator= (const KARecurrence &r)=delete
 
bool operator== (const KARecurrence &r) const
 
bool recurReadOnly () const
 
bool recurs () const
 
bool recursAt (const KADateTime &dt) const
 
bool recursOn (const QDate &, const KADateTime::Spec &) const
 
KCalendarCore::TimeList recurTimesOn (const QDate &date, const KADateTime::Spec &timeSpec) const
 
KCalendarCore::Duration regularInterval () const
 
bool set (const QString &icalRRULE)
 
bool set (Type t, int freq, int count, const KADateTime &start, const KADateTime &end)
 
bool set (Type t, int freq, int count, const KADateTime &start, const KADateTime &end, Feb29Type f29)
 
void setDuration (int duration)
 
void setEndDate (const QDate &endDate)
 
void setEndDateTime (const KADateTime &endDateTime)
 
void setExDates (const KCalendarCore::DateList &exdates)
 
void setExDateTimes (const KCalendarCore::DateTimeList &exdates)
 
void setFrequency (int freq)
 
void setRecurReadOnly (bool readOnly)
 
void setStartDateTime (const KADateTime &dt, bool dateOnly)
 
void shiftTimes (const QTimeZone &oldSpec, const QTimeZone &newSpec)
 
QDate startDate () const
 
KADateTime startDateTime () const
 
KCalendarCore::DateTimeList timesInInterval (const KADateTime &start, const KADateTime &end) const
 
Type type () const
 
void writeRecurrence (KCalendarCore::Recurrence &) const
 
QList< int > yearDates () const
 
QList< int > yearDays () const
 
QList< int > yearMonths () const
 
QList< KCalendarCore::RecurrenceRule::WDayPosyearPositions () const
 

Static Public Member Functions

static bool dailyType (const KCalendarCore::RecurrenceRule *)
 
static Feb29Type defaultFeb29Type ()
 
static void setDefaultFeb29Type (Feb29Type t)
 
static Type type (const KCalendarCore::RecurrenceRule *)
 

Detailed Description

Represents recurrences for KAlarm.

This class represents the restricted range of recurrence types which are handled by KAlarm, and translates between these and the libkcalendarcore Recurrence class. In particular, it handles yearly recurrences on 29th February in non-leap years specially:

KARecurrence allows annual 29th February recurrences to fall on 28th February or 1st March, or not at all, in non-leap years. It allows such 29th February recurrences to be combined with the 29th of other months in a simple way, represented simply as the 29th of multiple months including February. For storage in the libkcalendarcore calendar, the 29th day of the month recurrence for other months is combined with a last-day-of-February or a 60th-day-of-the-year recurrence rule, thereby conforming to RFC2445.

Author
David Jarvie djarv[email protected][email protected][email protected]de.or[email protected]g

Definition at line 47 of file karecurrence.h.

Member Enumeration Documentation

When annual February 29th recurrences should occur in non-leap years.

Enumerator
Feb29_Feb28 

occurs on 28 February in non-leap years

Feb29_Mar1 

occurs on 1 March in non-leap years

Feb29_None 

does not occur in non-leap years

Definition at line 65 of file karecurrence.h.

The recurrence's period type.

This is a subset of the possible KCalendarCore recurrence types.

Enumerator
NO_RECUR 

does not recur

MINUTELY 

at an hours/minutes interval

DAILY 

daily

WEEKLY 

weekly, on specified weekdays

MONTHLY_POS 

monthly, on specified weekdays in a specified week of the month

MONTHLY_DAY 

monthly, on a specified day of the month

ANNUAL_DATE 

yearly, on a specified date in each of the specified months

ANNUAL_POS 

yearly, on specified weekdays in the specified weeks of the specified months

Definition at line 53 of file karecurrence.h.

Member Function Documentation

void KAlarmCal::KARecurrence::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 784 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::addMonthlyPos ( short  pos,
const QBitArray 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 774 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::addWeeklyDays ( const QBitArray 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 749 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::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 759 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::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 754 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::addYearlyMonth ( short  month)

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
monththe month in which the event will recur.

Definition at line 764 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::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.

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 769 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::allDay ( ) const

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

Definition at line 694 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::clear ( )

Removes all recurrence and exception rules and dates.

Definition at line 279 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::dailyType ( const KCalendarCore::RecurrenceRule rrule)
static

Check if the recurrence rule is a daily rule with or without BYDAYS specified.

Definition at line 1266 of file karecurrence.cpp.

QBitArray KAlarmCal::KARecurrence::days ( ) const

Returns week day mask (bit 0 = Monday).

Definition at line 714 of file karecurrence.cpp.

KARecurrence::Feb29Type KAlarmCal::KARecurrence::defaultFeb29Type ( )
static

Return the default way that 29th February annual recurrences should occur in non-leap years.

See also
setDefaultFeb29Type().

Definition at line 126 of file karecurrence.cpp.

int KAlarmCal::KARecurrence::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 884 of file karecurrence.cpp.

int KAlarmCal::KARecurrence::durationTo ( const KADateTime dt) const

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

Warning
This function can be very time consuming - use it sparingly!

Definition at line 894 of file karecurrence.cpp.

int KAlarmCal::KARecurrence::durationTo ( const QDate date) const

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

Warning
This function can be very time consuming - use it sparingly!

Definition at line 899 of file karecurrence.cpp.

QDate KAlarmCal::KARecurrence::endDate ( ) const

Return the date of the last recurrence.

Definition at line 678 of file karecurrence.cpp.

KADateTime KAlarmCal::KARecurrence::endDateTime ( ) const

Return the date/time of the last recurrence.

Definition at line 608 of file karecurrence.cpp.

KARecurrence::Feb29Type KAlarmCal::KARecurrence::feb29Type ( ) const

Return when 29th February annual recurrences should occur in non-leap years.

Definition at line 121 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::fix ( )

Convert the recurrence to KARecurrence types.

Must be called after presetting with a KCalendarCore::Recurrence.

  • Convert hourly recurrences to minutely.
  • Remove all but the first day in yearly date recurrences.
  • Check for yearly recurrences falling on February 29th and adjust them as necessary. A 29th of the month rule can be combined with either a 60th day of the year rule or a last day of February rule.

Definition at line 293 of file karecurrence.cpp.

int KAlarmCal::KARecurrence::frequency ( ) const

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

Definition at line 874 of file karecurrence.cpp.

KADateTime KAlarmCal::KARecurrence::getNextDateTime ( const KADateTime preDateTime) const

Get the next time the recurrence occurs, strictly after a specified time.

Definition at line 792 of file karecurrence.cpp.

KADateTime KAlarmCal::KARecurrence::getPreviousDateTime ( const KADateTime afterDateTime) const

Get the previous time the recurrence occurred, strictly before a specified time.

Definition at line 809 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::init ( KCalendarCore::RecurrenceRule::PeriodType  t,
int  freq,
int  count,
const KADateTime start,
const KADateTime end 
)

Set up a KARecurrence from recurrence parameters.

Annual 29th February recurrences in non-leap years will be handled according to the default set by setDefaultFeb29Type(). Only a restricted subset of recurrence types is allowed: minutely, daily, weekly, monthly, yearly or none.

Returns
true if successful.

Definition at line 193 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::init ( KCalendarCore::RecurrenceRule::PeriodType  t,
int  freq,
int  count,
const KADateTime start,
const KADateTime end,
Feb29Type  f29 
)

Set up a KARecurrence from recurrence parameters, specifying how annual 29th February recurrences in non-leap years should be handled.

Only a restricted subset of recurrence types is allowed: minutely, daily, weekly, monthly, yearly or none.

Returns
true if successful.

Definition at line 199 of file karecurrence.cpp.

Duration KAlarmCal::KARecurrence::longestInterval ( ) const

Return the longest interval between recurrences.

Returns
0 if it never recurs.

Definition at line 982 of file karecurrence.cpp.

QList< int > KAlarmCal::KARecurrence::monthDays ( ) const

Returns list of day numbers of a month.

Definition at line 724 of file karecurrence.cpp.

QList< RecurrenceRule::WDayPos > KAlarmCal::KARecurrence::monthPositions ( ) const

Returns list of day positions in months.

Definition at line 719 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::operator!= ( const KARecurrence r) const
inline

Comparison operator for inequality.

Parameters
rinstance to compare with
Returns
true if recurrences are the different, false if the same

Definition at line 94 of file karecurrence.h.

KARecurrence& KAlarmCal::KARecurrence::operator= ( const KARecurrence r)
delete

Assignment operator.

Parameters
rthe recurrence which will be assigned to this.
bool KAlarmCal::KARecurrence::operator== ( const KARecurrence r) const

Comparison operator for equality.

Parameters
rinstance to compare with
Returns
true if recurrences are the same, false otherwise

Definition at line 115 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::recurReadOnly ( ) const

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

Definition at line 704 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::recurs ( ) const

Returns whether the event recurs at all.

Definition at line 709 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::recursAt ( const KADateTime 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.

Parameters
dtis the date/time to check.

Definition at line 853 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::recursOn ( const QDate dt,
const KADateTime::Spec timeSpec 
) const

Return whether the event will recur on the specified date.

The start date only returns true if it matches the recurrence rules.

Definition at line 827 of file karecurrence.cpp.

TimeList KAlarmCal::KARecurrence::recurTimesOn ( const QDate date,
const KADateTime::Spec timeSpec 
) 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 timeSpec.

Parameters
datethe date for which to find the recurrence times
timeSpectime specification for date

Definition at line 858 of file karecurrence.cpp.

Duration KAlarmCal::KARecurrence::regularInterval ( ) const

Return the interval between recurrences, if the interval between successive occurrences does not vary.

Returns
0 if recurrence does not occur at fixed intervals.

Definition at line 1116 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::set ( const QString icalRRULE)

Initialise the recurrence from an iCalendar RRULE string.

Returns
true if successful, false if an error occurred.

Definition at line 263 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::set ( Type  t,
int  freq,
int  count,
const KADateTime start,
const KADateTime end 
)

Set up a KARecurrence from recurrence parameters, using the start date to determine the recurrence day/month as appropriate.

Annual 29th February recurrences in non-leap years will be handled according to the default set by setDefaultFeb29Type(). Only a restricted subset of recurrence types is allowed: minutely, daily, weekly, monthly, yearly or none.

Returns
true if successful.

Definition at line 142 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::set ( Type  t,
int  freq,
int  count,
const KADateTime start,
const KADateTime end,
Feb29Type  f29 
)

Set up a KARecurrence from recurrence parameters, using the start date to determine the recurrence day/month as appropriate, and specifying how annual 29th February recurrences in non-leap years should be handled.

Returns
true if successful.

Definition at line 147 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setDefaultFeb29Type ( Feb29Type  t)
static

Set the default way that 29th February annual recurrences should occur in non-leap years.

See also
defaultFeb29Type().

Definition at line 131 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setDuration ( int  duration)

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

Definition at line 889 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setEndDate ( const QDate 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 recurrence is not all-day, the end time will be 23:59.

Definition at line 684 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setEndDateTime ( const KADateTime endDateTime)

Sets the date and time of the last recurrence.

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

Definition at line 689 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setFrequency ( int  freq)

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

Definition at line 879 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setRecurReadOnly ( bool  readOnly)

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

Definition at line 699 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setStartDateTime ( const KADateTime dt,
bool  dateOnly 
)

Set the recurrence start date/time, and optionally set it to all-day.

Parameters
dtstart date/time.
dateOnlyif true, sets the recurrence to all-day.

Definition at line 597 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::shiftTimes ( const QTimeZone oldSpec,
const QTimeZone newSpec 
)

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 (oldSpec) of Europe/London, to a new time zone (newSpec) 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.

Parameters
oldSpecthe time specification which provides the clock times
newSpecthe new time specification

Definition at line 1221 of file karecurrence.cpp.

QDate KAlarmCal::KARecurrence::startDate ( ) const

Return the start date/time of the recurrence.

Definition at line 592 of file karecurrence.cpp.

KADateTime KAlarmCal::KARecurrence::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.

Definition at line 587 of file karecurrence.cpp.

DateTimeList KAlarmCal::KARecurrence::timesInInterval ( const KADateTime start,
const KADateTime 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 KADateTime 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 863 of file karecurrence.cpp.

KARecurrence::Type KAlarmCal::KARecurrence::type ( ) const

Return the recurrence's period type.

Definition at line 1234 of file karecurrence.cpp.

KARecurrence::Type KAlarmCal::KARecurrence::type ( const KCalendarCore::RecurrenceRule rrule)
static

Return the type of a recurrence rule.

Definition at line 1245 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::writeRecurrence ( KCalendarCore::Recurrence recur) const

Initialise a KCalendarCore::Recurrence to be the same as this instance.

Additional recurrence rules are created as necessary if it recurs on Feb 29th.

Definition at line 462 of file karecurrence.cpp.

QList< int > KAlarmCal::KARecurrence::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 734 of file karecurrence.cpp.

QList< int > KAlarmCal::KARecurrence::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 729 of file karecurrence.cpp.

QList< int > KAlarmCal::KARecurrence::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 739 of file karecurrence.cpp.

QList< RecurrenceRule::WDayPos > KAlarmCal::KARecurrence::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.

Definition at line 744 of file karecurrence.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Tue Sep 22 2020 23:10:31 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.