KAlarmCal Design Notes

The terms "alarm" and "event" are often used interchangeably in the context of KAlarm (including in source code comments). Technically speaking, a KAlarm "alarm" is really an event which contains one or more alarms. Each event is held in a KAEvent object and is stored as an iCalendar VEVENT. Each event normally contains the "main" alarm together with other subsidiary alarms; subsidiary alarms are used to represent reminders, deferrals, sounds, at-login alarms, pre-alarm actions and post-alarm actions. However, if the "main" alarm has expired but a subsidiary alarm is still due (e.g. a deferral), the event may no longer contain the "main" alarm. Individual alarms in the event may be fetched as KAAlarm objects.

Repeat-at-login events do not allow a reminder before the alarm, late-cancellation, or copying to KOrganizer, since these are incompatible with an alarm with no fixed trigger time.

The limit for deferring an alarm is as follows. Note that reminders are not triggered for sub-repetitions, just recurrences.

Recurs? Sub-
repetition? Reminder
type Deferral limit

-
No limit

Before
Main alarm: no limit
Reminder: before main alarm

After
Main alarm: no limit
Reminder: no limit

Y -
Last recurrence: no limit
Other recurrences: before next recurrence

Y Before
Main alarm last recurrence: no limit
Main alarm other recurrences: before next reminder

Y After
Main alarm last recurrence: no limit
Main alarm other recurrences: before next recurrence
Reminder last recurrence: no limit
Reminder other recurrences: before next recurrence

Y Y -
Last sub-repetition of last recurrence: no limit
Other occurrences: before next recurrence or sub-repetition

Y Y Before
Main alarm last sub-repetition of last recurrence: no limit
Main alarm other occurrences: before next recurrence or sub-repetition or reminder
Reminder: before next recurrence

Y Y After
Main alarm last sub-repetition of last recurrence: no limit
Main alarm other occurrences: before next recurrence or sub-repetition
Reminder: before next sub-repetition

Recurs?	Sub- repetition?	Reminder type	Deferral limit
		-	No limit
		Before	Main alarm: no limit Reminder: before main alarm
		After	Main alarm: no limit Reminder: no limit
Y		-	Last recurrence: no limit Other recurrences: before next recurrence
Y		Before	Main alarm last recurrence: no limit Main alarm other recurrences: before next reminder
Y		After	Main alarm last recurrence: no limit Main alarm other recurrences: before next recurrence Reminder last recurrence: no limit Reminder other recurrences: before next recurrence
Y	Y	-	Last sub-repetition of last recurrence: no limit Other occurrences: before next recurrence or sub-repetition
Y	Y	Before	Main alarm last sub-repetition of last recurrence: no limit Main alarm other occurrences: before next recurrence or sub-repetition or reminder Reminder: before next recurrence
Y	Y	After	Main alarm last sub-repetition of last recurrence: no limit Main alarm other occurrences: before next recurrence or sub-repetition Reminder: before next sub-repetition

Calendar Storage

KAlarm uses the iCalendar format defined in RFC2445.

The DTSTART property is always set as a date/time value, never a date-only value; a date-only event is indicated by the DATE parameter in the X-KDE-KALARM-FLAGS property. This is necessary for two reasons: 1) to allow a time zone to be specified for a date-only event; 2) KAlarm allows the trigger time to float within the 24-hour period defined by the start-of-day time (which is user-dependent and therefore can't be written into the calendar) rather than midnight to midnight, and there is no RFC2445 conformant way to specify this.

The following VALARM components are stored within a VEVENT:

Alarm type ACTION
property Description

Main alarm any The main alarm. This is always present unless it is a recurring alarm and the last recurrence has already triggered, but a subsidiary alarm is still pending. Possible pending alarms are either sub-repetitions, a deferral, or a reminder after the main alarm.

At-login alarm any If the event is configured to trigger each time KAlarm starts up (normally at each login), this alarm has a trigger time in the past, which ensures that it always triggers at startup.

Reminder alarm DISPLAY If a reminder is configured, and it is due before the next or only recurrence of the main alarm, this alarm triggers the reminder.

Deferral alarm DISPLAY If the user has deferred an alarm (either the main alarm or a reminder), this alarm triggers at the deferral time.

Audio alarm AUDIO If it is a display event, and any type of sound is configured (beep, speaking or audio file), this alarm is set to trigger at the same time as the next due alarm (main, at-login, reminder, or deferral).
Special values of REPEAT may be used to specify that an audio file should be played repeatedly in a loop until the user clicks 'stop': see Audio file loop below.
Pre-alarm action alarm PROCEDURE If a pre-alarm action is configured, this alarm is set to trigger at the same time as the next due alarm.

Post‑alarm action alarm PROCEDURE If a post-alarm action is configured, this alarm is set to trigger at the same time as the next due alarm.

Displaying alarm DISPLAY If an alarm is currently being displayed, this alarm held in the displaying calendar contains a copy of the main alarm, plus other information necessary to redisplay the alarm window after a logout or crash.

Alarm type	`ACTION` property	Description
Main alarm	any	The main alarm. This is always present unless it is a recurring alarm and the last recurrence has already triggered, but a subsidiary alarm is still pending. Possible pending alarms are either sub-repetitions, a deferral, or a reminder after the main alarm.
At-login alarm	any	If the event is configured to trigger each time KAlarm starts up (normally at each login), this alarm has a trigger time in the past, which ensures that it always triggers at startup.
Reminder alarm	`DISPLAY`	If a reminder is configured, and it is due before the next or only recurrence of the main alarm, this alarm triggers the reminder.
Deferral alarm	`DISPLAY`	If the user has deferred an alarm (either the main alarm or a reminder), this alarm triggers at the deferral time.
Audio alarm	`AUDIO`	If it is a display event, and any type of sound is configured (beep, speaking or audio file), this alarm is set to trigger at the same time as the next due alarm (main, at-login, reminder, or deferral). Special values of `REPEAT` may be used to specify that an audio file should be played repeatedly in a loop until the user clicks 'stop': see Audio file loop below.
Pre-alarm action alarm	`PROCEDURE`	If a pre-alarm action is configured, this alarm is set to trigger at the same time as the next due alarm.
Post‑alarm action alarm	`PROCEDURE`	If a post-alarm action is configured, this alarm is set to trigger at the same time as the next due alarm.
Displaying alarm	`DISPLAY`	If an alarm is currently being displayed, this alarm held in the displaying calendar contains a copy of the main alarm, plus other information necessary to redisplay the alarm window after a logout or crash.

Alarm trigger times are always set as an offset from the next or current recurrence of the main alarm as set in DTSTART (for a non-recurring alarm) or in the X-KDE-KALARM-NEXTRECUR property (for a recurring alarm). An offset is used because RFC2445 stipulates that if the TRIGGER property value is an absolute time, it must be a UTC date/time value, which is in general not suitable. Note that the main alarm's trigger offset must always be zero, because if it was non-zero, exception dates and rules would not work since they apply to the event time, not the alarm time.

Custom properties

Compliant with the iCalendar specification, KAlarm defines a number of custom fields prefixed by X-KDE-KALARM- for use in the calendar. These are listed here, together with their possible parameters. All properties are optional unless stated to be mandatory.

Note that in the iCalendar format, the property name is separated from its parameter(s) by a semi-colon. Multiple parameters are also semi-colon separated.

Calendar-level custom properties

The following custom properties are used within a VCALENDAR element.

Property Parameter Description

X-KDE-KALARM-VERSION Mandatory. The single parameter contains the KAlarm calendar format version used to write this calendar. Note that this version may be older than the actual KAlarm application version; the calendar format version is only updated when the calendar format changes.

version KAlarm calendar format version, in the format n.n.n . E.g. 2.3.10

Event-level custom properties

The following custom properties are used within a VEVENT element.

Property Parameter Description

X-KDE-KALARM-TYPE Mandatory. The parameter holds the event's type, in one of the following two forms:

type The event's type, one of ACTIVE, ARCHIVED, TEMPLATE, DISPLAYING

DISPLAYING;resource[;DEFER][;EDIT]

Specifies the event's type as DISPLAYING. The parameter's components are:

`resource`	The saved Akonadi collection ID, or KResources resource ID. Note that this is not the collection/resource which the event is in.
`DEFER`	For an event in the displaying calendar, indicates that the Defer button should be shown in the alarm window. Optional.
`EDIT`	For an event in the displaying calendar, indicates that the Edit button should be shown in the alarm window. Optional.

X-KDE-KALARM-FLAGS Multiple parameters specify various properties of the event

LOCAL The event time is specified using the local system time zone, and any TZID specifier in DTSTART is to be ignored. Note that this is used because the PIM libraries set the current local time zone as the TZID value when storing local times in the calendar.

DATE The event time is date-only, i.e. its time is ignored and it triggers at the first opportunity on the specified date (after the start-of-day time configured by the user). Note that this is used instead of specifying a start date (DTSTART) without a time.

ACKCONF For a display alarm, when the user acknowledges the alarm (i.e. closes the alarm window), a confirmation prompt will be output

KORG The event was copied as an alarm to KOrganizer

EXHOLIDAYS The alarm will not trigger on holidays (as defined for the holiday region configured by the user)

WORKTIME The alarm will not trigger during working hours on working days (as configured by the user)

DEFER;interval Records the default deferral parameters for the alarm, used when the Defer dialogue is displayed. interval holds the deferral interval in minutes, with an optional D suffix to specify a date-only deferral. E.g. DEFER;1440D = 1 day, date-only

LATECANCEL;interval How late the alarm can trigger (in minutes) before it will be cancelled; default = 1 minute

LATECLOSE;interval For a display alarm, how long after the trigger time (in minutes) until the alarm window is automatically closed; default = 1 minute. It will also be cancelled if it triggers after this time.

TMPLAFTTIME;interval For a template alarm, holds the value (in minutes) of the "After time" option

KMAIL;itemid The Akonadi Item ID of the email whose text forms the alarm message. The alarm message must be in the form From: ...\nTo: ...\n[Cc: ...\n]Date: ...\nSubject: ...

BCC For an email alarm, the email will be blind copied to the user

REMINDER;[ONCE;]interval The reminder interval for the alarm: < 0 for a reminder before the main alarm, > 0 for a reminder after the main alarm. A suffix indicates the time units: M = minutes, H = hours, D = days. E.g. -12M. If ONCE is specified, this indicates that the reminder should be shown only for the first recurrence.

LOGIN For an active alarm, when its main alarm has expired, records that the original alarm was triggered each time KAlarm started up (normally at each login)

NOTIFY For a display alarm, indicates that it should be displayed using the notification system instead of showing it in a window

ARCHIVE For an active alarm, indicates that the alarm has triggered at least once and should be archived when it expires or is deleted

X-KDE-KALARM-NEXTRECUR The single parameter records the next due recurrence date/time of the main alarm or, if sub-repetitions are still pending after the latest recurrence, the date/time of that recurrence

date-time The date and optional time, in the format YYYYMMDDTHHMMSS for a date/time alarm, or YYYYMMDD for a date-only alarm. E.g. 19990131T120000

X-KDE-KALARM-REPEAT Used for an active alarm when its main alarm has expired (e.g. when the last occurrence of the alarm has been deferred), holds the alarm's sub-repetition information. (Normally, this is held in the main alarm.)

interval:count Sub-repetition interval (in minutes) and count

X-KDE-KALARM-LOG The single parameter specifies where command alarm output should go; default = discard

xterm: Display command output in a terminal window

display: Display command output in an alarm window

filename Store command output in the specified file

Alarm-level custom properties

The following custom properties are used within a VALARM element.

Property Parameter Description

X-KDE-KALARM-TYPE Multiple parameters hold information about the alarm's type. If this property is missing, the alarm is the "main" alarm for the event.

LOGIN The alarm should be triggered each time KAlarm starts up (normally at each login)

FILE For a display alarm, indicates that the alarm text holds the name of a file whose contents should form the alarm message

REMINDER The alarm is a subsidiary reminder alarm. If combined with DEFERRAL or DATE_DEFERRAL, the alarm is a deferred reminder alarm.

DEFERRAL The alarm is a subsidiary timed deferral alarm

DATE_DEFERRAL The alarm is a subsidiary date-only deferral alarm

PRE The alarm is a subsidiary pre-alarm action command, which is executed immediately before the main alarm

POST The alarm is a subsidiary post-alarm action command, which is executed immediately after the user acknowledges the main display alarm

SOUNDREPEAT,pause For an audio alarm, indicates that the sound file should be played repeatedly in a loop until the user clicks 'stop', each time it triggers. The argument is the pause in seconds between repetitions. This is used only for "main" alarms: see Audio file loop below.

DISPLAYING The alarm is currently being displayed, i.e. in the displaying calendar

X-KDE-KALARM-FLAGS Multiple parameters specify various properties of the alarm

HIDE For an alarm of type REMINDER, indicates that it is suppressed by a deferral alarm whose trigger time is later than this alarm. Allows the reminder alarm to be reinstated if the deferral is subsequently cancelled.

SPEAK For an audio alarm in an event whose main alarm is a display or command alarm, specifies that the alarm text should be spoken

EXECDEFER For a command alarm containing a pre-alarm action, indicates that the pre-alarm action should be executed when a deferred alarm triggers. Normally, it is executed only when the alarm proper triggers.

ERRCANCEL For a command alarm containing a pre-alarm action, indicates that the alarm should be cancelled if the pre-alarm action fails

ERRNOSHOW For a command alarm (which is either the main alarm, or contains a pre-alarm action), indicates that there should be no error notification if the command fails

EMAILID;uoid For an email alarm, holds the email ID (the KDE email UOID) to use in the 'From' field.

X-KDE-KALARM-NEXTREPEAT The single parameter holds the repetition count of the next due sub-repetition: 0 = the main recurrence, 1 = the first sub-repetition, etc.

count Repetition number

X-KDE-KALARM-FONTCOLOR For a display alarm, holds the colours to use in the alarm message window

[background][;foreground] The optional background colour (default = white) and optional foreground colour (default = black)

X-KDE-KALARM-VOLUME Holds volume settings for an audio alarm

[volume][;fadevolume;fadeinterval] Contains the optional volume (floating point, range 0 - 1), and optionally the fade volume (floating point, range 0 - 1) and fade interval in seconds. E.g. 0.75 to set volume with no fade, ;0.3;10 for default volume with fade, 0.75;0.3;10 to specify volume and fade

Custom status field values

The following custom parameter value is used in the STATUS property in VEVENT:

DISABLED - indicates that the individual event is disabled.

Other

Audio file loop

An audio alarm (ACTION:AUDIO) can specify that each time the alarm triggers, the audio file should be played repeatedly in a loop until the user presses 'stop'. This is independent of the overall event recurrence or sub-repetition, and is indicated as follows.

In the "main" alarm, X-KDE-KALARM-TYPE:SOUNDREPEAT is used to specify sound file repetition, because the REPEAT and DURATION properties apply to the overall event.
In subsidiary alarms, the following scheme is used. The reason for this scheme is that KCalendarCore::Alarm cannot set a snooze time of zero.