KAlarmCal::KARecurrence Class Reference

#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 KCalCore::Recurrence &r)
	KARecurrence (const KARecurrence &r)
void	addExDate (const QDate &exdate)
void	addExDateTime (const KDateTime &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
KCalCore::RecurrenceRule *	defaultRRuleConst () const
int	duration () const
int	durationTo (const KDateTime &dt) const
int	durationTo (const QDate &date) const
QDate	endDate () const
KDateTime	endDateTime () const
KCalCore::DateList	exDates () const
KCalCore::DateTimeList	exDateTimes () const
Feb29Type	feb29Type () const
void	fix ()
int	frequency () const
KDateTime	getNextDateTime (const KDateTime &preDateTime) const
KDateTime	getPreviousDateTime (const KDateTime &afterDateTime) const
bool	init (KCalCore::RecurrenceRule::PeriodType t, int freq, int count, const KDateTime &start, const KDateTime &end)
bool	init (KCalCore::RecurrenceRule::PeriodType t, int freq, int count, const KDateTime &start, const KDateTime &end, Feb29Type f29)
KCalCore::Duration	longestInterval () const
QList< int >	monthDays () const
QList < KCalCore::RecurrenceRule::WDayPos >	monthPositions () const
bool	operator!= (const KARecurrence &r) const
KARecurrence &	operator= (const KARecurrence &r)
bool	operator== (const KARecurrence &r) const
bool	recurReadOnly () const
bool	recurs () const
bool	recursAt (const KDateTime &dt) const
bool	recursOn (const QDate &, const KDateTime::Spec &) const
KCalCore::TimeList	recurTimesOn (const QDate &date, const KDateTime::Spec &timeSpec) const
KCalCore::Duration	regularInterval () const
bool	set (const QString &icalRRULE)
bool	set (Type t, int freq, int count, const KDateTime &start, const KDateTime &end)
bool	set (Type t, int freq, int count, const KDateTime &start, const KDateTime &end, Feb29Type f29)
void	setDuration (int duration)
void	setEndDate (const QDate &endDate)
void	setEndDateTime (const KDateTime &endDateTime)
void	setExDates (const KCalCore::DateList &exdates)
void	setExDateTimes (const KCalCore::DateTimeList &exdates)
void	setFrequency (int freq)
void	setRecurReadOnly (bool readOnly)
void	setStartDateTime (const KDateTime &dt, bool dateOnly)
void	shiftTimes (const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec)
QDate	startDate () const
KDateTime	startDateTime () const
KCalCore::DateTimeList	timesInInterval (const KDateTime &start, const KDateTime &end) const
Type	type () const
void	writeRecurrence (KCalCore::Recurrence &) const
QList< int >	yearDates () const
QList< int >	yearDays () const
QList< int >	yearMonths () const
QList < KCalCore::RecurrenceRule::WDayPos >	yearPositions () const

Static Public Member Functions
static bool	dailyType (const KCalCore::RecurrenceRule *)
static Feb29Type	defaultFeb29Type ()
static void	setDefaultFeb29Type (Feb29Type t)
static Type	type (const KCalCore::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 libkcalcore 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 libkcalcore 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.nosp@m.ie@k.nosp@m.de.or.nosp@m.g

Definition at line 61 of file karecurrence.h.

Member Enumeration Documentation

enum KAlarmCal::KARecurrence::Feb29Type

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 79 of file karecurrence.h.

enum KAlarmCal::KARecurrence::Type

The recurrence's period type.

This is a subset of the possible KCalCore 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 67 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

day	the date in the month to recur.

Definition at line 802 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

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.

Definition at line 792 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::addWeeklyDays

(

const QBitArray &

days

)

Adds days to the weekly day recurrence list.

Parameters

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

Definition at line 767 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

date	the day of the month for the event

Definition at line 777 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

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.

Definition at line 772 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

month

the month in which the event will recur.

Definition at line 782 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

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

Definition at line 787 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 712 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::clear

(

)

Removes all recurrence and exception rules and dates.

Definition at line 290 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::dailyType ( const KCalCore::RecurrenceRule *  rrule )

static

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

Definition at line 1270 of file karecurrence.cpp.

QBitArray KAlarmCal::KARecurrence::days

(

)

const

Returns week day mask (bit 0 = Monday).

Definition at line 732 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 139 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 895 of file karecurrence.cpp.

int KAlarmCal::KARecurrence::durationTo

(

const KDateTime &

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

QDate KAlarmCal::KARecurrence::endDate

(

)

const

Return the date of the last recurrence.

Definition at line 696 of file karecurrence.cpp.

KDateTime KAlarmCal::KARecurrence::endDateTime

(

)

const

Return the date/time of the last recurrence.

Definition at line 623 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 134 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::fix

(

)

Convert the recurrence to KARecurrence types.

Must be called after presetting with a KCalCore::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 304 of file karecurrence.cpp.

int KAlarmCal::KARecurrence::frequency

(

)

const

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

Definition at line 885 of file karecurrence.cpp.

KDateTime KAlarmCal::KARecurrence::getNextDateTime

(

const KDateTime &

preDateTime

)

const

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

Definition at line 810 of file karecurrence.cpp.

KDateTime KAlarmCal::KARecurrence::getPreviousDateTime

(

const KDateTime &

afterDateTime

)

const

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

Definition at line 829 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::init	(	KCalCore::RecurrenceRule::PeriodType	t,
		int	freq,
		int	count,
		const KDateTime &	start,
		const KDateTime &	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 208 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::init	(	KCalCore::RecurrenceRule::PeriodType	t,
		int	freq,
		int	count,
		const KDateTime &	start,
		const KDateTime &	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 213 of file karecurrence.cpp.

Duration KAlarmCal::KARecurrence::longestInterval

(

)

const

Return the longest interval between recurrences.

Returns

0 if it never recurs.

Definition at line 994 of file karecurrence.cpp.

QList< int > KAlarmCal::KARecurrence::monthDays

(

)

const

Returns list of day numbers of a month.

Definition at line 742 of file karecurrence.cpp.

QList< RecurrenceRule::WDayPos > KAlarmCal::KARecurrence::monthPositions

(

)

const

Returns list of day positions in months.

Definition at line 737 of file karecurrence.cpp.

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

inline

Comparison operator for inequality.

Parameters

r	instance to compare with

Returns

true if recurrences are the different, false if the same

Definition at line 112 of file karecurrence.h.

KARecurrence & KAlarmCal::KARecurrence::operator=

(

const KARecurrence &

r

)

Assignment operator.

Parameters

r	the recurrence which will be assigned to this.

Definition at line 121 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::operator==

(

const KARecurrence &

r

)

const

Comparison operator for equality.

Parameters

r	instance to compare with

Returns

true if recurrences are the same, false otherwise

Definition at line 128 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 722 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::recurs

(

)

const

Returns whether the event recurs at all.

Definition at line 727 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::recursAt

(

const KDateTime &

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

dt	is the date/time to check.

Definition at line 870 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::recursOn	(	const QDate &	dt,
		const KDateTime::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 849 of file karecurrence.cpp.

TimeList KAlarmCal::KARecurrence::recurTimesOn	(	const QDate &	date,
		const KDateTime::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

date	the date for which to find the recurrence times
timeSpec	time specification for date

Definition at line 875 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 1127 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 276 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::set	(	Type	t,
		int	freq,
		int	count,
		const KDateTime &	start,
		const KDateTime &	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 155 of file karecurrence.cpp.

bool KAlarmCal::KARecurrence::set	(	Type	t,
		int	freq,
		int	count,
		const KDateTime &	start,
		const KDateTime &	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 160 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 144 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 900 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

endDate

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

Definition at line 702 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setEndDateTime

(

const KDateTime &

endDateTime

)

Sets the date and time of the last recurrence.

Parameters

endDateTime

the ending date/time after which to stop recurring.

Definition at line 707 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 890 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::setRecurReadOnly

(

bool

readOnly

)

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

Definition at line 717 of file karecurrence.cpp.

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

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

Parameters

dt	start date/time.
dateOnly	if true, sets the recurrence to all-day.

Definition at line 613 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::shiftTimes	(	const KDateTime::Spec &	oldSpec,
		const KDateTime::Spec &	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

oldSpec	the time specification which provides the clock times
newSpec	the new time specification

Definition at line 1226 of file karecurrence.cpp.

QDate KAlarmCal::KARecurrence::startDate

(

)

const

Return the start date/time of the recurrence.

Definition at line 608 of file karecurrence.cpp.

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

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

Parameters

start	inclusive start of interval
end	inclusive end of interval

Returns

list of date/time values

Definition at line 880 of file karecurrence.cpp.

KARecurrence::Type KAlarmCal::KARecurrence::type

(

)

const

Return the recurrence's period type.

Definition at line 1239 of file karecurrence.cpp.

KARecurrence::Type KAlarmCal::KARecurrence::type ( const KCalCore::RecurrenceRule *  rrule )

static

Return the type of a recurrence rule.

Definition at line 1249 of file karecurrence.cpp.

void KAlarmCal::KARecurrence::writeRecurrence

(

KCalCore::Recurrence &

recur

)

const

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

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

Definition at line 477 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 752 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 747 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 757 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 762 of file karecurrence.cpp.

---

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

• karecurrence.h
• karecurrence.cpp