kalarm/DESIGN.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   5   <title>KAlarm Design Notes</title>
   6   <meta content="KAlarm" name=description>
   7   <style type="text/css">
   8       body         { font-family: sans-serif }
   9       .eg          { color: green }
  10       .titlerow    { font-size: 1.2em; padding-top: 1em; padding-bottom: 0.5em; font-weight: bold }
  11       td           { vertical-align: top; padding-right: 1em; padding-top: 3px }
  12       th           { vertical-align: top; padding-right: 1em; padding-top: 0.3em; text-align: left }
  13       *#divided    { border: 1px transparent }
  14       tr.divided   { border: 1px transparent }
  15       td.cont      { padding-top: 0 }
  16   </style>
  17
  18 </head>
  19
  20 <body>
  21
  22 <h1>KAlarm Design Notes</h1>
  23
  24 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 <tt>KAEvent</tt> object and is stored as an iCalendar <tt>VEVENT</tt>. 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 <tt>KAAlarm</tt> objects.
  25
  26 <p>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.
  27
  28 <p>The limit for deferring an alarm is as follows. Note that reminders are not triggered for sub-repetitions, just recurrences.
  29 <table>
  30 <col id=divided><col id=divided><col id=divided>
  31 <tr><th>Recurs?</th><th>Sub-<br>repetition?</th><th>Reminder<br>type</th><th>Deferral limit</th></tr>
  32 <tr class=divided><td style="text-align: center"></td><td style="text-align: center"></td><td>-</td><td><li>No limit</td></tr>
  33 <tr class=divided><td style="text-align: center"></td><td style="text-align: center"></td><td>Before</td><td><li>Main alarm: no limit<br><li>Reminder: before main alarm</td></tr>
  34 <tr class=divided><td style="text-align: center"></td><td style="text-align: center"></td><td>After</td><td><li>Main alarm: no limit<br><li>Reminder: no limit</td></tr>
  35 <tr class=divided><td style="text-align: center">Y</td><td style="text-align: center"></td><td>-</td><td><li>Last recurrence: no limit<br><li>Other recurrences: before next recurrence</td></tr>
  36 <tr class=divided><td style="text-align: center">Y</td><td style="text-align: center"></td><td>Before</td><td><li>Main alarm last recurrence: no limit<br><li>Main alarm other recurrences: before next reminder</td></tr>
  37 <tr class=divided><td style="text-align: center">Y</td><td style="text-align: center"></td><td>After</td><td><li>Main alarm last recurrence: no limit<br><li>Main alarm other recurrences: before next recurrence<br><li>Reminder last recurrence: no limit<br><li>Reminder other recurrences: before next recurrence</td></tr>
  38 <tr class=divided><td style="text-align: center">Y</td><td style="text-align: center">Y</td><td>-</td><td><li>Last sub-repetition of last recurrence: no limit<br><li>Other occurrences: before next recurrence or sub-repetition</td></tr>
  39 <tr class=divided><td style="text-align: center">Y</td><td style="text-align: center">Y</td><td>Before</td><td><li>Main alarm last sub-repetition of last recurrence: no limit<br><li>Main alarm other occurrences: before next recurrence or sub-repetition or reminder<br><li>Reminder: before next recurrence</td></tr>
  40 <tr class=divided><td style="text-align: center">Y</td><td style="text-align: center">Y</td><td>After</td><td><li>Main alarm last sub-repetition of last recurrence: no limit<br><li>Main alarm other occurrences: before next recurrence or sub-repetition<br><li>Reminder: before next sub-repetition</td></tr>
  41 </table>
  42
  43 <h2>Calendar Storage</h2>
  44
  45 KAlarm uses the iCalendar format defined in RFC2445.
  46
  47 <p>The <tt>DTSTART</tt> property is always set as a date/time value, never a date-only value; a date-only event is indicated by the <tt>DATE</tt> parameter in the <tt>X-KDE-KALARM-FLAGS</tt> 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.
  48
  49 <p>The following <tt>VALARM</tt> components are stored within a <tt>VEVENT</tt>:
  50
  51 <table>
  52 <tr><th>Alarm type</th><th><tt>ACTION</tt><br>property</th><th>Description</th></tr>
  53 <tr><td>Main alarm</td><td><em>any</em></td><td>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.</td></tr>
  54 <tr><td>At-login alarm</td><td><em>any</em></td><td>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.</td></tr>
  55 <tr><td>Reminder alarm</td><td><tt>DISPLAY</tt></td><td>If a reminder is configured, and it is due before the next or only recurrence of the main alarm, this alarm triggers the reminder.</td></tr>
  56 <tr><td>Deferral alarm</td><td><tt>DISPLAY</tt></td><td>If the user has deferred an alarm (either the main alarm or a reminder), this alarm triggers at the deferral time.</td></tr>
  57 <tr><td>Audio alarm</td><td><tt>AUDIO</tt></td><td>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).</td></tr>
  58 <tr><td>Pre-alarm action alarm</td><td><tt>PROCEDURE</tt></td><td>If a pre-alarm action is configured, this alarm is set to trigger at the same time as the next due alarm.</td></tr>
  59 <tr><td>Post&#8209;alarm&nbsp;action&nbsp;alarm</td><td><tt>PROCEDURE</tt></td><td>If a post-alarm action is configured, this alarm is set to trigger at the same time as the next due alarm.</td></tr>
  60 <tr><td>Displaying alarm</td><td><tt>DISPLAY</tt></td><td>If an alarm is currently being displayed, this alarm held in the displaying calendar contains information necessary to redisplay the alarm window after a logout or crash.</td></tr>
  61 </table>
  62
  63 <p>Alarm trigger times are always set as an offset from the next or current recurrence of the main alarm as set in <tt>DTSTART</tt> (for a non-recurring alarm) or in the <tt>X-KDE-KALARM-NEXTRECUR</tt> property (for a recurring alarm). An offset is used because RFC2445 stipulates that if the <tt>TRIGGER</tt> 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.
  64
  65 <h3>Custom properties</h3>
  66
  67 Compliant with the iCalendar specification, KAlarm defines a number of custom fields prefixed by <tt>X-KDE-KALARM-</tt> for use in the calendar. These are listed here, together with their possible parameters. All properties are optional unless stated to be mandatory.
  68
  69 <p>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.</p>
  70
  71 <table>
  72
  73 <tr><td colspan=3 class=titlerow>Calendar-level custom properties</td></tr>
  74 <tr><td colspan=3>The following custom properties are used within a <tt>VCALENDAR</tt> element.</td></tr>
  75
  76     <tr><th align=left>Property&nbsp;&nbsp;&nbsp;&nbsp;</th><th>Parameter</th><th align=left>Description</th></tr>
  77     <tr><td colspan=2><tt>X-KDE-KALARM-VERSION</tt></td><td>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.</td></tr>
  78     <tr><td></td><td><em>version</em><tt></td><td>KAlarm calendar format version, in the format <em>n</em><tt>.</tt><em>n</em><tt>.</tt><em>n</em> . E.g. <tt class=eg>2.3.10</tt></td></tr>
  79
  80 <tr><td colspan=3 class=titlerow>Event-level custom properties</td></tr>
  81 <tr><td colspan=3>The following custom properties are used within a <tt>VEVENT</tt> element.</td></tr>
  82
  83     <tr><th align=left>Property</th><th>Parameter</th><th align=left>Description</th></tr>
  84     <tr><td colspan=2><tt>X-KDE-KALARM-TYPE</tt></td><td>Mandatory. Multiple parameters hold the alarm's type. The first two parameters are always in the following order:</td></tr>
  85     <tr><td></td><td><em>type</em></td><td>The event's type, one of <tt>ACTIVE</tt>, <tt>ARCHIVED</tt>, <tt>TEMPLATE</tt>, <tt>DISPLAYING</tt></td></tr>
  86     <tr><td class=cont></td><td class=cont><em>resource</em></td><td class=cont>The saved Akonadi collection ID, or KResources resource ID. Note that this is not the collection/resource which the event is in.</td></tr>
  87     <tr><td class=cont></td><td class=cont><tt>DEFER</tt></td><td class=cont>For an event in the displaying calendar, indicates that the Defer button should be shown in the alarm window. Optional.</td></tr>
  88     <tr><td class=cont></td><td class=cont><tt>EDIT</tt></td><td class=cont>For an event in the displaying calendar, indicates that the Edit button should be shown in the alarm window. Optional.</td></tr>
  89     <tr><td colspan=2><tt>X-KDE-KALARM-FLAGS</tt></td><td>Multiple parameters specify various properties of the event</td></tr>
  90     <tr><td></td><td><tt>DATE</tt></td><td>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 (<tt>DTSTART</tt>) without a time.</td></tr>
  91     <tr><td class=cont></td><td class=cont><tt>ACKCONF</tt></td><td class=cont>For a display alarm, when the user acknowledges the alarm (i.e. closes the alarm window), a confirmation prompt will be output</td></tr>
  92     <tr><td class=cont></td><td class=cont><tt>KORG</tt></td><td class=cont>The event was copied as an alarm to KOrganizer</td></tr>
  93     <tr><td class=cont></td><td class=cont><tt>EXHOLIDAYS</tt></td><td class=cont>The alarm will not trigger on holidays (as defined for the holiday region configured by the user)</td></tr>
  94     <tr><td class=cont></td><td class=cont><tt>WORKTIME</tt></td><td class=cont>The alarm will not trigger during working hours on working days (as configured by the user)</td></tr>
  95     <tr><td class=cont></td><td class=cont><tt>DEFER;</tt><em>interval</em></td><td class=cont>Records the default deferral parameters for the alarm, used when the Defer dialogue is displayed. <em>interval</em> holds the deferral interval in minutes, with an optional <tt>D</tt> suffix to specify a date-only deferral. E.g. <tt class=eg>DEFER;1440D</tt> = 1 day, date-only</td></tr>
  96     <tr><td class=cont></td><td class=cont><tt>LATECANCEL;</tt><em>interval</em></td><td class=cont>How late the alarm can trigger (in minutes) before it will be cancelled; default = 1 minute</td></tr>
  97     <tr><td class=cont></td><td class=cont><tt>LATECLOSE;</tt><em>interval</em></td><td class=cont>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.</td></tr>
  98     <tr><td class=cont></td><td class=cont><tt>TMPLAFTTIME;</tt><em>interval</em></td><td class=cont>For a template alarm, holds the value (in minutes) of the "After time" option</td></tr>
  99     <tr><td class=cont></td><td class=cont><tt>KMAIL;</tt><em>sernum</em></td><td class=cont>The KMail serial number of the email whose text forms the alarm message</td></tr>
 100     <tr><td class=cont></td><td class=cont><tt>BCC</tt></td><td class=cont>For an email alarm, the email will be blind copied to the user</td></tr>
 101     <tr><td class=cont></td><td class=cont><tt>REMINDER;<em>[</em><tt>ONCE;</tt><em>]interval</em></td><td class=cont>The reminder interval for the alarm: &lt; 0 for a reminder before the main alarm, &gt; 0 for a reminder after the main alarm. A suffix indicates the time units:  <tt>M</tt> = minutes, <tt>H</tt> = hours, <tt>D</tt> = days. E.g. <tt class=eg>-12M</tt>. If <tt>ONCE</tt> is specified, this indicates that the reminder should be shown only for the first recurrence.</td></tr>
 102     <tr><td class=cont></td><td class=cont><tt>LOGIN</tt></td><td class=cont>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)</td></tr>
 103     <tr><td class=cont></td><td class=cont><tt>ARCHIVE</tt></td><td class=cont>For an active alarm, indicates that the alarm has triggered at least once and should be archived when it expires or is deleted</td></tr>
 104
 105     <tr><td colspan=2><tt>X-KDE-KALARM-NEXTRECUR</tt></td><td>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</td></tr>
 106     <tr><td></td><td><em>date-time</em></td><td>The date and optional time, in the format <em>YYYYMMDD</em><tt>T</tt><em>HHMMSS</em> for a date/time alarm, or <em>YYYYMMDD</em> for a date-only alarm. E.g. <tt class=eg>19990131T120000</tt></td></tr>
 107     <tr><td colspan=2><tt>X-KDE-KALARM-REPEAT</tt></td><td>Used for an active alarm when its main alarm has expired, holds the alarm's sub-repetition information. (Normally, this is held in the main alarm.)</td></tr>
 108     <tr><td></td><td><em>interval</em><tt>:</tt><em>count</em></td><td>Sub-repetition interval (in minutes) and count</td></tr>
 109     <tr><td colspan=2><tt>X-KDE-KALARM-LOG</tt></td><td>The single parameter specifies where command alarm output should go; default = discard</td></tr>
 110     <tr><td></td><td><tt>xterm:</tt></td><td>Display command output in a terminal window</td></tr>
 111     <tr><td class=cont></td><td class=cont><tt>display:</tt></td><td class=cont>Display command output in an alarm window</td></tr>
 112     <tr><td class=cont></td><td class=cont><em>filename</em></td><td class=cont>Store command output in the specified file</td></tr>
 113
 114 <tr><td colspan=3 class=titlerow>Alarm-level custom properties</td></tr>
 115 <tr><td colspan=3>The following custom properties are used within a <tt>VALARM</tt> element.</td></tr>
 116
 117     <tr><th align=left>Property</th><th>Parameter</th><th align=left>Description</th></tr>
 118     <tr><td colspan=2><tt>X-KDE-KALARM-TYPE</tt></td><td>Multiple parameters hold information about the alarm's type. If this property is missing, the alarm is the "main" alarm for the event.</td></tr>
 119     <tr><td></td><td><tt>LOGIN</tt></td><td>The alarm should be triggered each time KAlarm starts up (normally at each login)</td></tr>
 120     <tr><td class=cont></td><td class=cont><tt>FILE</tt></td><td class=cont>For a display alarm, indicates that the alarm text holds the name of a file whose contents should form the alarm message</td></tr>
 121     <tr><td class=cont></td><td class=cont><tt>REMINDER</tt></td><td class=cont>The alarm is a subsidiary reminder alarm. If combined with <tt>DEFERRAL</tt> or <tt>DATE_DEFERRAL</tt>, the alarm is a deferred reminder alarm.</td></tr>
 122     <tr><td class=cont></td><td class=cont><tt>DEFERRAL</tt></td><td class=cont>The alarm is a subsidiary timed deferral alarm</td></tr>
 123     <tr><td class=cont></td><td class=cont><tt>DATE_DEFERRAL</tt></td><td class=cont>The alarm is a subsidiary date-only deferral alarm</td></tr>
 124     <tr><td class=cont></td><td class=cont><tt>PRE</tt></td><td class=cont>The alarm is a subsidiary pre-alarm action command, which is executed immediately before the main alarm</td></tr>
 125     <tr><td class=cont></td><td class=cont><tt>POST</tt></td><td class=cont>The alarm is a subsidiary post-alarm action command, which is executed immediately after the user acknowledges the main display alarm</td></tr>
 126     <tr><td class=cont></td><td class=cont><tt>SOUNDREPEAT</tt></td><td class=cont>For an audio alarm, indicates that the sound file should be repeated indefinitely</td></tr>
 127     <tr><td class=cont></td><td class=cont><tt>DISPLAYING</tt></td><td class=cont>The alarm is currently being displayed, i.e. in the displaying calendar</td></tr>
 128     <tr><td colspan=2><tt>X-KDE-KALARM-FLAGS</tt></td><td>Multiple parameters specify various properties of the alarm</td></tr>
 129     <tr><td></td><td><tt>HIDE</tt></td><td>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.</td></tr>
 130     <tr><td></td><td><tt>SPEAK</tt></td><td>For an audio alarm in an event whose main alarm is a display or command alarm, specifies that the alarm text should be spoken</td></tr>
 131     <tr><td class=cont></td><td class=cont><tt>ERRCANCEL</tt></td><td class=cont>For a command alarm containing a pre-alarm action, indicates that the alarm should be cancelled if the pre-alarm action fails</td></tr>
 132     <tr><td class=cont></td><td class=cont><tt>ERRNOSHOW</tt></td><td class=cont>For a command alarm containing a pre-alarm action, indicates that there should be no error notification if the pre-alarm action fails</td></tr>
 133     <tr><td class=cont></td><td class=cont><tt>EMAILID;</tt><em>uoid</em></td><td class=cont>For an email alarm, holds the email ID (the KDE email UOID) to use in the 'From' field.</td></tr>
 134     <tr><td colspan=2><tt>X-KDE-KALARM-NEXTREPEAT</tt></td><td>The single parameter holds the repetition count of the next due sub-repetition: 0 = the main recurrence, 1 = the first sub-repetition, etc.</td></tr>
 135     <tr><td></td><td><em>count</em></td><td>Repetition number</td></tr>
 136     <tr><td colspan=2><tt>X-KDE-KALARM-FONTCOLOR</tt></td><td>For a display alarm, holds the colours to use in the alarm message window</td></tr>
 137     <tr><td></td><td><em>[background][</em><tt>;</tt><em>foreground]</em></td><td>The optional background colour (default = white) and optional foreground colour (default = black)</td></tr>
 138     <tr><td colspan=2><tt>X-KDE-KALARM-VOLUME</tt></td><td>Holds volume settings for an audio alarm</td></tr>
 139     <tr><td></td><td><em>[volume][</em><tt>;</tt><em>fadevolume</em><tt>;</tt><em>fadeinterval]</em></td><td>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. <tt class=eg>0.75</tt> to set volume with no fade, <tt class=eg>;0.3;10</tt> for default volume with fade, <tt class=eg>0.75;0.3;10</tt> to specify volume and fade</td></tr>
 140 </table>
 141
 142 <h3>Custom status field values</h3>
 143
 144 The following custom parameter value is used in the <tt>STATUS</tt> property in <tt>VEVENT</tt>:
 145 <ul><li><tt>DISABLED</tt> - indicates that the individual event is disabled.</ul>
 146
 147 </body>