Description: KAlarm

# 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

## 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 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.
  No pause between repetitions: `X-KDE-KALARM-TYPE:SOUNDREPEAT`
  Pause (in seconds) between repetitions: `X-KDE-KALARM-TYPE:SOUNDREPEAT,pause`
- In subsidiary alarms, the following scheme is used. The reason for this scheme is that KCalendarCore::Alarm cannot set a snooze time of zero.
  No pause between repetitions: `REPEAT:-1` (`DURATION` is ignored)
  Pause between repetitions: `REPEAT:-2` with `DURATION` containing the pause interval.