#include <kaevent.h>

Classes
struct	MonthPos

Public Types
enum	Actions { ACT_NONE = 0, ACT_DISPLAY = 0x01, ACT_COMMAND = 0x02, ACT_EMAIL = 0x04, ACT_AUDIO = 0x08, ACT_DISPLAY_COMMAND = ACT_DISPLAY \| ACT_COMMAND, ACT_ALL = ACT_DISPLAY \| ACT_COMMAND \| ACT_EMAIL \| ACT_AUDIO }

enum	CmdErrType { CMD_NO_ERROR = 0, CMD_ERROR = 0x01, CMD_ERROR_PRE = 0x02, CMD_ERROR_POST = 0x04, CMD_ERROR_PRE_POST = CMD_ERROR_PRE \| CMD_ERROR_POST }

enum	DeferLimitType { LIMIT_NONE, LIMIT_MAIN, LIMIT_RECURRENCE, LIMIT_REPETITION, LIMIT_REMINDER }

enum	ExtraActionOption { CancelOnPreActError = 0x01, DontShowPreActError = 0x02, ExecPreActOnDeferral = 0x04 }

enum	Flag { BEEP = 0x02, REPEAT_AT_LOGIN = 0x04, ANY_TIME = 0x08, CONFIRM_ACK = 0x10, EMAIL_BCC = 0x20, DEFAULT_FONT = 0x40, REPEAT_SOUND = 0x80, DISABLED = 0x100, AUTO_CLOSE = 0x200, SCRIPT = 0x400, EXEC_IN_XTERM = 0x800, SPEAK = 0x1000, COPY_KORGANIZER = 0x2000, EXCL_HOLIDAYS = 0x4000, WORK_TIME_ONLY = 0x8000, DISPLAY_COMMAND = 0x10000, REMINDER_ONCE = 0x20000 }

typedef QVector< KAEvent * >	List

enum	OccurOption { IGNORE_REPETITION, RETURN_REPETITION, ALLOW_FOR_REPETITION }

enum	OccurType { NO_OCCURRENCE = 0, FIRST_OR_ONLY_OCCURRENCE = 0x01, RECURRENCE_DATE = 0x02, RECURRENCE_DATE_TIME = 0x03, LAST_RECURRENCE = 0x04, OCCURRENCE_REPEAT = 0x10, FIRST_OR_ONLY_OCCURRENCE_REPEAT = OCCURRENCE_REPEAT \| FIRST_OR_ONLY_OCCURRENCE, RECURRENCE_DATE_REPEAT = OCCURRENCE_REPEAT \| RECURRENCE_DATE, RECURRENCE_DATE_TIME_REPEAT = OCCURRENCE_REPEAT \| RECURRENCE_DATE_TIME, LAST_RECURRENCE_REPEAT = OCCURRENCE_REPEAT \| LAST_RECURRENCE }

enum	SubAction { MESSAGE = KAAlarm::MESSAGE, FILE = KAAlarm::FILE, COMMAND = KAAlarm::COMMAND, EMAIL = KAAlarm::EMAIL, AUDIO = KAAlarm::AUDIO }

enum	TriggerType { ALL_TRIGGER, MAIN_TRIGGER, WORK_TRIGGER, ALL_WORK_TRIGGER, DISPLAY_TRIGGER }

enum	UidAction { UID_IGNORE, UID_CHECK, UID_SET }

Public Member Functions
	KAEvent ()

	KAEvent (const KDateTime &, const QString &text, const QColor &bg, const QColor &fg, const QFont &f, SubAction, int lateCancel, Flags flags, bool changesPending=false)

	KAEvent (const KCalCore::Event::Ptr &)

	KAEvent (const KAEvent &other)

SubAction	actionSubType () const

Actions	actionTypes () const

void	activateReminderAfter (const DateTime &mainAlarmTime)

KAAlarm	alarm (KAAlarm::Type type) const

int	alarmCount () const

QString	audioFile () const

bool	autoClose () const

bool	beep () const

QColor	bgColour () const

void	cancelDefer ()

bool	cancelOnPreActionError () const

CalEvent::Type	category () const

QString	cleanText () const

Akonadi::Collection::Id	collectionId () const

QString	command () const

bool	commandDisplay () const

CmdErrType	commandError () const

bool	commandScript () const

bool	commandXterm () const

KACalendar::Compat	compatibility () const

bool	confirmAck () const

KAAlarm	convertDisplayingAlarm () const

bool	copyToKOrganizer () const

KDateTime	createdDateTime () const

QMap< QByteArray, QString >	customProperties () const

void	defer (const DateTime &dt, bool reminder, bool adjustRecurrence=false)

DateTime	deferDateTime () const

bool	deferDefaultDateOnly () const

int	deferDefaultMinutes () const

DateTime	deferralLimit (DeferLimitType *limitType=0) const

bool	deferred () const

bool	displaying () const

QString	displayMessage () const

bool	dontShowPreActionError () const

void	dumpDebug () const

KCalCore::Person::List	emailAddressees () const

QStringList	emailAddresses () const

QString	emailAddresses (const QString &sep) const

QStringList	emailAttachments () const

QString	emailAttachments (const QString &sep) const

bool	emailBcc () const

uint	emailFromId () const

QString	emailMessage () const

QStringList	emailPureAddresses () const

QString	emailPureAddresses (const QString &sep) const

QString	emailSubject () const

bool	enabled () const

void	endChanges ()

bool	expired () const

ExtraActionOptions	extraActionOptions () const

int	fadeSeconds () const

float	fadeVolume () const

QColor	fgColour () const

QString	fileName () const

KAAlarm	firstAlarm () const

Flags	flags () const

QFont	font () const

bool	holidaysExcluded () const

QString	id () const

void	incrementRevision ()

bool	isReadOnly () const

bool	isTemplate () const

bool	isValid () const

bool	isWorkingTime (const KDateTime &dt) const

Akonadi::Item::Id	itemId () const

unsigned long	kmailSerialNumber () const

int	lateCancel () const

QString	logFile () const

KCalCore::Duration	longestRecurrenceInterval () const

DateTime	mainDateTime (bool withRepeats=false) const

DateTime	mainEndRepeatTime () const

bool	mainExpired () const

QTime	mainTime () const

QString	message () const

KAAlarm	nextAlarm (const KAAlarm &previousAlarm) const

KAAlarm	nextAlarm (KAAlarm::Type previousType) const

OccurType	nextOccurrence (const KDateTime &preDateTime, DateTime &result, OccurOption option=IGNORE_REPETITION) const

int	nextRepetition () const

DateTime	nextTrigger (TriggerType type) const

bool	occursAfter (const KDateTime &preDateTime, bool includeRepetitions) const

KAEvent &	operator= (const KAEvent &other)

QString	postAction () const

QString	preAction () const

OccurType	previousOccurrence (const KDateTime &afterDateTime, DateTime &result, bool includeRepetitions=false) const

int	recurInterval () const

KARecurrence *	recurrence () const

QString	recurrenceText (bool brief=false) const

bool	recurs () const

KARecurrence::Type	recurType () const

void	reinstateFromDisplaying (const KCalCore::Event::Ptr &event, Akonadi::Collection::Id &colId, bool &showEdit, bool &showDefer)

bool	reminderActive () const

bool	reminderDeferral () const

int	reminderMinutes () const

bool	reminderOnceOnly () const

void	removeExpiredAlarm (KAAlarm::Type type)

bool	repeatAtLogin (bool includeArchived=false) const

bool	repeatSound () const

int	repeatSoundPause () const

Repetition	repetition () const

QString	repetitionText (bool brief=false) const

int	revision () const

void	set (const KCalCore::Event::Ptr &)

void	set (const KDateTime &dt, const QString &text, const QColor &bg, const QColor &fg, const QFont &font, SubAction action, int lateCancel, Flags flags, bool changesPending=false)

void	setActions (const QString &pre, const QString &post, ExtraActionOptions options)

void	setActions (const QString &pre, const QString &post, bool cancelOnError, bool dontShowError)

void	setArchive ()

void	setAudioFile (const QString &filename, float volume, float fadeVolume, int fadeSeconds, int repeatPause=-1, bool allowEmptyFile=false)

void	setAutoClose (bool autoclose)

void	setCategory (CalEvent::Type type)

void	setCollectionId (Akonadi::Collection::Id id)

void	setCollectionId_const (Akonadi::Collection::Id id) const

void	setCommandError (CmdErrType error) const

void	setCompatibility (KACalendar::Compat c)

void	setCreatedDateTime (const KDateTime &dt)

void	setDeferDefaultMinutes (int minutes, bool dateOnly=false)

bool	setDisplaying (const KAEvent &event, KAAlarm::Type type, Akonadi::Collection::Id colId, const KDateTime &repeatAtLoginTime, bool showEdit, bool showDefer)

void	setEmail (uint from, const KCalCore::Person::List &, const QString &subject, const QStringList &attachments)

void	setEnabled (bool enable)

void	setEventId (const QString &id)

void	setExcludeHolidays (bool exclude)

void	setFirstRecurrence ()

void	setItemId (Akonadi::Item::Id id)

bool	setItemPayload (Akonadi::Item &, const QStringList &collectionMimeTypes) const

void	setKMailSerialNumber (unsigned long n)

void	setLateCancel (int minutes)

void	setLogFile (const QString &logfile)

OccurType	setNextOccurrence (const KDateTime &preDateTime)

void	setNoRecur ()

void	setReadOnly (bool ro)

bool	setRecurAnnualByDate (int freq, const QVector< int > &months, int day, KARecurrence::Feb29Type, int count, const QDate &end)

bool	setRecurAnnualByPos (int freq, const QVector< MonthPos > &pos, const QVector< int > &months, int count, const QDate &end)

bool	setRecurDaily (int freq, const QBitArray &days, int count, const QDate &end)

bool	setRecurMinutely (int freq, int count, const KDateTime &end)

bool	setRecurMonthlyByDate (int freq, const QVector< int > &days, int count, const QDate &end)

bool	setRecurMonthlyByPos (int freq, const QVector< MonthPos > &pos, int count, const QDate &end)

void	setRecurrence (const KARecurrence &r)

bool	setRecurWeekly (int freq, const QBitArray &days, int count, const QDate &end)

void	setReminder (int minutes, bool onceOnly)

void	setRepeatAtLogin (bool repeat)

bool	setRepetition (const Repetition &r)

void	setTemplate (const QString &name, int afterTime=-1)

void	setTime (const KDateTime &dt)

void	setWorkTimeOnly (bool wto)

float	soundVolume () const

bool	speak () const

void	startChanges ()

DateTime	startDateTime () const

int	templateAfterTime () const

QString	templateName () const

bool	toBeArchived () const

bool	updateKCalEvent (const KCalCore::Event::Ptr &event, UidAction u, bool setCustomProperties=true) const

bool	useDefaultFont () const

bool	usingDefaultTime () const

bool	workTimeOnly () const

Static Public Member Functions
static void	adjustStartOfDay (const KAEvent::List &events)

static bool	convertKCalEvents (const KCalCore::Calendar::Ptr &, int calendarVersion)

static int	currentCalendarVersion ()

static QByteArray	currentCalendarVersionString ()

static QString	joinEmailAddresses (const KCalCore::Person::List &addresses, const QString &sep)

static List	ptrList (QVector< KAEvent > &events)

static void	setDefaultFont (const QFont &font)

static void	setHolidays (const KHolidays::HolidayRegion &region)

static void	setStartOfDay (const QTime &)

static void	setWorkTime (const QBitArray &days, const QTime &start, const QTime &end)

Detailed Description

KAEvent represents a KAlarm event.

KAEvent represents a KAlarm event. An event contains a main alarm together with optional subsidiary alarms such as reminders and deferrals. Individual alarms are represented by the KAAlarm class. KAEvent includes the complete definition of the event including recurrence information, and also holds current status information such as the next due occurrence and command execution error status. It provides methods to set and get the event properties, to defer the alarm, to convert it for storage in the displaying calendar.

Methods which act globally or on multiple KAEvent instances include convertKCalEvents() which converts events stored in an older KAlarm calendar format to the current format; setStartOfDay() and adjustStartOfDay() which set a new start-of-day time for date-only alarms; setHolidays() and setWorkTime() which set holiday region and working days/hours.

Author: David Jarvie djarv.nosp@m.ie@k.nosp@m.de.or.nosp@m.g

Definition at line 210 of file kaevent.h.

Member Typedef Documentation

typedef QVector<KAEvent*> KAlarmCal::KAEvent::List

A list of pointers to KAEvent objects.

Definition at line 214 of file kaevent.h.

Member Enumeration Documentation

enum KAlarmCal::KAEvent::Actions

The basic action type(s) for the event's main alarm.

Values may be combined by OR'ing them together.

Enumerator
ACT_NONE	invalid
ACT_DISPLAY	the alarm displays something
ACT_COMMAND	the alarm executes a command
ACT_EMAIL	the alarm sends an email
ACT_AUDIO	the alarm plays an audio file (without any display)
ACT_DISPLAY_COMMAND	the alarm displays command output
ACT_ALL	all types mask

Definition at line 244 of file kaevent.h.

enum KAlarmCal::KAEvent::CmdErrType

Command execution error type for last time the alarm was triggered.

Enumerator
CMD_NO_ERROR	no error
CMD_ERROR	command alarm execution failed
CMD_ERROR_PRE	pre-alarm command execution failed
CMD_ERROR_POST	post-alarm command execution failed

Definition at line 309 of file kaevent.h.

enum KAlarmCal::KAEvent::DeferLimitType

What type of occurrence currently limits how long the alarm can be deferred.

Enumerator
LIMIT_NONE	there is no limit
LIMIT_MAIN	the main alarm
LIMIT_RECURRENCE	a recurrence
LIMIT_REPETITION	a sub-repetition
LIMIT_REMINDER	a reminder

Definition at line 289 of file kaevent.h.

enum KAlarmCal::KAEvent::ExtraActionOption

Options for pre- or post-alarm actions.

These may be OR'ed together.

Since: 4.9

Enumerator
CancelOnPreActError	cancel alarm on pre-alarm action error
DontShowPreActError	do not notify pre-alarm action errors to user
ExecPreActOnDeferral	execute pre-alarm action also for deferred alarms

Definition at line 321 of file kaevent.h.

enum KAlarmCal::KAEvent::Flag

Flags for use in D-Bus calls, etc.

Flags may be combined by OR'ing them together.

Enumerator
BEEP	sound an audible beep when the alarm is displayed
REPEAT_AT_LOGIN	repeat the alarm at every login
ANY_TIME	only a date is specified for the alarm, not a time
CONFIRM_ACK	closing the alarm message window requires a confirmation prompt
EMAIL_BCC	blind copy the email to the user
DEFAULT_FONT	use the default alarm message font
REPEAT_SOUND	repeat the sound file while the alarm is displayed
DISABLED	the alarm is currently disabled
AUTO_CLOSE	auto-close the alarm window after the late-cancel period
SCRIPT	the command is a script, not a shell command line
EXEC_IN_XTERM	execute the command in a terminal window
SPEAK	speak the message when the alarm is displayed
COPY_KORGANIZER	KOrganizer should hold a copy of the event.
EXCL_HOLIDAYS	don't trigger the alarm on holidays
WORK_TIME_ONLY	trigger the alarm only during working hours
DISPLAY_COMMAND	display command output in the alarm window
REMINDER_ONCE	only trigger the reminder on the first recurrence

Definition at line 217 of file kaevent.h.

enum KAlarmCal::KAEvent::OccurOption

How to treat sub-repetitions in nextOccurrence().

Enumerator
IGNORE_REPETITION	check for recurrences only, ignore sub-repetitions
RETURN_REPETITION	return a sub-repetition if it's the next occurrence
ALLOW_FOR_REPETITION	if a sub-repetition is the next occurrence, return the previous recurrence, not the sub-repetition

Definition at line 281 of file kaevent.h.

enum KAlarmCal::KAEvent::OccurType

What type of occurrence is due.

Enumerator
NO_OCCURRENCE	no occurrence is due
FIRST_OR_ONLY_OCCURRENCE	the first occurrence (takes precedence over LAST_RECURRENCE)
RECURRENCE_DATE	a recurrence with only a date, not a time
RECURRENCE_DATE_TIME	a recurrence with a date and time
LAST_RECURRENCE	the last recurrence
OCCURRENCE_REPEAT	(bitmask for a sub-repetition of an occurrence)
FIRST_OR_ONLY_OCCURRENCE_REPEAT	a sub-repetition of the first occurrence
RECURRENCE_DATE_REPEAT	a sub-repetition of a date-only recurrence
RECURRENCE_DATE_TIME_REPEAT	a sub-repetition of a date/time recurrence
LAST_RECURRENCE_REPEAT	a sub-repetition of the last recurrence

Definition at line 266 of file kaevent.h.

enum KAlarmCal::KAEvent::SubAction

The sub-action type for the event's main alarm.

Enumerator
MESSAGE	display a message text
FILE	display the contents of a file
COMMAND	execute a command
EMAIL	send an email
AUDIO	play an audio file

Definition at line 256 of file kaevent.h.

enum KAlarmCal::KAEvent::TriggerType

Alarm trigger type.

Enumerator
ALL_TRIGGER	next trigger, including reminders, ignoring working hours & holidays
MAIN_TRIGGER	next trigger, excluding reminders, ignoring working hours & holidays
WORK_TRIGGER	next main working time trigger, excluding reminders
ALL_WORK_TRIGGER	next actual working time trigger, including reminders
DISPLAY_TRIGGER	next trigger time for display purposes (i.e. excluding reminders)

Definition at line 299 of file kaevent.h.

enum KAlarmCal::KAEvent::UidAction

How to deal with the event UID in updateKCalEvent().

Enumerator
UID_IGNORE	leave KCal::Event UID unchanged
UID_CHECK	verify that the KCal::Event UID is already the same as the KAEvent ID, if the latter is non-empty
UID_SET	set the KCal::Event UID to the KAEvent ID

Definition at line 330 of file kaevent.h.

Constructor & Destructor Documentation

KAlarmCal::KAEvent::KAEvent ( )

Default constructor which creates an invalid event.

KAlarmCal::KAEvent::KAEvent	(	const KDateTime &	dt,
		const QString &	text,
		const QColor &	bg,
		const QColor &	fg,
		const QFont &	f,
		SubAction	action,
		int	lateCancel,
		Flags	flags,
		bool	changesPending = `false`
	)

Construct an event and initialise with the specified parameters.

Parameters

dt	start date/time.
text	alarm message (`action` = MESSAGE); file to display (`action` = FILE); command to execute (`action` = COMMAND); email body (`action` = EMAIL); audio file (`action` = AUDIO).
bg	background color (for display alarms, ignored otherwise).
fg	foreground color (for display alarms, ignored otherwise).
font	font (for display alarms, ignored otherwise).
action	alarm action type.
lateCancel	late-cancellation period (minutes), else 0.
flags	OR of Flag enum values.
changesPending	true to inhibit automatic calculations and data updates until further changes have been applied to the instance; call endChanges() when changes are complete.

Definition at line 607 of file kaevent.cpp.

KAlarmCal::KAEvent::KAEvent ( const KCalCore::Event::Ptr & e )

explicit

Construct an event and initialise it from a KCalCore::Event.

Definition at line 622 of file kaevent.cpp.

Member Function Documentation

KAEvent::SubAction KAlarmCal::KAEvent::actionSubType ( ) const

Return the action sub-type of the event's main alarm.

For display alarms, this is MESSAGE or FILE, while other types of alarm simply return the basic action type (COMMAND, EMAIL, AUDIO). Note that for a display alarm whose text is generated by a command, the returned type is COMMAND.

Definition at line 1987 of file kaevent.cpp.

KAEvent::Actions KAlarmCal::KAEvent::actionTypes ( ) const

Return the OR of the basic action types of the event's main alarm (display, command, email, audio).

Note that for a display alarm whose text is generated by a command, the returned type is ACT_DISPLAY|ACT_COMMAND.

Definition at line 1992 of file kaevent.cpp.

void KAlarmCal::KAEvent::activateReminderAfter ( const DateTime & mainAlarmTime )

If there is a reminder which occurs AFTER the main alarm, activate the event's reminder which occurs after the given main alarm time.

If there is no reminder after the main alarm, this method does nothing.

Returns: true if successful (i.e. reminder falls before the next main alarm).

Definition at line 2458 of file kaevent.cpp.

void KAlarmCal::KAEvent::adjustStartOfDay ( const KAEvent::List & events )

static

Call when the user changes the start-of-day time, to adjust the data for each date-only event in a list.

Parameters

events list of events. Any date-time events in the list are ignored.

See also: setStartOfDay()

Definition at line 2797 of file kaevent.cpp.

KAAlarm KAlarmCal::KAEvent::alarm ( KAAlarm::Type type ) const

Return the alarm of a specified type.

Parameters

type	alarm type to return.

See also: nextAlarm(), alarmCount()

Definition at line 3796 of file kaevent.cpp.

int KAlarmCal::KAEvent::alarmCount ( ) const

Return the number of alarms in the event, i.e.

the count of:

main alarm
repeat-at-login alarm
deferral alarm
reminder alarm
displaying alarm

Definition at line 3941 of file kaevent.cpp.

QString KAlarmCal::KAEvent::audioFile ( ) const

Return the audio file path.

See also: setAudioFile()

Definition at line 2312 of file kaevent.cpp.

bool KAlarmCal::KAEvent::autoClose ( ) const

Return whether auto-close is enabled, i.e.

whether the alarm window will be closed on expiry of the late-cancellation time. Note that auto-close will only operate if in addition to being enabled, late-cancel is also set.

Returns: true if it is a display alarm and auto-close is enabled.

See also: lateCancel(), setAutoClose()

Definition at line 2024 of file kaevent.cpp.

bool KAlarmCal::KAEvent::beep ( ) const

Return whether a beep should sound when the alarm is displayed.

Definition at line 2342 of file kaevent.cpp.

QColor KAlarmCal::KAEvent::bgColour ( ) const

Return the message window background color, for a display alarm.

Definition at line 2060 of file kaevent.cpp.

void KAlarmCal::KAEvent::cancelDefer ( )

Cancel any deferral alarm which is pending.

See also: defer()

Definition at line 2656 of file kaevent.cpp.

bool KAlarmCal::KAEvent::cancelOnPreActionError ( ) const

Return whether the alarm is to be cancelled if the pre-alarm action fails.

See also: preAction(), setActions()

Deprecated:: Use preActionOptions() instead

Definition at line 2417 of file kaevent.cpp.

CalEvent::Type KAlarmCal::KAEvent::category ( ) const

Return the alarm category (active/archived/template, or displaying).

Definition at line 1885 of file kaevent.cpp.

QString KAlarmCal::KAEvent::cleanText ( ) const

Return the alarm's text.

Its significance depends on the type of alarm; alternatively, use message(), displayMessage(), fileName() or command(), which incorporate checks on alarm type.

Definition at line 2039 of file kaevent.cpp.

Akonadi::Collection::Id KAlarmCal::KAEvent::collectionId ( ) const

Return the ID of the Akonadi Collection which contains the event.

Definition at line 1921 of file kaevent.cpp.

QString KAlarmCal::KAEvent::command ( ) const

Return the command or script to execute, for a command alarm.

Returns: command, or empty if not a command alarm.

Definition at line 2085 of file kaevent.cpp.

bool KAlarmCal::KAEvent::commandDisplay ( ) const

Return whether the command output is to be displayed in an alarm message window.

Definition at line 2100 of file kaevent.cpp.

KAEvent::CmdErrType KAlarmCal::KAEvent::commandError ( ) const

Return the command execution error for the last time the alarm triggered.

Definition at line 2181 of file kaevent.cpp.

bool KAlarmCal::KAEvent::commandScript ( ) const

Return whether a command script is specified, for a command alarm.

Definition at line 2090 of file kaevent.cpp.

bool KAlarmCal::KAEvent::commandXterm ( ) const

Return whether to execute the command in a terminal window, for a command alarm.

Definition at line 2095 of file kaevent.cpp.

KACalendar::Compat KAlarmCal::KAEvent::compatibility ( ) const

Return the event's storage format compatibility compared to the current KAlarm calendar format.

Definition at line 1965 of file kaevent.cpp.

bool KAlarmCal::KAEvent::confirmAck ( ) const

Return whether alarm acknowledgement must be confirmed by the user, for a display alarm.

Definition at line 2198 of file kaevent.cpp.

KAAlarm KAlarmCal::KAEvent::convertDisplayingAlarm ( ) const

Return the original alarm which the displaying alarm refers to.

Note that the caller is responsible for ensuring that the event was a displaying event; this check is not made in convertDisplayingAlarm() since it is normally called after reinstateFromDisplaying(), which resets the instance so that displaying() returns false.

Definition at line 3765 of file kaevent.cpp.

bool KAlarmCal::KAEvent::convertKCalEvents	(	const KCalCore::Calendar::Ptr &	calendar,
		int	calendarVersion
	)

static

If a calendar was written by a previous version of KAlarm, do any necessary format conversions on the events to ensure that when the calendar is saved, no information is lost or corrupted.

Parameters

calendar	calendar whose events are to be converted.
calendarVersion	KAlarm calendar format version of `calendar`, in the format returned by KAlarmCal::Version(). The KDE 3.0.0 version 0.5.7 requires a special adjustment for summer time and should be passed negated (-507) to distinguish it from the KDE 3.0.1 version 0.5.7 which does not require the adjustment.

Returns: true if any conversions were done.

Definition at line 5240 of file kaevent.cpp.

bool KAlarmCal::KAEvent::copyToKOrganizer ( ) const

Return whether KOrganizer should hold a copy of the event.

Definition at line 2203 of file kaevent.cpp.

KDateTime KAlarmCal::KAEvent::createdDateTime ( ) const

Return the date/time the event was created, or saved in the archive calendar.

See also: setCreatedDateTime()

Definition at line 2832 of file kaevent.cpp.

int KAlarmCal::KAEvent::currentCalendarVersion ( )

static

Return the current KAlarm calendar storage format version.

Returns: version in the format returned by KAlarmCal::Version().

See also: currentCalendarVersionString()

Definition at line 446 of file kaevent.cpp.

QByteArray KAlarmCal::KAEvent::currentCalendarVersionString ( )

static

Return the current KAlarm calendar storage format version.

Returns: version as a string in the format "1.2.3".

See also: currentCalendarVersion()

Definition at line 445 of file kaevent.cpp.

QMap< QByteArray, QString > KAlarmCal::KAEvent::customProperties ( ) const

Return the original KCalCore::Event's custom properties in the source calendar.

Definition at line 1970 of file kaevent.cpp.

void KAlarmCal::KAEvent::defer	(	const DateTime &	dt,
		bool	reminder,
		bool	adjustRecurrence = `false`
	)

Defer the event to the specified time.

If the main alarm time has passed, the main alarm is marked as expired.

Parameters

dt	date/time to defer the event to
reminder	true if deferring a reminder alarm
adjustRecurrence	if true, ensure that the next scheduled recurrence is after the current time.

See also: cancelDefer(), deferred(), deferDateTime()

Definition at line 2522 of file kaevent.cpp.

DateTime KAlarmCal::KAEvent::deferDateTime ( ) const

Return the time at which the currently pending deferred alarm should trigger.

Returns: trigger time, or invalid if no deferral pending.

See also: defer(), deferred()

Definition at line 2682 of file kaevent.cpp.

bool KAlarmCal::KAEvent::deferDefaultDateOnly ( ) const

Return the default date-only setting used in the deferral dialog.

Definition at line 2750 of file kaevent.cpp.

int KAlarmCal::KAEvent::deferDefaultMinutes ( ) const

Return the default deferral interval used in the deferral dialog.

See also: setDeferDefaultMinutes()

Definition at line 2745 of file kaevent.cpp.

DateTime KAlarmCal::KAEvent::deferralLimit ( DeferLimitType * limitType = 0 ) const

Return the latest time which the alarm can currently be deferred to.

Parameters

limitType if non-null, pointer to variable which will be updated to hold the type of occurrence which currently limits the deferral.

Returns: deferral limit, or invalid if no limit

Definition at line 2690 of file kaevent.cpp.

bool KAlarmCal::KAEvent::deferred ( ) const

Return whether there is currently a deferred alarm pending.

See also: defer(), deferDateTime()

Definition at line 2677 of file kaevent.cpp.

bool KAlarmCal::KAEvent::displaying ( ) const

Return whether the alarm is currently being displayed, i.e.

is in the displaying calendar.

Definition at line 3788 of file kaevent.cpp.

QString KAlarmCal::KAEvent::displayMessage ( ) const

Return the message text for a display alarm.

Returns: message text, or empty if not a text display alarm.

Definition at line 2050 of file kaevent.cpp.

bool KAlarmCal::KAEvent::dontShowPreActionError ( ) const

Return whether the user should not be notified if the pre-alarm action fails.

Returns: true if the user will not be notified, false if the user will be notified

See also: preAction(), setActions()

Deprecated:: Use preActionOptions() instead

Definition at line 2422 of file kaevent.cpp.

void KAlarmCal::KAEvent::dumpDebug ( ) const

Output the event's data as debug output.

Definition at line 4044 of file kaevent.cpp.

KCalCore::Person::List KAlarmCal::KAEvent::emailAddressees ( ) const

Return the list of email addressees, including names, for an email alarm.

Definition at line 2233 of file kaevent.cpp.

QStringList KAlarmCal::KAEvent::emailAddresses ( ) const

Return a list of the email addresses, including names, for an email alarm.

Definition at line 2241 of file kaevent.cpp.

QString KAlarmCal::KAEvent::emailAddresses ( const QString & sep ) const

Return a string containing the email addressees, including names, for an email alarm.

Parameters

sep	separator string to insert between addresses.

Definition at line 2246 of file kaevent.cpp.

QStringList KAlarmCal::KAEvent::emailAttachments ( ) const

Return the list of file paths of the attachments, for an email alarm.

Definition at line 2275 of file kaevent.cpp.

QString KAlarmCal::KAEvent::emailAttachments ( const QString & sep ) const

Return the file paths of the attachments, as a string, for an email alarm.

Parameters

sep	string separator

Definition at line 2280 of file kaevent.cpp.

bool KAlarmCal::KAEvent::emailBcc ( ) const

Return whether to send a blind copy of the email to the sender, for an email alarm.

Definition at line 2285 of file kaevent.cpp.

uint KAlarmCal::KAEvent::emailFromId ( ) const

Return the email identity to be used as the sender, for an email alarm.

Returns: email UOID

Definition at line 2227 of file kaevent.cpp.

QString KAlarmCal::KAEvent::emailMessage ( ) const

Return the email message body, for an email alarm.

Returns: email body, or empty if not an email alarm

Definition at line 2222 of file kaevent.cpp.

QStringList KAlarmCal::KAEvent::emailPureAddresses ( ) const

Return the list of email addressees, excluding names, for an email alarm.

Definition at line 2260 of file kaevent.cpp.

QString KAlarmCal::KAEvent::emailPureAddresses ( const QString & sep ) const

Return a string containing the email addressees, excluding names, for an email alarm.

Parameters

sep	separator string to insert between addresses.

Definition at line 2265 of file kaevent.cpp.

QString KAlarmCal::KAEvent::emailSubject ( ) const

Return the email subject line, for an email alarm.

Definition at line 2270 of file kaevent.cpp.

bool KAlarmCal::KAEvent::enabled ( ) const

Return the enabled status of the alarm.

Definition at line 1801 of file kaevent.cpp.

void KAlarmCal::KAEvent::endChanges ( )

Call when a group of changes preceded by startChanges() is complete, to allow resultant updates to occur.

Definition at line 4020 of file kaevent.cpp.

bool KAlarmCal::KAEvent::expired ( ) const

Return whether the event has expired.

Returns: true if the event has expired and is currently being displayed, or it is an archived event.

Definition at line 1833 of file kaevent.cpp.

KAEvent::ExtraActionOptions KAlarmCal::KAEvent::extraActionOptions ( ) const

Return the pre- and post-alarm action options.

See also: preAction(), postAction(), setActions()

Since: 4.9

Definition at line 2412 of file kaevent.cpp.

int KAlarmCal::KAEvent::fadeSeconds ( ) const

Return the fade period in seconds, or 0 if no fade is specified.

See also: setAudioFile()

Definition at line 2327 of file kaevent.cpp.

float KAlarmCal::KAEvent::fadeVolume ( ) const

Return the initial volume which will fade to the final volume.

Returns: volume in range 0 - 1, or -1 if no fade specified.

See also: setAudioFile()

Definition at line 2322 of file kaevent.cpp.

QColor KAlarmCal::KAEvent::fgColour ( ) const

Return the message window foreground color, for a display alarm.

Definition at line 2065 of file kaevent.cpp.

QString KAlarmCal::KAEvent::fileName ( ) const

Return the path of the file whose contents are to be shown, for a display alarm.

Returns: file path, or empty if not a file display alarm.

Definition at line 2055 of file kaevent.cpp.

KAAlarm KAlarmCal::KAEvent::firstAlarm ( ) const

Return the main alarm for the event.

If the main alarm does not exist, one of the subsidiary ones is returned if possible. N.B. a repeat-at-login alarm can only be returned if it has been read from/ written to the calendar file.

See also: nextAlarm()

Definition at line 3877 of file kaevent.cpp.

KAEvent::Flags KAlarmCal::KAEvent::flags ( ) const

Return the OR of various Flag enum status values.

Definition at line 1838 of file kaevent.cpp.

QFont KAlarmCal::KAEvent::font ( ) const

Return the font to use for alarm message texts.

Definition at line 2080 of file kaevent.cpp.

bool KAlarmCal::KAEvent::holidaysExcluded ( ) const

Return whether the alarm is disabled on holiday dates.

See also: setExcludeHolidays()

Definition at line 2883 of file kaevent.cpp.

QString KAlarmCal::KAEvent::id ( ) const

Return the event's unique identifier.

Note that the UID is guaranteed to be unique only within the calendar containing the event.

Definition at line 1895 of file kaevent.cpp.

void KAlarmCal::KAEvent::incrementRevision ( )

Increment the revision number of the event (SEQUENCE property in iCalendar).

Definition at line 1900 of file kaevent.cpp.

bool KAlarmCal::KAEvent::isReadOnly ( ) const

Return the read-only status of the alarm.

Definition at line 1812 of file kaevent.cpp.

bool KAlarmCal::KAEvent::isTemplate ( ) const

Return whether the event is an alarm template.

See also: setTemplate()

Definition at line 2365 of file kaevent.cpp.

bool KAlarmCal::KAEvent::isValid ( ) const

Return whether the instance represents a valid event.

Definition at line 1791 of file kaevent.cpp.

bool KAlarmCal::KAEvent::isWorkingTime ( const KDateTime & dt ) const

Check whether a date/time is during working hours and/or holidays, depending on the flags set for the specified event.

Definition at line 2916 of file kaevent.cpp.

Akonadi::Item::Id KAlarmCal::KAEvent::itemId ( ) const

Return the ID of the Akonadi Item which contains the event.

Definition at line 1932 of file kaevent.cpp.

QString KAlarmCal::KAEvent::joinEmailAddresses	(	const KCalCore::Person::List &	addresses,
		const QString &	sep
	)

static

Concatenate a list of email addresses into a string.

Parameters

sep	separator string to insert between addresses.

Definition at line 2252 of file kaevent.cpp.

int KAlarmCal::KAEvent::lateCancel ( ) const

Get the late cancellation period.

This is how late the alarm can trigger after its scheduled time, before it will be cancelled.

Returns: period in minutes, or 0 if no late cancellation is specified

See also: setLateCancel()

Definition at line 2014 of file kaevent.cpp.

QString KAlarmCal::KAEvent::logFile ( ) const

Return the log file which command alarm output should be written to.

Returns: log file path, or empty if no log file.

Definition at line 2193 of file kaevent.cpp.

Duration KAlarmCal::KAEvent::longestRecurrenceInterval ( ) const

Return the longest interval which can occur between consecutive recurrences.

See also: recurInterval()

Definition at line 3235 of file kaevent.cpp.

DateTime KAlarmCal::KAEvent::mainDateTime ( bool withRepeats = false ) const

Return the next time the main alarm will trigger.

Parameters

withRepeats true to include sub-repetitions, false to exclude them.

See also: mainTime(), startDateTime(), setTime()

Definition at line 2766 of file kaevent.cpp.

DateTime KAlarmCal::KAEvent::mainEndRepeatTime ( ) const

Return the time at which the last sub-repetition of the main alarm will occur.

Returns: last sub-repetition time, or main alarm time if no sub-repetitions are configured.

Definition at line 2776 of file kaevent.cpp.

bool KAlarmCal::KAEvent::mainExpired ( ) const

Return whether the event's main alarm has expired.

If so, a deferral alarm will exist.

Definition at line 1828 of file kaevent.cpp.

QTime KAlarmCal::KAEvent::mainTime ( ) const

Return the time at which the main alarm will next trigger.

Sub-repetitions are ignored.

Definition at line 2771 of file kaevent.cpp.

QString KAlarmCal::KAEvent::message ( ) const

Return the message text for a display alarm, or the email body for an email alarm.

Returns: message/email text, or empty if not a display or email alarm.

Definition at line 2044 of file kaevent.cpp.

KAAlarm KAlarmCal::KAEvent::nextAlarm ( const KAAlarm & previousAlarm ) const

Return the next alarm for the event, after the specified alarm.

See also: firstAlarm()

Definition at line 3898 of file kaevent.cpp.

KAAlarm KAlarmCal::KAEvent::nextAlarm ( KAAlarm::Type previousType ) const

Return the next alarm for the event, after the specified alarm type.

See also: firstAlarm()

Definition at line 3903 of file kaevent.cpp.

KAEvent::OccurType KAlarmCal::KAEvent::nextOccurrence	(	const KDateTime &	preDateTime,
		DateTime &	result,
		OccurOption	option = `IGNORE_REPETITION`
	)		const

Get the date/time of the next occurrence of the event, after the specified date/time.

Parameters

result	date/time of next occurrence, or invalid date/time if none.
option	how/whether to make allowance for sub-repetitions.

See also: nextRepetition(), setNextOccurrence(), previousOccurrence(), occursAfter()

Definition at line 3527 of file kaevent.cpp.

int KAlarmCal::KAEvent::nextRepetition ( ) const

Return the count of the next sub-repetition which is due.

Returns: sub-repetition count (>=1), or 0 for the main recurrence.

See also: nextOccurrence()

Definition at line 3375 of file kaevent.cpp.

DateTime KAlarmCal::KAEvent::nextTrigger ( TriggerType type ) const

Return the next time the alarm will trigger.

Parameters

type	specifies whether to ignore reminders, working time restrictions, etc.

Definition at line 2807 of file kaevent.cpp.

bool KAlarmCal::KAEvent::occursAfter	(	const KDateTime &	preDateTime,
		bool	includeRepetitions
	)		const

Determine whether the event will occur after the specified date/time.

Parameters

includeRepetitions if true and the alarm has a sub-repetition, the method will return true if any sub-repetitions occur after preDateTime.

See also: nextOccurrence()

Definition at line 3410 of file kaevent.cpp.

QString KAlarmCal::KAEvent::postAction ( ) const

Return the shell command to execute after the display alarm is acknowledged.

See also: setActions()

Definition at line 2407 of file kaevent.cpp.

QString KAlarmCal::KAEvent::preAction ( ) const

Return the shell command to execute before the alarm is displayed.

Definition at line 2402 of file kaevent.cpp.

KAEvent::OccurType KAlarmCal::KAEvent::previousOccurrence	(	const KDateTime &	afterDateTime,
		DateTime &	result,
		bool	includeRepetitions = `false`
	)		const

Get the date/time of the last previous occurrence of the event, before the specified date/time.

Parameters

result	date/time of previous occurrence, or invalid date/time if none.
includeRepetitions	if true and the alarm has a sub-repetition, the last previous repetition is returned if appropriate.

See also: nextOccurrence()

Definition at line 3603 of file kaevent.cpp.

KAEvent::List KAlarmCal::KAEvent::ptrList ( QVector< KAEvent > & events )

static

Return a list of pointers to a list of KAEvent objects.

Definition at line 4035 of file kaevent.cpp.

int KAlarmCal::KAEvent::recurInterval ( ) const

Return the recurrence interval in units of the recurrence period type (minutes, days, etc).

See also: longestRecurrenceInterval()

Definition at line 3214 of file kaevent.cpp.

KARecurrence * KAlarmCal::KAEvent::recurrence ( ) const

Return the full recurrence data for the event.

Returns: recurrence data, or null if none.

See also: recurrenceText()

Definition at line 3206 of file kaevent.cpp.

QString KAlarmCal::KAEvent::recurrenceText ( bool brief = false ) const

Return the recurrence interval as text suitable for display.

Definition at line 3291 of file kaevent.cpp.

bool KAlarmCal::KAEvent::recurs ( ) const

Return whether the event recurs.

See also: recurType()

Definition at line 3196 of file kaevent.cpp.

KARecurrence::Type KAlarmCal::KAEvent::recurType ( ) const

Return the recurrence period type for the event.

Note that this does not test for repeat-at-login.

See also: recurInterval()

Definition at line 3201 of file kaevent.cpp.

void KAlarmCal::KAEvent::reinstateFromDisplaying	(	const KCalCore::Event::Ptr &	event,
		Akonadi::Collection::Id &	colId,
		bool &	showEdit,
		bool &	showDefer
	)

Reinstate the original event from the 'displaying' event.

This instance is initialised from the supplied displaying event, and appropriate adjustments are made to convert it back to the original pre-displaying state.

Parameters

event	the displaying event
colId	updated to the ID of the collection which originally contained the event
showEdit	updated to true if Edit button was displayed, else false
showDefer	updated to true if Defer button was displayed, else false

Definition at line 3726 of file kaevent.cpp.

bool KAlarmCal::KAEvent::reminderActive ( ) const

Return whether a reminder is currently due (before the next, or after the last, main alarm/recurrence).

See also: reminderDeferral()

Definition at line 2501 of file kaevent.cpp.

bool KAlarmCal::KAEvent::reminderDeferral ( ) const

Return whether there is currently a deferred reminder alarm pending.

Definition at line 2511 of file kaevent.cpp.

int KAlarmCal::KAEvent::reminderMinutes ( ) const

Return the number of minutes BEFORE the main alarm when a reminder alarm is set.

Returns: >0 if the reminder is before the main alarm; <0 if the reminder is after the main alarm; 0 if no reminder is configured.

See also: setReminder()

Definition at line 2496 of file kaevent.cpp.

bool KAlarmCal::KAEvent::reminderOnceOnly ( ) const

Return whether the reminder alarm is triggered only for the first recurrence.

See also: setReminder()

Definition at line 2506 of file kaevent.cpp.

void KAlarmCal::KAEvent::removeExpiredAlarm ( KAAlarm::Type type )

Remove the alarm of the specified type from the event.

This must only be called to remove an alarm which has expired, not to reconfigure the event.

Definition at line 3951 of file kaevent.cpp.

bool KAlarmCal::KAEvent::repeatAtLogin ( bool includeArchived = false ) const

Return whether the alarm repeats at login.

Parameters

includeArchived true to also test for archived repeat-at-login status, false to test only for a current repeat-at-login alarm.

See also: setRepeatAtLogin()

Definition at line 2871 of file kaevent.cpp.

bool KAlarmCal::KAEvent::repeatSound ( ) const

Return whether the sound file will be repeated indefinitely.

Definition at line 2332 of file kaevent.cpp.

int KAlarmCal::KAEvent::repeatSoundPause ( ) const

Return how many seconds to pause between repetitions of the sound file.

Returns: pause interval, or -1 if sound does not repeat.

Definition at line 2337 of file kaevent.cpp.

Repetition KAlarmCal::KAEvent::repetition ( ) const

Return the event's sub-repetition data.

See also: setRepetition(), repetitionText()

Definition at line 3370 of file kaevent.cpp.

QString KAlarmCal::KAEvent::repetitionText ( bool brief = false ) const

Return the repetition interval as text suitable for display.

Definition at line 3383 of file kaevent.cpp.

int KAlarmCal::KAEvent::revision ( ) const

Return the revision number of the event (SEQUENCE property in iCalendar).

Definition at line 1905 of file kaevent.cpp.

void KAlarmCal::KAEvent::set ( const KCalCore::Event::Ptr & e )

Initialise the instance from a KCalCore::Event.

Definition at line 757 of file kaevent.cpp.

void KAlarmCal::KAEvent::set	(	const KDateTime &	dt,
		const QString &	text,
		const QColor &	bg,
		const QColor &	fg,
		const QFont &	font,
		SubAction	action,
		int	lateCancel,
		Flags	flags,
		bool	changesPending = `false`
	)

Initialise the instance with the specified parameters.

Parameters

dt	start date/time
text	alarm message (`action` = MESSAGE); file to display (`action` = FILE); command to execute (`action` = COMMAND); email body (`action` = EMAIL); audio file (`action` = AUDIO)
bg	background color (for display alarms, ignored otherwise)
fg	background color (for display alarms, ignored otherwise)
font	font (for display alarms, ignored otherwise)
action	alarm action type
lateCancel	late-cancellation period (minutes), else 0
flags	OR of Flag enum values
changesPending	true to inhibit automatic data updates until further changes have been applied to the instance; call endChanges() when changes are complete.

Definition at line 1236 of file kaevent.cpp.

void KAlarmCal::KAEvent::setActions	(	const QString &	pre,
		const QString &	post,
		ExtraActionOptions	options
	)

Set the pre-alarm and post-alarm actions, and their options.

Parameters

pre	shell command to execute before the alarm is displayed
post	shell command to execute after the alarm is acknowledged
options	options for pre- or post-alarm actions

See also: preAction(), postAction(), cancelOnPreActionError(), dontShowPreActionError()

Since: 4.9

Definition at line 2385 of file kaevent.cpp.

void KAlarmCal::KAEvent::setActions	(	const QString &	pre,
		const QString &	post,
		bool	cancelOnError,
		bool	dontShowError
	)

Set the pre-alarm and post-alarm actions, and their options.

Parameters

pre	shell command to execute before the alarm is displayed
post	shell command to execute after the alarm is acknowledged
cancelOnError	true to cancel the alarm if the pre-alarm action fails
dontShowError	true to not notify the error if the pre-alarm action fails

See also: preAction(), postAction(), cancelOnPreActionError(), dontShowPreActionError()

Deprecated:: Use alternative form of setActions() instead.

Definition at line 2392 of file kaevent.cpp.

void KAlarmCal::KAEvent::setArchive ( )

Set the event to be archived when it expires or is deleted.

Normally this is set when the event has triggered at least once.

Definition at line 1818 of file kaevent.cpp.

void KAlarmCal::KAEvent::setAudioFile	(	const QString &	filename,
		float	volume,
		float	fadeVolume,
		int	fadeSeconds,
		int	repeatPause = `-1`,
		bool	allowEmptyFile = `false`
	)

Set the audio file related data for the event.

Parameters

filename	audio file path
volume	final volume (0 - 1), or -1 for default volume
fadeVolume	initial volume (0 - 1), or -1 for no fade
fadeSeconds	number of seconds to fade from `fadeVolume` to `volume`
repeatPause	number of seconds to pause between repetitions, or -1 if no repeat
allowEmptyFile	true to set the volume levels even if `filename` is empty

See also: audioFile(), soundVolume(), fadeVolume(), fadeSeconds()

Definition at line 2290 of file kaevent.cpp.

void KAlarmCal::KAEvent::setAutoClose ( bool autoclose )

Enable or disable auto-close for a display alarm, i.e.

whether the alarm window will be closed on expiry of the late-cancellation time. Note that auto-close will only take effect if the late-cancel option is also set.

See also: setLateCancel(), autoClose()

Definition at line 2019 of file kaevent.cpp.

void KAlarmCal::KAEvent::setCategory ( CalEvent::Type type )

Set the alarm category (active/archived/template, or displaying).

Definition at line 1871 of file kaevent.cpp.

void KAlarmCal::KAEvent::setCollectionId ( Akonadi::Collection::Id id )

Set the ID of the Akonadi Collection which contains the event.

Definition at line 1911 of file kaevent.cpp.

void KAlarmCal::KAEvent::setCollectionId_const ( Akonadi::Collection::Id id ) const

Set the ID of the Akonadi Collection which contains the event.

Warning: This is a const method, which means that any other instance which references the same shared data will also be updated. It is designed to be used when a KAEvent is being created from an Akonadi Item, to avoid unnecessary copying. Use with caution!

Definition at line 1916 of file kaevent.cpp.

void KAlarmCal::KAEvent::setCommandError ( CmdErrType error ) const

Set or clear the command execution error for the last time the alarm triggered.

Definition at line 2106 of file kaevent.cpp.

void KAlarmCal::KAEvent::setCompatibility ( KACalendar::Compat c )

Note the event's storage format compatibility compared to the current KAlarm calendar format.

Definition at line 1960 of file kaevent.cpp.

void KAlarmCal::KAEvent::setCreatedDateTime ( const KDateTime & dt )

Set the date/time the event was created, or saved in the archive calendar.

See also: createdDateTime()

Definition at line 2827 of file kaevent.cpp.

void KAlarmCal::KAEvent::setDefaultFont ( const QFont & font )

static

Set the global default font for alarm message texts.

Definition at line 2070 of file kaevent.cpp.

void KAlarmCal::KAEvent::setDeferDefaultMinutes	(	int	minutes,
		bool	dateOnly = `false`
	)

Set defaults for the deferral dialog.

Parameters

minutes	default number of minutes, or 0 to select time control.
dateOnly	true to select date-only by default.

See also: deferDefaultMinutes()

Definition at line 2671 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setDisplaying	(	const KAEvent &	event,
		KAAlarm::Type	type,
		Akonadi::Collection::Id	colId,
		const KDateTime &	repeatAtLoginTime,
		bool	showEdit,
		bool	showDefer
	)

Set the event to be a copy of the specified event, making the specified alarm the 'displaying' alarm.

The purpose of setting up a 'displaying' alarm is to be able to reinstate the alarm message in case of a crash, or to reinstate it should the user choose to defer the alarm. Note that even repeat-at-login alarms need to be saved in case their end time expires before the next login.

Parameters

event	the event to copy
type	the alarm type (main, reminder, deferred etc.)
colId	the ID of the collection which originally contained the event
repeatAtLoginTime	repeat-at-login time if `type` == AT_LOGIN_ALARM, else ignored
showEdit	whether the Edit button was displayed
showDefer	whether the Defer button was displayed

Returns: true if successful, false if alarm was not copied.

Definition at line 3667 of file kaevent.cpp.

void KAlarmCal::KAEvent::setEmail	(	uint	from,
		const KCalCore::Person::List &	addresses,
		const QString &	subject,
		const QStringList &	attachments
	)

Set the email related data for the event.

Definition at line 2209 of file kaevent.cpp.

void KAlarmCal::KAEvent::setEnabled ( bool enable )

Enable or disable the alarm.

Definition at line 1796 of file kaevent.cpp.

void KAlarmCal::KAEvent::setEventId ( const QString & id )

Set the event's unique identifier.

Note that the UID is guaranteed to be unique only within the calendar containing the event.

Definition at line 1890 of file kaevent.cpp.

void KAlarmCal::KAEvent::setExcludeHolidays ( bool exclude )

Enable or disable the alarm on holiday dates.

The currently selected holiday region determines which dates are holidays. Note that this option only has any effect for recurring alarms.

Parameters

exclude true to disable on holidays, false to enable

See also: holidaysExcluded(), setHolidays()

Definition at line 2876 of file kaevent.cpp.

void KAlarmCal::KAEvent::setFirstRecurrence ( )

Adjust the event date/time to the first recurrence of the event, on or after the event start date/time.

The event start date may not be a recurrence date, in which case a later date will be set.

Definition at line 3245 of file kaevent.cpp.

void KAlarmCal::KAEvent::setHolidays ( const KHolidays::HolidayRegion & region )

static

Set the holiday region to be used by all KAEvent instances.

Alarms which exclude holidays record the pointer to the holiday definition at the time their next trigger times were last calculated. The change in holiday definition pointer will cause their next trigger times to be recalculated.

Parameters

region the holiday region data. The data object must persist for the lifetime of the application, since this class just stores a pointer to region.

See also: setExcludeHolidays()

Definition at line 2895 of file kaevent.cpp.

void KAlarmCal::KAEvent::setItemId ( Akonadi::Item::Id id )

Set the ID of the Akonadi Item which contains the event.

Definition at line 1927 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setItemPayload	(	Akonadi::Item &	item,
		const QStringList &	collectionMimeTypes
	)		const

Initialise an Akonadi::Item with the event's data.

Note that the event is not updated with the Item ID.

Returns: true if successful; false if the event's category does not match the collection's mime types.

Definition at line 1943 of file kaevent.cpp.

void KAlarmCal::KAEvent::setLateCancel ( int minutes )

Set or clear the late-cancel option.

This determines whether the alarm will be cancelled if it is late in triggering.

Parameters

minutes late cancellation period in minutes, or 0 to clear

See also: lateCancel()

Definition at line 2005 of file kaevent.cpp.

void KAlarmCal::KAEvent::setLogFile ( const QString & logfile )

Set the log file to write command alarm output to.

Parameters

logfile log file path

Definition at line 2186 of file kaevent.cpp.

KAEvent::OccurType KAlarmCal::KAEvent::setNextOccurrence ( const KDateTime & preDateTime )

Set the date/time of the event to the next scheduled occurrence after a specified date/time, provided that this is later than its current date/time.

Any reminder alarm is adjusted accordingly. If the alarm has a sub-repetition, and a sub-repetition of a previous recurrence occurs after the specified date/time, that sub-repetition is set as the next occurrence.

See also: nextOccurrence()

Definition at line 3453 of file kaevent.cpp.

void KAlarmCal::KAEvent::setNoRecur ( )

Clear the event's recurrence and sub-repetition data.

See also: setRecurrence(), recurs()

Definition at line 2952 of file kaevent.cpp.

void KAlarmCal::KAEvent::setReadOnly ( bool ro )

Set the read-only status of the alarm.

Definition at line 1807 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setRecurAnnualByDate	(	int	freq,
		const QVector< int > &	months,
		int	day,
		KARecurrence::Feb29Type	feb29,
		int	count,
		const QDate &	end
	)

Set the recurrence to recur annually, on the specified day in each of the specified months.

Parameters

freq	how many years between recurrences.
months	which months of the year alarms should occur on.
day	day of month, or 0 to use event start date.
feb29	for a February 29th recurrence, when February 29th should recur in non-leap years.
count	number of occurrences, including first and last; = -1 to recur indefinitely; = 0 to use `end` instead.
end	= end date (set invalid to use `count` instead).

Returns: false if no recurrence was set up.

Definition at line 3124 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setRecurAnnualByPos	(	int	freq,
		const QVector< MonthPos > &	pos,
		const QVector< int > &	months,
		int	count,
		const QDate &	end
	)

Set the recurrence to recur annually, on the specified weekdays in the specified weeks of the specified months.

Parameters

freq	how many years between recurrences.
days	which days of the week/weeks of the month alarms should occur on.
months	which months of the year alarms should occur on.
count	number of occurrences, including first and last; = -1 to recur indefinitely; = 0 to use `end` instead.
end	= end date (set invalid to use `count` instead).

Returns: false if no recurrence was set up.

Definition at line 3151 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setRecurDaily	(	int	freq,
		const QBitArray &	days,
		int	count,
		const QDate &	end
	)

Set the recurrence to recur daily.

Parameters

freq	how many days between recurrences.
days	which days of the week alarms are allowed to occur on.
count	number of occurrences, including first and last; = -1 to recur indefinitely; = 0 to use `end` instead.
end	= end date (set invalid to use `count` instead).

Returns: false if no recurrence was set up.

Definition at line 3025 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setRecurMinutely	(	int	freq,
		int	count,
		const KDateTime &	end
	)

Set the recurrence to recur at a minutes interval.

Parameters

freq	how many minutes between recurrences.
count	number of occurrences, including first and last; = -1 to recur indefinitely; = 0 to use `end` instead.
end	= end date/time (set invalid to use `count` instead).

Returns: false if no recurrence was set up.

Definition at line 3007 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setRecurMonthlyByDate	(	int	freq,
		const QVector< int > &	days,
		int	count,
		const QDate &	end
	)

Set the recurrence to recur monthly, on the specified days within the month.

Parameters

freq	how many months between recurrences.
days	which days of the month alarms should occur on.
count	number of occurrences, including first and last; = -1 to recur indefinitely; = 0 to use `end` instead.
end	= end date (set invalid to use `count` instead).

Returns: false if no recurrence was set up.

Definition at line 3074 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setRecurMonthlyByPos	(	int	freq,
		const QVector< MonthPos > &	pos,
		int	count,
		const QDate &	end
	)

Set the recurrence to recur monthly, on the specified weekdays in the specified weeks of the month.

Parameters

freq	how many months between recurrences.
days	which days of the week/weeks of the month alarms should occur on.
count	number of occurrences, including first and last; = -1 to recur indefinitely; = 0 to use `end` instead.
end	= end date (set invalid to use `count` instead).

Returns: false if no recurrence was set up.

Definition at line 3098 of file kaevent.cpp.

void KAlarmCal::KAEvent::setRecurrence ( const KARecurrence & r )

Initialise the event's recurrence from a KARecurrence.

The event's start date/time is not changed.

See also: setRecurMinutely(), setRecurDaily(), setRecurWeekly(), setRecurMonthlyByDate(), setRecurMonthlyByPos(), setRecurAnnualByDate(), setRecurAnnualByPos(), setFirstRecurrence()

Definition at line 2973 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setRecurWeekly	(	int	freq,
		const QBitArray &	days,
		int	count,
		const QDate &	end
	)

Set the recurrence to recur weekly, on the specified weekdays.

Parameters

freq	how many weeks between recurrences.
days	which days of the week alarms are allowed to occur on.
count	number of occurrences, including first and last; = -1 to recur indefinitely; = 0 to use `end` instead.
end	= end date (set invalid to use `count` instead).

Returns: false if no recurrence was set up.

Definition at line 3054 of file kaevent.cpp.

void KAlarmCal::KAEvent::setReminder	(	int	minutes,
		bool	onceOnly
	)

Set an additional reminder alarm.

Parameters

minutes	number of minutes BEFORE the main alarm; if negative, the reminder will occur AFTER the main alarm. 0 = clear the reminder.
onceOnly	true to trigger a reminder only for the first recurrence.

See also: reminderMinutes(), reminderOnceOnly()

Definition at line 2431 of file kaevent.cpp.

void KAlarmCal::KAEvent::setRepeatAtLogin ( bool repeat )

Enable or disable repeat-at-login.

If repeat is true, any existing pre-alarm reminder, late-cancel and copy-to-KOrganizer will all be disabled.

See also: repeatAtLogin()

Definition at line 2840 of file kaevent.cpp.

bool KAlarmCal::KAEvent::setRepetition ( const Repetition & r )

Initialise the event's sub-repetition.

The repetition length is adjusted if necessary to fit the recurrence interval. If the event doesn't recur, the sub-repetition is cleared.

Returns: false if a non-daily interval was specified for a date-only recurrence.

See also: repetition()

Definition at line 3332 of file kaevent.cpp.

void KAlarmCal::KAEvent::setStartOfDay ( const QTime & startOfDay )

static

Set the start-of-day time used by all date-only alarms.

Note that adjustStartOfDay() should be called immediately after this, to adjust all events' internal data.

Definition at line 2784 of file kaevent.cpp.

void KAlarmCal::KAEvent::setTemplate	(	const QString &	name,
		int	afterTime = `-1`
	)

Set the event to be an alarm template.

Parameters

name	template's name
afterTime	number of minutes after default time to schedule alarm for, or -1 to not use 'time from now'

See also: isTemplate(), templateName()

Definition at line 2357 of file kaevent.cpp.

void KAlarmCal::KAEvent::setTime ( const KDateTime & dt )

Set the next time to trigger the alarm (excluding sub-repetitions).

Note that for a recurring event, this should match one of the recurrence times.

Definition at line 2760 of file kaevent.cpp.

void KAlarmCal::KAEvent::setWorkTime	(	const QBitArray &	days,
		const QTime &	start,
		const QTime &	end
	)

static

Set working days and times, to be used by all KAEvent instances.

Parameters

days	bits set to 1 for each working day. Array element 0 = Monday ... 6 = Sunday.
start	start time in working day.
end	end time in working day.

See also: setWorkTimeOnly(), isWorkingTime()

Definition at line 2937 of file kaevent.cpp.

void KAlarmCal::KAEvent::setWorkTimeOnly ( bool wto )

Enable or disable the alarm on non-working days and outside working hours.

Note that this option only has any effect for recurring alarms.

Parameters

exclude true to restrict to working time, false to enable any time

See also: workTimeOnly(), setWorkTime()

Definition at line 2900 of file kaevent.cpp.

float KAlarmCal::KAEvent::soundVolume ( ) const

Return the sound volume (the final volume if fade is specified).

Returns: volume in range 0 - 1, or -1 for default volume.

See also: setAudioFile()

Definition at line 2317 of file kaevent.cpp.

bool KAlarmCal::KAEvent::speak ( ) const

Return whether the displayed alarm text should be spoken.

Definition at line 2347 of file kaevent.cpp.

void KAlarmCal::KAEvent::startChanges ( )

Call before making a group of changes to the event, to avoid unnecessary calculation intensive recalculations of trigger times from being performed until all the changes have been applied.

When the changes are complete, endChanges() should be called to allow resultant updates to occur.

Definition at line 4011 of file kaevent.cpp.

DateTime KAlarmCal::KAEvent::startDateTime ( ) const

Return the start time for the event.

If the event recurs, this is the time of the first recurrence.

See also: mainDateTime()

Definition at line 2755 of file kaevent.cpp.

int KAlarmCal::KAEvent::templateAfterTime ( ) const

Return the number of minutes (>= 0) after the default alarm time which is specified in the alarm template.

If this is specified, an alarm based on this template wll have the "Time from now" radio button enabled in the alarm edit dialog.

Returns: minutes after the default time, or -1 if the template specifies a time of day or a date-only alarm.

Definition at line 2380 of file kaevent.cpp.

QString KAlarmCal::KAEvent::templateName ( ) const

Return the alarm template's name.

Returns: template name, or empty if not a template

See also: setTemplate()

Definition at line 2370 of file kaevent.cpp.

bool KAlarmCal::KAEvent::toBeArchived ( ) const

Return whether the event should be archived when it expires or is deleted.

Definition at line 1823 of file kaevent.cpp.

bool KAlarmCal::KAEvent::updateKCalEvent	(	const KCalCore::Event::Ptr &	event,
		UidAction	u,
		bool	setCustomProperties = `true`
	)		const

Update an existing KCalCore::Event with the KAEvent data.

Parameters

event	Event to update.
u	how to deal with the Event's UID.
setCustomProperties	if true, all the Event's existing custom properties are cleared and replaced with the KAEvent's custom properties. If false, the KCal::Event's non-KAlarm custom properties are left untouched.

Definition at line 1346 of file kaevent.cpp.

bool KAlarmCal::KAEvent::useDefaultFont ( ) const

Return whether to use the default font (as set by setDefaultFont()) for alarm message texts.

Definition at line 2075 of file kaevent.cpp.

bool KAlarmCal::KAEvent::usingDefaultTime ( ) const

Return whether the alarm template does not specify a time.

Returns: true if no time is specified, i.e. the normal default alarm time will be used, false if the template specifies a time.

Definition at line 2375 of file kaevent.cpp.

bool KAlarmCal::KAEvent::workTimeOnly ( ) const

Return whether the alarm is disabled on non-working days and outside working hours.

See also: setWorkTimeOnly()

Definition at line 2907 of file kaevent.cpp.

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

KAlarm Library

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

KAlarm Library

kdepimlibs API Reference

Search