diff options
Diffstat (limited to 'doc/kalarm/index.docbook')
| -rw-r--r-- | doc/kalarm/index.docbook | 4170 |
1 files changed, 4170 insertions, 0 deletions
diff --git a/doc/kalarm/index.docbook b/doc/kalarm/index.docbook new file mode 100644 index 00000000..28f44e78 --- /dev/null +++ b/doc/kalarm/index.docbook @@ -0,0 +1,4170 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kalarm;"> + <!ENTITY package "kdepim"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<!-- The language must NOT be changed here. --> + +<book lang="&language;"> + +<bookinfo> +<title>The &kalarm; Handbook</title> + +<authorgroup> +<author> +<firstname>David</firstname> +<surname>Jarvie</surname> +<affiliation> +<address><email>&David.Jarvie.mail;</email></address> +</affiliation> +</author> + +<othercredit role="developer"> +<firstname>David</firstname> +<surname>Jarvie</surname> +<affiliation><address><email>&David.Jarvie.mail;</email></address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2001</year><year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year><year>2007</year><year>2008</year> +<holder>David Jarvie</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Don't change format of date and version of the documentation --> + +<date>2008-01-23</date> +<releaseinfo>1.05.00</releaseinfo> + +<abstract> +<para>&kalarm; is a personal alarm message, command and email scheduler for &kde;.</para> +</abstract> + + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdepim</keyword> +<keyword>kalarm</keyword> +<keyword>alarm</keyword> +<keyword>reminder</keyword> +</keywordset> + +</bookinfo> + + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kalarm; lets you schedule the display of personal alarm +messages, the playing of sound files, the execution of commands and +the sending of emails.</para> + +<para>In its default graphical mode, &kalarm; displays the list of +pending alarms, showing their times and details. You can create new +alarms, or you can select existing alarms for modification or +deletion. You can also optionally view expired alarms.</para> + +<para>When configuring an alarm, you may either type in the alarm +message text, specify a text or image file to display, specify a +command to execute, or enter an email to send. You can also choose +the color of the alarm message, whether to play a sound or speak the +message, whether it should repeat, and whether the alarm should be +canceled if it cannot be triggered at its scheduled time.</para> + +<para>Alarms may also be scheduled from the command line, or via &DCOP; +calls from programs.</para> + +<para>When an alarm message is due, it is displayed on each &kde; +desktop to ensure that you don't miss it. The message window shows the +time for which the alarm was scheduled. It usually has a defer option +to ask for the alarm to be displayed again later. An example of an +alarm message:</para> + +<screenshot> +<screeninfo>Screenshot of the &kalarm; message window</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="alarmmessage.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Alarm message</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para>When the alarm specifies a command to execute or an email to +send, &kalarm; displays nothing.</para> + +<para>&kalarm; can run in either of two modes: +<quote>continuous</quote> (the default) where it runs from the +system tray, or <quote>on-demand</quote> where it runs as and when +required (with the option of displaying an independent system tray +icon).</para> + +<para>This document makes various references to the <application>alarm +daemon</application>. This is an application which runs in the +background, checking pending alarms and telling &kalarm; to display +them when they become due.</para> + +</chapter> + +<chapter id="using-kalarm"> +<title>Using &kalarm;</title> + +<para>When it is run with no command line parameters, &kalarm; starts +in graphical mode, and displays the current list of outstanding +alarms.</para> + +<para>When &kalarm; starts in graphical mode, it checks whether the +<application>alarm daemon</application> is running. If it is not +already running, &kalarm; starts it.</para> + +<tip><para>All spin boxes in &kalarm; have an acceleration facility. +To make the value change by larger steps, hold down the +<keycap>Shift</keycap> key while you click on the spin arrow +buttons.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="spinbox.png" format="PNG"/> +</imageobject> +</mediaobject> +</tip> + +<sect1 id="alarm-list"> +<title>Alarm list</title> + +<para>The main &kalarm; window displays the current list of pending +alarms, showing their times, repetition intervals, colors, and +message texts, names of files to display, commands to execute or email +subjects. (For a recurring alarm, the time shown is its next scheduled +trigger time. For an alarm with a reminder, the time shown is the time +of the alarm proper, not the reminder time.) An icon at the left of +each alarm text/file/command/email subject indicates the type of +alarm.</para> + +<screenshot> +<screeninfo>Screenshot of the &kalarm; main window</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mainwindow.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Main window</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para>For a repeated alarm, the list shows its next scheduled trigger +time and its basic repetition interval (⪚ <quote>1 Day</quote> for +a daily recurrence, <quote>3 Weeks</quote> for a recurrence which +triggers on Monday and Wednesday every third week, +<quote>Login</quote> for a repeat-at-login alarm).</para> + +<para>The alarms may be ordered by date/time, repeat interval, color, +type or text by clicking on the titlebar for the appropriate column. +To reverse the sort order, click the column titlebar again.</para> + +<para>You can optionally show the remaining time until each alarm is +due, together with, or instead of, the alarm's scheduled time. +To show or hide the alarm time column, select +<menuchoice><guimenu>View</guimenu><guimenuitem>Show Alarm +Times</guimenuitem></menuchoice>. +To show or hide the time-to-alarm column, select +<menuchoice><guimenu>View</guimenu><guimenuitem>Show Time To +Alarms</guimenuitem></menuchoice>. At least one of these columns is +always shown. You can use the +<link linkend="preferences-view">Preferences dialog</link> to change +the default columns to display.</para> + +<sect2 id="expired"> +<title>Expired alarms</title> + +<para>By default, &kalarm; stores alarms for a limited period once +they have expired or been deleted. (But note that alarms which you +delete are stored only if they have already triggered at least once.) +You can control whether &kalarm; stores expired alarms, and for how +long, in the +<link linkend="preferences-general">Preferences dialog</link>.</para> + +<para>Expired alarms may be shown in the alarm list by selecting +<menuchoice><guimenu>View</guimenu><guimenuitem>Show Expired +Alarms</guimenuitem></menuchoice>. To hide them again, repeat the +action. You can use the +<link linkend="preferences-view">Preferences dialog</link> to show +expired alarms by default.</para> + +</sect2> + +<sect2 id="search"> +<title>Searching the alarm list</title> + +<para>You can search through the alarm list to find alarms containing +a search text. To invoke this, select <menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Find</guimenuitem></menuchoice>. +In the search dialog, select the alarm types which you wish to search. +To continue searching for more alarms which match, use <menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice> +or <menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Find Previous</guimenuitem> +</menuchoice>.</para> + +<para>Searching is performed as follows:</para> + +<itemizedlist> +<listitem> +<para>Text alarms: the message text is searched.</para> +</listitem> + +<listitem> +<para>File alarms: the file path/URL is searched.</para> +</listitem> + +<listitem> +<para>Command alarms: the command line or command script is +searched.</para> +</listitem> + +<listitem> +<para>Email alarms: in addition to the subject and body of the email, +the recipients and the URLs of attachments are searched.</para> +</listitem> +</itemizedlist> + +<note><para>Only alarms currently shown in the alarm list can be +selected for searching. So if you want to search expired alarms, you +must first display them as described in the section above.</para></note> +</sect2> +</sect1> + +<sect1 id="create-edit"> +<title>Creating and manipulating alarms</title> + +<sect2> +<title>Creating a new alarm</title> + +<para>To create a new alarm, do one of the following. This displays +the <link linkend="alarm-edit-dlg">alarm edit dialog</link> through +which you configure the alarm.</para> + +<itemizedlist> +<listitem> +<para>Select <menuchoice><guimenu>Actions</guimenu> +<guimenuitem>New</guimenuitem></menuchoice>.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click on the system tray icon +and choose +<menuchoice><guimenuitem>New</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> + +<listitem> +<para>Click the <mousebutton>Middle</mousebutton> mouse button on the +system tray icon.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click in the alarm list and +choose <menuchoice><guimenuitem>New</guimenuitem></menuchoice> from +the context menu.</para> +</listitem> + +<listitem> +<para>Double click on empty space below the last entry in the alarm +list.</para> +</listitem> +</itemizedlist> + +<para>Alternatively, you can create new alarms preconfigured from +various sources:</para> + +<itemizedlist> +<listitem> +<para>To base your new alarm on an alarm template, follow the +instructions in the <link linkend="templates">Alarm templates</link> +section.</para> +</listitem> + +<listitem> +<para>To base your new alarm on an existing one, highlight the existing +alarm in the list and select <menuchoice> +<guimenu>Actions</guimenu><guimenuitem>Copy</guimenuitem></menuchoice>. +This opens the <link linkend="alarm-edit-dlg">alarm edit dialog</link> +already filled in with a copy of the selected alarm's details.</para> +</listitem> + +<listitem> +<para>To create a new alarm which displays an existing email message, +drag the email from &kmail; onto &kalarm;'s main window or system tray +icon. This opens the <link linkend="alarm-edit-dlg">alarm edit +dialog</link> with the entire email message (including sender, +recipient, etc.) as the alarm text.</para> +</listitem> + +<listitem> +<para>To create a new email alarm to send a copy of an existing email +message, drag the email from &kmail; onto &kalarm;'s main window or +system tray icon. Then select the <guilabel>Email</guilabel> option. +The <link linkend="alarm-edit-dlg">alarm edit dialog</link> is preset +with the entire email message except sender.</para> +</listitem> + +<listitem> +<para>Dragging any piece of text onto &kalarm;'s main window or system +tray icon opens the <link linkend="alarm-edit-dlg">alarm edit +dialog</link> and sets the alarm text.</para> +</listitem> + +<listitem> +<para>To create a file display alarm, drag a file URL onto &kalarm;'s +main window or system tray icon. This opens the +<link linkend="alarm-edit-dlg">alarm edit dialog</link> and sets the +file name.</para> +</listitem> + +<listitem> +<para>You can automatically create birthday alarms for people in +&kaddressbook; as described in <link linkend="birthdays">Importing +birthdays from &kaddressbook;</link>.</para> +</listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="edit-alarm"> +<title>Modifying an existing alarm</title> + +<para>To modify an existing pending alarm (expired alarms cannot be +amended), do one of the following:</para> + +<itemizedlist> +<listitem> +<para>Double click on its entry in the alarm list.</para> +</listitem> + +<listitem> +<para>Select it by clicking on its entry in the alarm list. Then +choose <menuchoice><guimenu>Actions</guimenu> +<guimenuitem>Edit</guimenuitem></menuchoice>.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click on its entry in the alarm +list and choose +<menuchoice><guimenuitem>Edit</guimenuitem></menuchoice> from the +context menu.</para> +</listitem> +</itemizedlist> + +<para>This displays the <link linkend="alarm-edit-dlg">alarm edit +dialog</link>.</para> + +</sect2> + +<sect2> +<title>Deleting/reactivating an alarm</title> + +<para>To delete existing alarms, do one of the following:</para> + +<itemizedlist> +<listitem> +<para>Select one or more alarms by clicking on their entries in the +alarm list. Then choose <menuchoice> +<guimenu>Actions</guimenu><guimenuitem>Delete</guimenuitem> +</menuchoice>.</para> +</listitem> +<listitem> +<para><mousebutton>Right</mousebutton> click on the desired entries in +the alarm list and choose +<menuchoice><guimenuitem>Delete</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> +</itemizedlist> + +<para>When you delete an active alarm, it is stored as an expired +alarm, provided that it has triggered at least once before being +deleted, and provided that expired alarms are stored at all. (Use the +<link linkend="preferences-general">Preferences dialog</link> to +control whether and for how long expired alarms are stored.) When you +delete an expired alarm, or an active alarm which has not yet +triggered, it is removed permanently.</para> + +<para>You can reactivate a deleted alarm from the expired alarms list, +provided that it has not yet expired. To do this, first display +expired alarms, as described in +<link linkend="expired">Expired alarms</link>. Then:</para> + +<itemizedlist> +<listitem> +<para>Select one or more appropriate expired alarms by clicking on +their entries in the alarm list. Then choose <menuchoice> +<guimenu>Actions</guimenu><guimenuitem>Reactivate</guimenuitem> +</menuchoice>.</para> +</listitem> +<listitem> +<para><mousebutton>Right</mousebutton> click on the desired entries in +the expired alarm list and choose +<menuchoice><guimenuitem>Reactivate</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Enabling/disabling an alarm</title> + +<para>See <link linkend="enable-disable">Enabling and disabling alarms</link> +for how to enable and disable alarms, either individually or as a whole.</para> + +</sect2> + +<sect2> +<title>Viewing an alarm</title> + +<para>To view an existing alarm without the ability to modify it, do +one of the following:</para> + +<itemizedlist> +<listitem> +<para>Select it by clicking on its entry in the alarm list. Then choose +<menuchoice> +<guimenu>Actions</guimenu><guimenuitem>View</guimenuitem> +</menuchoice>.</para> +</listitem> +<listitem> +<para><mousebutton>Right</mousebutton> click on its entry in the alarm +list and choose +<menuchoice><guimenuitem>View</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> +</itemizedlist> + +<para>This displays the <link linkend="alarm-edit-dlg">alarm edit +dialog</link> in read-only mode.</para> + +</sect2> + +<sect2> +<title>Acknowledging an alarm</title> + +<para>See <link linkend="message-window">Alarm message window</link> +for how to acknowledge alarms.</para> + +</sect2> + +<sect2 id="templates"> +<title>Alarm templates</title> + +<para>If you frequently want to set up similar alarms, you can create +an alarm template to avoid having to enter all the details from +scratch each time. A template can contain all the details which an +alarm can contain, apart from the start date.</para> + +<para>As an example, you may regularly want to set an +alarm to remind you about a television program whose time varies +from week to week. The template would contain all the alarm details +(message text, whether to play a sound, etc.) except for the time and +date. Now, to create the alarm, all you need to do is open the alarm +edit dialog with that template and then enter the time and +date.</para> + +<para>To create an alarm based on a template, open the +<link linkend="alarm-edit-dlg">alarm edit dialog</link> preset with +the template details:</para> + +<itemizedlist> +<listitem> +<para>Select the <menuchoice> +<guimenu>Actions</guimenu><guimenuitem>New From Template</guimenuitem> +</menuchoice> menu item, and then select the desired template.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click on the system tray icon +and choose +<menuchoice><guimenuitem>New Alarm From Template</guimenuitem></menuchoice> +from the context menu. Then select the desired template.</para> +</listitem> + +<listitem> +<para>Open the <link linkend="alarm-edit-dlg">alarm edit dialog</link> +in the usual way, and click the +<guibutton>Load Template...</guibutton> button to select a template to +preset the dialog with.</para> +</listitem> +</itemizedlist> + +<sect3> +<title>Configuring templates</title> + +<para>You can create, modify or delete templates using the Alarm +Templates dialog, or you can create a new alarm template based on an +existing alarm.</para> + +<para>To create a new alarm template, do one of the following:</para> + +<itemizedlist> +<listitem> +<para>Display the Alarm Templates dialog by selecting the <menuchoice> +<guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem> +</menuchoice> menu item, and click <guibutton>New</guibutton>. This +displays a blank template edit dialog.</para> +</listitem> + +<listitem> +<para>Display the Alarm Templates dialog by selecting the <menuchoice> +<guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem> +</menuchoice> menu item, select an existing template from the list and +click <guibutton>Copy</guibutton>. This opens the template edit dialog +already filled in with a copy of the existing template's +details.</para> +</listitem> + +<listitem> +<para>Highlight an alarm in the alarm list and select <menuchoice> +<guimenu>Actions</guimenu><guimenuitem>Create template</guimenuitem> +</menuchoice>. This opens the template edit dialog already filled in +with a copy of the selected alarm's details.</para> +</listitem> +</itemizedlist> + +<para>To modify an existing template, display the Alarm Templates +dialog by selecting the <menuchoice> +<guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem> +</menuchoice> menu item and click <guibutton>Edit</guibutton>. This +displays the template edit dialog which is described below.</para> + +<para>To delete existing templates, display the Alarm Templates +dialog by selecting the <menuchoice> +<guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem> +</menuchoice> menu item, select one or more templates and click +<guibutton>Delete</guibutton>. A confirmation prompt is issued to +prevent accidental deletions.</para> + +</sect3> + +<sect3> +<title>Template edit dialog</title> + +<para>The template edit dialog is similar to the +<link linkend="alarm-edit-dlg">alarm edit dialog</link>. The +following controls are different:</para> + +<itemizedlist> +<listitem> +<para>Enter the template's name in <guilabel>Template name</guilabel>. +It is the template's name which is displayed in template selection +lists, so it is best to choose a name which will remind you of its +function. Each template's name must be unique.</para> +</listitem> + +<listitem> +<para>In the <guilabel>Time</guilabel> group box, select one of:</para> + +<itemizedlist> +<listitem> +<para><guilabel>Default time</guilabel> if you do not wish to specify +any trigger time. Alarms based on this template will initially +use the normal default trigger time for new alarms.</para> +</listitem> + +<listitem> +<para><guilabel>Time</guilabel> to enter a time when the alarm is to +be triggered.</para> +</listitem> + +<listitem> +<para><guilabel>Any time</guilabel> to specify that the alarm should +only have a date, not a time.</para> +</listitem> + +<listitem> +<para><guilabel>Time from now</guilabel> to enter how long (in hours +and minutes) after the alarm is created, that it should be +triggered.</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para>In the <guilabel>Recurrence Rule</guilabel> group box in the +<guilabel>Recurrence</guilabel> tab, no day or month need be selected +for weekly or yearly recurrences, respectively.</para> +</listitem> +</itemizedlist> + +</sect3> + +</sect2> + +<sect2 id="import"> +<title>Importing alarms from external calendars</title> + +<para>You can import alarms from other calendar files into &kalarm;, +by <menuchoice><guimenu>File</guimenu> +<guimenuitem>Import Alarms...</guimenuitem></menuchoice>. The +import function scans the selected calendar file for events containing +alarms, and copies them (with new unique IDs) into &kalarm;'s calendar. +Events without alarms, and calendar entries other than events, are +ignored.</para> + +<warning><para>If you import alarms from calendar files which were +created by applications other than &kalarm;, the alarms may be changed +by the import process – even alarm times may change. This depends on +the data storage conventions used by the other application, and is +unavoidable if those conventions differ from what &kalarm; expects. +Always check imported alarms for unexpected changes, and adjust them +as necessary.</para></warning> + +</sect2> + +<sect2 id="birthdays"> +<title>Importing birthdays from &kaddressbook;</title> + +<para>You can set up display alarms for birthdays stored in +&kaddressbook;, by <menuchoice><guimenu>File</guimenu> +<guimenuitem>Import Birthdays...</guimenuitem></menuchoice>. This +displays a dialog which allows you to select which birthdays to create +alarms for.</para> + +<itemizedlist> +<listitem> +<para>In the <guilabel>Alarm Text</guilabel> group box, you can set up +the text to be displayed in the birthday alarm messages. The message +text is created by combining the <guilabel>Prefix</guilabel> text +followed by the person's name followed by the +<guilabel>Suffix</guilabel> text. No spaces are added, so remember to +include any necessary trailing space in <guilabel>Prefix</guilabel> +and leading space in <guilabel>Suffix</guilabel>.</para> + +<note><para>If you change the alarm text, the birthday selection list +will be re-evaluated.</para></note> +</listitem> + +<listitem> +<para>In the <guilabel>Select Birthdays</guilabel> list, select the +birthdays which you want to create alarms for. Note that the list +shows only those entries in &kaddressbook; which contain a birthday +and which do not already have a birthday alarm in the format currently +defined in the <guilabel>Alarm Text</guilabel> group box.</para> +</listitem> + +<listitem> +<para>The remaining controls are the same as for +<guilabel>Text</guilabel> alarms in the +<link linkend="alarm-edit-dlg">Alarm Edit dialog</link>.</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="undo"> +<title>Undo / redo</title> + +<para>You can undo and redo the most recent changes which you have +made during the current session of &kalarm;. Most actions can be +undone, including creation, edit and deletion of alarms and alarm +templates, and reactivation of alarms. To prevent excessive resources +being used by the undo history, the number of changes stored is +limited to the last 12.</para> + +<para>To undo the last change, select <menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Undo</guimenuitem></menuchoice>. +To redo the last change which was undone, select <menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Redo</guimenuitem> +</menuchoice>.</para> + +<para>To undo a change other than the last one, click on the +<guibutton>Undo</guibutton> button in the toolbar and hold the mouse +button down. A list of actions will be displayed from which you can +choose the one to undo. If you don't see the action which you are +looking for, remember that you may need to undo more recent changes +first, which the desired change depends on. For example, if you edited +an alarm and then deleted it, you cannot undo the edit until you have +first undone the deletion.</para> + +<para>Redoing a change other than the last one can be done in a +similar manner, using the <guibutton>Redo</guibutton> toolbar +button.</para> + +</sect2> +</sect1> + +<sect1 id="alarm-edit-dlg"> +<title>The alarm edit dialog</title> + +<para>The alarm edit dialog enables you to view and edit an +alarm.</para> + +<screenshot> +<screeninfo>Screenshot of the alarm edit dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="editwindow.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Alarm edit dialog</phrase> +</textobject> +</mediaobject> +</screenshot> + +<sect2> +<title>Alarm action</title> + +<para>In the <guilabel>Action</guilabel> group box, select the type +of alarm:</para> + +<itemizedlist> +<listitem> +<para><guilabel>Text</guilabel> in order to enter an alarm message text +(which may include newlines) in the edit box. Set the following +options:</para> + +<itemizedlist> +<listitem> +<para>The <guilabel>Sound</guilabel> option allows you to select +whether an audible alarm should sound when the alarm message is +displayed. Choose:</para> + +<itemizedlist> +<listitem> +<para><guilabel>None</guilabel> to display the alarm silently.</para> +</listitem> + +<listitem> +<para><guilabel>Beep</guilabel> to sound a beep.</para> +</listitem> + +<listitem> +<para><guilabel>Speak</guilabel> to have the alarm message spoken as +well as being displayed. This option is only available if you have +<application>KTTSD</application> (from the kdeaccessibility package) +installed and configured, together with a compatible speech +synthesizer, ⪚ <application>Festival</application>.</para> +</listitem> + +<listitem> +<para><guilabel>Sound file</guilabel> to play an audio file. Use the +button on the right to display the Sound File dialog which lets you +select a file to play and set volume and repetition options. If you +hover the mouse over the selector, a tooltip will display the audio file +currently selected.</para> + +<note><para>&kalarm; uses the &arts; sound server for repetition and +volume control. If &kalarm; has been built without &arts; support, +repetition and volume options will not be available and a simple sound +file selector will appear in place of the full Sound File +dialog.</para></note> + +<para>In the Sound File dialog:</para> + +<itemizedlist> +<listitem> +<para>Enter the sound file path, or use the button beside the +edit box to display a file selection dialog. You can listen to the +selected file by clicking the play button to the left of the edit +field. That button then changes function to allow you to stop playing +when you have heard enough.</para> +</listitem> + +<listitem> +<para>Check <guilabel>Repeat</guilabel> to continually repeat the +audio file for as long as the alarm is displayed. (The alarm message +window contains a button to stop playing the sound should you need +silence but still want to display the alarm.)</para> +</listitem> + +<listitem> +<para>Check <guilabel>Volume</guilabel> and adjust the slider +control if you want to adjust the volume at which the audio file is +played.</para> +</listitem> + +<listitem> +<para>If you wish, you can fade the volume. Fading means to start +playing the audio file at one volume and gradually change to the final +volume, over a specified time interval. The final volume is that +entered in <guilabel>Volume</guilabel> above. To enable fade, check +<guilabel>Fade</guilabel>, and then enter the fade period in seconds +in the <guilabel>Fade time</guilabel> field, and adjust the +<guilabel>Initial volume</guilabel> slider.</para> +</listitem> +</itemizedlist> + +<note><para>When possible, &kmix; is used to set volumes. This +ensures that the volume at which the alarm is played is unaffected by +any changes in the computer's sound level. If &kmix; is not installed +(or is older than &kde; 3.1), the volume is set relative to the sound +level current at the time the alarm triggers. So in this case, the +volume at which the alarm is played will vary depending on any changes +in the computer's sound level.</para></note> + +<tip><para>You can use the <guibutton>Try</guibutton> button to test out +the selected sound levels.</para></tip> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para>Use the <guibutton>Font & Color...</guibutton> button to +select a font, and foreground and background colors, for the alarm +message. In the <guilabel>Choose Alarm Font & Color</guilabel> +dialog, check <guilabel>Use default font</guilabel> to display the +message in whatever font is configured as the default at the time +the message is displayed. To choose a specific font for the message, +uncheck <guilabel>Use default font</guilabel>. (The default font, and +the colors shown in the color selection lists, can be set in the +<link linkend="preferences-fontcolour">Preferences dialog</link>.)</para> + +<para>The selected font and colors are shown in a sample text +alongside the button. You can edit this text to show special +characters.</para> +</listitem> + +<listitem> +<para>Use the <guibutton>Special Actions...</guibutton> button to +specify shell commands to execute before or after displaying the +alarm. In the <guilabel>Special Alarm Actions</guilabel> +dialog:</para> + +<itemizedlist> +<listitem> +<para>In the <guilabel>Pre-alarm action</guilabel> field, enter a +shell command to execute before the alarm is displayed. Note that +&kalarm; will wait for the command to complete before displaying the +alarm.</para> + +<para>A pre-alarm action is only executed once when the alarm message +is initially displayed, including when a reminder message is replaced +by the actual alarm message. It is <emphasis>not</emphasis> executed +in any of the following circumstances:</para> + +<itemizedlist> +<listitem><para>When a reminder message is displayed.</para></listitem> +<listitem><para>When the message is redisplayed after deferring the +alarm.</para></listitem> +<listitem><para>When the message was displaying at the time you logged +off and is then restored when you log back in.</para></listitem> +<listitem><para>When a recurring alarm triggers but the alarm message +(or a deferred alarm message) from a previous occurrence of the alarm +is still visible; in other words, when the previous occurrence of the +alarm has not yet been acknowledged.</para></listitem> +</itemizedlist> +</listitem> + +<listitem> +<para>In the <guilabel>Post-alarm action</guilabel> field, enter a +shell command to execute when the alarm is acknowledged (whether by +clicking <guibutton>Close</guibutton> or by using the close button +in the window's titlebar). It is <emphasis>not</emphasis> +executed in any of the following circumstances:</para> + +<itemizedlist> +<listitem><para>When a reminder message is closed.</para></listitem> +<listitem><para>When you defer the alarm, except when the deferred +alarm is finally acknowledged.</para></listitem> +<listitem><para>When the alarm message is closed due to logging +out.</para></listitem> +</itemizedlist> +</listitem> +</itemizedlist> + +<para>See the description of Command alarms below for details of how +shell commands are executed.</para> + +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para><guilabel>File</guilabel> to enter the path or &URL; of a text +or image file whose contents are to be displayed in the alarm message. +Use the button beside the edit box to display a file selection dialog. +Set options as for text alarms above, but note that the +<guilabel>Speak</guilabel> option is not available.</para> +</listitem> + +<listitem> +<para><guilabel>Command</guilabel> to enter a command to +execute.</para> + +<note><para>This option is not available if &kde; is running in kiosk +mode.</para></note> + +<itemizedlist> +<listitem> +<para>The <guilabel>Enter a script</guilabel> checkbox lets you choose +whether to enter a shell command line or a script.</para> + +<para>If this option is unchecked, you can enter a shell command line +to execute. The command is passed straight to the default shell (defined +by the <envar>SHELL</envar> environment variable), and may include +whatever options, parameters, piped commands, etc. are permitted by +the shell in a single line command.</para> + +<para>If this option is checked, you can enter the text of a script to +execute. Remember to include a first line such as +<literal>#!/bin/bash</literal> to ensure that the correct command +interpreter is invoked.</para> +</listitem> + +<listitem> +<para>Use the <guilabel>Command Output</guilabel> group box to specify +what you want to be done with any terminal output which the command +produces when it executes.</para> + +<itemizedlist> +<listitem> +<para>Check <guilabel>Execute in terminal window</guilabel> to cause +the command to be executed in a terminal window. You can choose +which type of terminal window should be used in the +<link linkend="preferences-general">Preferences dialog</link>.</para> +</listitem> + +<listitem> +<para>Check <guilabel>Log to file</guilabel> to save the command's +output in a file. The output, prefixed by a heading showing the time +at which the command was scheduled to run, will be appended to any +existing contents of the file. Enter the file name in the edit box, or +use the button beside the edit box to display a file selection +dialog.</para> +</listitem> + +<listitem> +<para>Check <guilabel>Discard</guilabel> to throw away the command's +output.</para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para><guilabel>Email</guilabel> to enter an email message to send. +Fill in the recipients' addresses, the email subject line and the +message body in the three edit fields. Use the button beside the +addressee edit box to display your &kde; address book from which you +can select email recipients. Attachments may be added using the +<guibutton>Add...</guibutton> button. Note that attached files must +still exist when the alarm is triggered; no copy is stored at the time +the alarm is configured. To remove an attachment, highlight it in the +drop-down list and click the <guibutton>Remove</guibutton> +button.</para> + +<para>Set the following options:</para> + +<itemizedlist> +<listitem> +<para>The <guilabel>From</guilabel> combo box allows you to select +which &kmail; identity to use as your email address for sending the +email. This option only appears if your <guilabel>From</guilabel> +email address in the +<link linkend="preferences-email">Preferences dialog</link> is set to +<guilabel>Use &kmail; identities</guilabel>. Otherwise your email +address is preset in the +<link linkend="preferences-email">Preferences dialog</link>, rendering +this option inapplicable.</para> +</listitem> + +<listitem> +<para>Check <guilabel>Copy email to self</guilabel> to send a blind +copy of the email to yourself when the alarm is triggered. The email +address to which the copy will be sent may be set in the +<link linkend="preferences-email">Preferences dialog</link>, the +default being your email address set in the &kde; Control +Center.</para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Deferral</title> + +<para>If the alarm is a recurring alarm and it was deferred after it +was last displayed, the <guilabel>Deferred Alarm</guilabel> group box +shows the time the alarm was deferred to. +<guibutton>Change...</guibutton> displays a dialog which allows you to +change the deferred time or to cancel the deferral.</para> + +</sect2> + +<sect2> +<title>Time</title> + +<para>In the <guilabel>Time</guilabel> group box, select either</para> + +<itemizedlist> +<listitem> +<para><guilabel>At date/time</guilabel> to enter the date and time +when the alarm is to be triggered. Check <guilabel>Any time</guilabel> +if you want to specify only a date for the alarm: in this case the +alarm will be displayed at the first opportunity on or after the +configured start-of-day time, on the specified date. +(<link linkend="preferences-general">Configuring &kalarm;</link> +describes how to set the start-of-day time.)</para> + +<para>For a non-recurring alarm, the date/time which you enter must be +in the future, or if you enter only a date it must be today or later. +For a recurring alarm, there are no such restrictions since the start +date/time will be automatically adjusted to the first recurrence due +after the current time.</para> +</listitem> + +<listitem> +<para><guilabel>Time from now</guilabel> to enter how long after now +(in hours and minutes) the alarm should be triggered.</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Reminder</title> + +<para>For a display alarm, check <guilabel>Reminder</guilabel> if you +want to display a reminder in advance of the main alarm and of each of +its recurrences (if any). Enter how long in advance using the edit +controls beside the checkbox.</para> + +<note><para>Reminders are not displayed for sub-repetitions within a +recurrence. Reminders are only shown before each main +recurrence of the alarm.</para></note> + +<para>If the alarm recurs, check <guilabel>Reminder for first +recurrence only</guilabel> if you only want a reminder before the +alarm's first recurrence. If this is not checked, the reminder period +is limited to being less than the recurrence interval.</para> + +</sect2> + +<sect2> +<title>Cancelation</title> + +<para>The late-cancelation options determine how an alarm is treated +after its scheduled time:</para> + +<itemizedlist> +<listitem> +<para>The <guilabel>Cancel if late</guilabel> checkbox determines what +happens if the alarm cannot be triggered at its scheduled time.</para> + +<para>Check this box to cancel the alarm if it cannot be triggered +within a specified time period after the right time. The time period +is selected using controls which appear when you check the box. For +example, if you enter a time period of 1 hour, the alarm will be +triggered at the first opportunity up to an hour after it is due, but +if it cannot be triggered within an hour its activation will be +canceled.</para> + +<note><para>The lateness of date-only alarms, &ie; ones for which the +<guilabel>Any time</guilabel> option is selected, is calculated from +the start-of-day time on the alarm's scheduled date.</para></note> + +<para>Leave the box unchecked to trigger the alarm at the first +opportunity starting at the scheduled time, regardless of how late it +is.</para> + +<note><para>An alarm can only be triggered while you are logged in, +and while both X and the <application>alarm daemon</application> are +running.</para></note> +</listitem> + +<listitem> +<para>Check <guilabel>Auto-close window after this time</guilabel> if +you want the alarm window to be automatically closed if it is still +showing at the expiry of the late-cancelation time.</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Recurrence</title> + +<para>Specify whether or how the alarm should be repeated using the +<guilabel>Recurrence</guilabel> tab.</para> + +<note><para>The alarm's basic repetition characteristics are displayed +for convenience in the title of the <guilabel>Recurrence</guilabel> +tab. The recurrence interval is shown first, followed by any +sub-repetition interval set up using the +<guibutton>Sub-Repetition</guibutton> button.</para></note> + +<para>In the <guilabel>Recurrence Rule</guilabel> group box, set the +recurrence type or time period as follows:</para> + +<itemizedlist> +<listitem><para>To trigger the alarm once only, select <guilabel>No +recurrence</guilabel>.</para></listitem> + +<listitem><para>Select <guilabel>At login</guilabel> to trigger the +alarm whenever you log in, until its scheduled end time. Then, at its +scheduled end time it will finally be triggered one last time. (Note +that an alarm repeated at login will also be triggered any time you +enable alarms, or restart or reset the <application>alarm +daemon</application>.)</para></listitem> + +<listitem> +<para>To make the alarm recur at regular intervals, select one of the +time period types and then enter in the +<guilabel>Recur every</guilabel> box how many time periods should +elapse between recurrences. For example, to repeat +every fortnight, you could select <guilabel>Daily</guilabel> and enter +a value of 14, or select <guilabel>Weekly</guilabel> and enter a value +of 2. Depending on the time period type selected, you may have further +options:</para> + +<itemizedlist> +<listitem> +<para>For a weekly recurrence, check each day in the week on which you +wish to trigger the alarm.</para> +</listitem> + +<listitem> +<para>For a monthly recurrence, you may select either a fixed date, or +a position (⪚ the second Tuesday).</para> +</listitem> + +<listitem> +<para>For a yearly recurrence, you may select either a fixed day in +the month, or a position in a month (⪚ the last Saturday in +May). Check each month of the year in which you wish to trigger the +alarm.</para> +</listitem> +</itemizedlist> + +<tip><para>To set a daily alarm to occur only on weekdays, use a +weekly recurrence and check each weekday.</para></tip> + +</listitem> +</itemizedlist> + +<para>In the <guilabel>Recurrence End</guilabel> group box, set the +overall recurrence time span as follows:</para> + +<itemizedlist> +<listitem><para>Select <guilabel>No end</guilabel> to continue the +repetitions indefinitely.</para></listitem> + +<listitem><para>Select <guilabel>End after</guilabel> to specify the +total number of occurrences of the alarm.</para></listitem> + +<listitem><para>Select <guilabel>End by</guilabel> to specify the +date/time until which the alarm will be repeated.</para></listitem> +</itemizedlist> + +<para>If you wish to exclude certain date/times from the recurrence +which you have set up, specify them in the +<guilabel>Exceptions</guilabel> group box. The list of exceptions +(&ie; excluded date/times) is shown on the left. To add a new +exception, enter a date on the right and press +<guibutton>Add</guibutton>. To change an exception, highlight it in +the list, enter the new date on the right and press +<guibutton>Change</guibutton>. To delete an exception, highlight it +in the list and press <guibutton>Delete</guibutton>.</para> + +<sect3> +<title>Sub-Repetition</title> + +<para>You can use the <guibutton>Sub-Repetition</guibutton> button to +set up a repetition within a repetition. In this case, each time the +alarm is due as specified in the main recurrence, instead of being +triggered just once it is triggered repeatedly in accordance with your +sub-repetition specification. For example, to set up an alarm which +repeats every hour from noon to 6 pm each Thursday, you would set up a +weekly recurrence on Thursday at 12:00, and use the Sub-Repetition +dialog to specify an interval of 1 hour and either a count of 6 or a +duration of 6 hours.</para> + +<para>In the Sub-Repetition dialog which is displayed when you click +the <guibutton>Sub-Repetition</guibutton> button, check +<guilabel>Repeat every</guilabel> to set up a repetition, or uncheck +it to remove the repetition. If <guilabel>Repeat every</guilabel> is +checked, set up the repetition as follows:</para> + +<itemizedlist> +<listitem><para>Enter the time interval between repetitions in the +controls beside <guilabel>Repeat every</guilabel>. Select the desired +time units (⪚ <guilabel>days</guilabel>) and then enter the number +of units.</para> +</listitem> + +<listitem><para>Specify either the repetition count or its +duration:</para> + +<itemizedlist> +<listitem><para>Select <guilabel>Number of times</guilabel> to enter +how many times the alarm should be triggered after the main +recurrence. So, for example, to make the alarm occur 4 times at each +main recurrence, &ie; 3 additional times, you should enter 3 +here.</para> +</listitem> + +<listitem><para>Select <guilabel>Duration</guilabel> to enter the +total time period during which the alarm should be repeated. This need +not be an exact multiple of the repetition interval; it will +automatically be rounded down when you click +<guibutton>OK</guibutton>.</para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> + +<note><para>To prevent overlapping sub-repetitions for the same alarm, +a sub-repetition's duration is restricted to be less than the longest +interval between main recurrences. Each time the alarm recurs as +specified in the main recurrence, any still active sub-repetition +which started at the previous recurrence is automatically +cancelled.</para></note> + +</sect3> +</sect2> + +<sect2> +<title>Other controls</title> + +<para>For display alarms, the +<guilabel>Confirm acknowledgment</guilabel> checkbox lets you specify +whether you will be prompted for confirmation when you close the alarm +message window. This may be used as a safeguard against accidental +acknowledgment of alarms.</para> + +<para>Select <guilabel>Show in &korganizer;</guilabel> to add the +alarm to &korganizer;'s active calendar, where it will appear as an +event without an alarm. This option allows you to track alarms in +&korganizer; while still making use of &kalarm;'s functions.</para> + +<note><para>If you later modify or delete the alarm in &kalarm;, the +&korganizer; event will be modified or deleted correspondingly. But +if you change the event in &korganizer;, the alarm in &kalarm; will +not be affected.</para></note> + +<para>Press the <guibutton>Load Template</guibutton> button to select +a template to preset the dialog with, as described in <link +linkend="create-edit">Creating and manipulating alarms</link>. </para> + +<para>Press the <guibutton>Try</guibutton> button to test the alarm +and check whether it works correctly. The alarm is executed just as +if it had been scheduled in the normal way.</para> + +<para>Press the <guibutton>OK</guibutton> button +when all details are correct, to add the alarm to the scheduled +list.</para> + +</sect2> +</sect1> + +<sect1 id="message-window"> +<title>Alarm message window</title> + +<para>When an alarm message is due, it is displayed on each &kde; +desktop and cannot be covered by ordinary windows, to ensure that +you see it. The message window shows the time for which the alarm was +scheduled, so that you can see when it popped up if you were away from +the computer at the time. (For reminder messages, however, the +date/time shown is that for the main alarm or its recurrence, not the +reminder message time, and the window title is +<quote>Reminder</quote>).</para> + +<para>Alarm message windows remain visible until you acknowledge them, +unless <guilabel>Auto-close window after late-cancelation +time</guilabel> was checked in the <link +linkend="alarm-edit-dlg">Alarm Edit dialog</link>. In the case of a +recurring alarm, if an unacknowledged message window remains from a +previous occurrence of the alarm, the existing window is simply popped +up when the alarm recurs. This avoids having to acknowledge multiple +copies of the same message should you not wish, or be unable, to +acknowledge a message at the time it appears.</para> + +<para>The alarm message window provides whichever of the following +options are applicable to the displayed alarm:</para> + +<itemizedlist> +<listitem> +<para>Acknowledge the alarm by clicking the +<guibutton>Close</guibutton> button. This closes the window (after a +prompt for confirmation, if you selected +<guilabel>Confirm acknowledgment</guilabel>).</para> +</listitem> + +<listitem> +<para>Edit the alarm by clicking the <guibutton>Edit...</guibutton> +button. This displays the +<link linkend="alarm-edit-dlg">alarm edit dialog</link>.</para> +</listitem> + +<listitem> +<para>Display options to defer the alarm until later by clicking the +<guibutton>Defer...</guibutton> button. Then select +<guilabel>Defer to date/time</guilabel> to enter the date and time +when the message is to be redisplayed, or select <guilabel>Defer for +time interval</guilabel> to enter how long after now (in hours and +minutes) the message should be redisplayed. Then click +<guibutton>Defer</guibutton> to defer the alarm message and close its +window.</para> + +<note><para>The time the alarm is deferred to must be earlier than its +next scheduled occurrence or next reminder. For this reason, the +<guibutton>Defer...</guibutton> button in the alarm message window and +the <guibutton>OK</guibutton> button in the deferral dialog are +disabled one minute before the next occurrence or +reminder.</para></note> + +<note><para>The <guibutton>Defer...</guibutton> button is not +available for alarms which are displayed at login due to the +<guilabel>Repeat at login</guilabel> option having been +selected.</para></note> +</listitem> + +<listitem> +<para>Stop playing the alarm's sound file by clicking the button +showing the <quote>stop playing</quote> symbol.</para> +</listitem> + +<listitem> +<para>If the alarm message was created by dragging an email from +&kmail;, you can directly access the email in &kmail; by clicking the +button showing the &kmail; icon. This will select and highlight the +email in &kmail;'s folder list.</para> + +<warning><para>If &kmail;'s indexes are regenerated, the link to the +email in &kmail; will be lost.</para></warning> +</listitem> + +<listitem> +<para>The button showing the <guiicon>&kalarm;</guiicon> icon provides +a convenient way to activate &kalarm;.</para> +</listitem> +</itemizedlist> + +<para>The alarm message window may be displayed in two different +modes, depending on your preferences. You can choose the mode in the +<link linkend="preferences-view">Preferences dialog</link>.</para> + +<itemizedlist> +<listitem> +<para>As a normal window. In this mode, the keyboard focus is taken +by the alarm message window when it appears, so if you are typing at +the time your keystrokes will be diverted to it rather than your +original application.</para> +</listitem> + +<listitem> +<para>As a non-modal window. In this mode, the keyboard focus is +unaffected when the alarm message window appears, so it will not +interfere with your typing. However in this mode the window has no +titlebar or frame, so you cannot move it or resize it.</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="system-tray"> +<title>System tray operation</title> + +<para>&kalarm; may be run as an icon in the system tray. This +icon allows one-click activation of &kalarm;, and provides both +control and status indication of alarm monitoring. A normal &kalarm; +icon indicates that alarms are being monitored, while a gray icon +indicates that alarms are not being monitored.</para> + +<para>If you hover the mouse cursor over the system tray icon, a +summary of the first few message alarms due in the next 24 hours are +displayed as a tooltip. You can switch this feature off, or configure +the number of alarms to display and their format, in the +<link linkend="preferences-view">Preferences dialog</link>.</para> + +<para><mousebutton>Left</mousebutton> click on the system tray icon to +toggle between displaying and hiding the &kalarm; main window.</para> + +<para><mousebutton>Right</mousebutton> click on the system tray icon to +display its context menu:</para> + +<variablelist> +<varlistentry> +<term><menuchoice><guimenuitem>Enable Alarms</guimenuitem></menuchoice></term> +<listitem><para><action>Enables monitoring of alarms. This option +only appears if alarms are currently disabled.</action></para> +<para>See +<link linkend="enable-disable">Enabling and disabling alarms</link> +for details.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Disable Alarms</guimenuitem></menuchoice></term> +<listitem><para><action>Disables monitoring of alarms. This option +only appears if alarms are currently enabled.</action></para> +<para>See +<link linkend="enable-disable">Enabling and disabling alarms</link> +for details.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>New Alarm...</guimenuitem></menuchoice></term> +<listitem><para><action>Opens the alarm edit dialog to create a new +alarm.</action></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>New Alarm From Template</guimenuitem></menuchoice></term> +<listitem><para><action>Displays the list of alarm templates in a +menu. When you select one, the alarm edit dialog is opened, preset +with that template's details.</action></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Configure &kalarm;...</guimenuitem></menuchoice></term> +<listitem><para><action>Displays the &kalarm; preferences dialog.</action></para> +<para>The preferences dialog is described in +<link linkend="preferences">Configuring &kalarm;</link>. It +includes options relating to the &kalarm; system tray icon.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Restore / Minimize</guimenuitem></menuchoice></term> +<listitem><para><action>Restores or minimizes the main &kalarm; window.</action></para> +<para>This option is only available if the run mode is +<quote>continuous</quote>. (See +<link linkend="preferences-general">Configuring &kalarm;</link> for a +description of run modes.)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Quit</guimenuitem></menuchoice></term> +<listitem><para><action>Closes the &kalarm; system tray +icon.</action></para> +<para>In <quote>continuous</quote> run mode +only, it also closes all &kalarm; main windows. It has no effect on +the monitoring of alarms by the <application>alarm +daemon</application>, if you have deselected <guilabel>Disable alarms +while not running</guilabel> in the Preferences dialog.</para> +</listitem> +</varlistentry> +</variablelist> + +<sect2> +<title>Displaying &kalarm; in the system tray</title> + +<para>You must be running the &kde; desktop or another suitable window +manager in order to display &kalarm; in the system tray. If &kalarm; +is running in <quote>continuous</quote> mode, the system tray icon is +always displayed. These instructions apply only to +<quote>on-demand</quote> mode. (See +<link linkend="preferences-general">Configuring &kalarm;</link> for a +description of run modes.)</para> + +<para>To display &kalarm; in the system tray, select <menuchoice> +<guimenu>View</guimenu><guimenuitem>Show in System Tray</guimenuitem> +</menuchoice>.</para> + +<para>To remove &kalarm; from the system tray, do one of the +following:</para> + +<itemizedlist> +<listitem> +<para>Select <menuchoice><guimenu>View</guimenu> +<guimenuitem>Hide from System Tray</guimenuitem></menuchoice>.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click on the system tray icon +and choose <menuchoice><guimenuitem>Quit</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> +</itemizedlist> + +</sect2> +</sect1> + +<sect1 id="refreshing"> +<title>Refreshing alarms</title> + +<para>If in the unlikely event that any alarm was not triggered when +it should have been, you can refresh the alarm list and trigger any +missed alarms by selecting +<menuchoice> +<guimenu>Actions</guimenu><guimenuitem>Refresh Alarms</guimenuitem> +</menuchoice>.</para> + +<para>&kalarm; retriggers missed alarms by resetting the +<application>alarm daemon</application>, which is discussed in the +<link linkend="daemon-reset">Alarm daemon</link> section.</para> + +</sect1> + +<sect1 id="enable-disable"> +<title>Enabling and disabling alarms</title> + +<para>Alarms may be enabled and disabled either as a whole or +individually:</para> + +<itemizedlist> +<listitem> +<para><quote>Alarm monitoring</quote> applies to alarms as a whole. +When alarm monitoring is disabled, the <application>alarm +daemon</application> ceases to check alarms and therefore no alarms +will trigger at all. When alarm monitoring is enabled (the normal +situation), all alarms which are not individually disabled will +trigger at the appropriate times.</para> +</listitem> + +<listitem> +<para>Alarms may be individually enabled and disabled, independently +of the alarm monitoring status. So the enabled/disabled status of +individual alarms will be unchanged by disabling and then re-enabling +alarm monitoring. Unlike alarm monitoring which could potentially be +disabled due to &kalarm; not running or the +<application>alarm daemon</application> not functioning, individual +alarms can only be disabled if you use menu commands to do so.</para> + +<para>An alarm's individual enabled/disabled status is indicated by +its color in the alarm list (the color being configurable in the +<link linkend="preferences-fontcolour">Font & Color</link> tab of +the Preferences dialog).</para> +</listitem> +</itemizedlist> + +<para>For an alarm to trigger, it must be individually enabled as well +as alarm monitoring being enabled.</para> + +<sect2> +<title>Enabling alarm monitoring</title> + +<para>If &kalarm;'s run mode is <quote>continuous</quote> and you +have selected <guilabel>Disable alarms while not running</guilabel> +in the Preferences dialog, you must first ensure that &kalarm; is +running in order for alarm monitoring to take place.</para> + +<para>Then if alarm monitoring is currently disabled, do one of the +following to enable alarms:</para> + +<itemizedlist> +<listitem> +<para>Select <menuchoice><guimenu>Actions</guimenu> +<guimenuitem>Enable Alarms</guimenuitem></menuchoice>.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click on the system tray icon +and choose +<menuchoice><guimenuitem>Enable Alarms</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> +</itemizedlist> + +<para>The <application>alarm daemon</application> is started if +necessary and alarms will be monitored for when they become +due.</para> + +</sect2> + +<sect2> +<title>Disabling alarm monitoring</title> + +<para>There are several ways to disable alarm monitoring, which +prevents &kalarm; from displaying any further alarms either until you +re-enable alarms, or – assuming that the <application>alarm +daemon</application> is configured to start at login – until the +next time you log in.</para> + +<para>To disable alarms without stopping the <application>alarm +daemon</application>, do one of the following:</para> + +<itemizedlist> +<listitem> +<para>Select <menuchoice><guimenu>Actions</guimenu> +<guimenuitem>Disable Alarms</guimenuitem></menuchoice>.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click on the system tray icon +and choose +<menuchoice><guimenuitem>Disable Alarms</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> + +<listitem> +<para>If &kalarm;'s run mode is <quote>continuous</quote> and you have +selected <guilabel>Disable alarms while not running</guilabel> in the +Preferences dialog, quit &kalarm;.</para> +</listitem> +</itemizedlist> + +<para>To disable alarms by stopping the <application>alarm +daemon</application>:</para> + +<itemizedlist> +<listitem> +<para>Select <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Control Alarm Daemon...</guimenuitem></menuchoice>. This +displays the Service Manager dialog which enables you to stop the +<application>alarm daemon</application>.</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Enabling and disabling individual alarms</title> + +<para>To enable individual alarms which are currently disabled, do +one of the following:</para> + +<itemizedlist> +<listitem> +<para>Select one or more alarms by clicking on their entries in the +alarm list. Then choose <menuchoice> +<guimenu>Actions</guimenu><guimenuitem>Enable</guimenuitem> +</menuchoice>.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click on the desired entries in +the alarm list and choose +<menuchoice><guimenuitem>Enable</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> +</itemizedlist> + +<para>To disable individual alarms which are currently enabled, do one +of the following:</para> + +<itemizedlist> +<listitem> +<para>Select one or more alarms by clicking on their entries in the +alarm list. Then choose <menuchoice> +<guimenu>Actions</guimenu><guimenuitem>Disable</guimenuitem> +</menuchoice>.</para> +</listitem> + +<listitem> +<para><mousebutton>Right</mousebutton> click on the desired entries in +the alarm list and choose +<menuchoice><guimenuitem>Disable</guimenuitem></menuchoice> +from the context menu.</para> +</listitem> +</itemizedlist> + +</sect2> +</sect1> + +<sect1 id="quitting"> +<title>Quitting the program</title> + +<para>Quit &kalarm; by closing all its windows and the system tray +icon, or if it is running in <quote>continuous</quote> mode, by +closing any message windows and selecting <menuchoice> +<guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice>, +or <menuchoice><guimenuitem>Quit</guimenuitem></menuchoice> in the +system tray icon context menu.</para> + +<para>The effect of <menuchoice><guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem></menuchoice> or of the system tray +icon context menu item +<menuchoice><guimenuitem>Quit</guimenuitem></menuchoice> depends on +the run mode: in <quote>on-demand</quote> mode it hides the system +tray icon, while in <quote>continuous</quote> mode it +quits the program.</para> + +<tip><para>If you have deselected <guilabel>Disable alarms while not +running</guilabel> in the Preferences dialog, quitting &kalarm; has no +effect on the <application>alarm daemon</application> which if +already active will continue to monitor scheduled alarms and request +their display when they become due.</para></tip> + +</sect1> +</chapter> + +<chapter id="preferences"> +<title>Configuring &kalarm;</title> + +<para>To configure &kalarm;'s operation to suit your system and your +personal preferences, select <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure &kalarm;...</guimenuitem></menuchoice>. +This displays the configuration dialog.</para> + +<sect1 id="preferences-general"> +<title>General</title> + +<para>The <guilabel>General</guilabel> section lets you control +&kalarm;'s overall behavior:</para> + +<itemizedlist> +<listitem><para><guilabel>Run Mode</guilabel> group box: These options +control &kalarm;'s system tray icon, and also allow some control over +&kalarm;'s use of system resources by specifying whether or not to run +it continuously. If system performance is of concern, running it on +demand without displaying the system tray icon may be desirable; +running it continuously in the system tray uses more system resources +but gives the benefits of displaying an alarm-enabled indication and +making the application more accessible. Running &kalarm; on demand +does not affect the execution of alarms, since it is the +<application>alarm daemon</application> and not &kalarm; which +monitors the alarm list and triggers alarms.</para> + +<itemizedlist> +<listitem><para><guilabel>Run only on demand</guilabel>: &kalarm; +is run only when an alarm is triggered, if you run it manually, or +while its system tray icon is displayed. In this mode the system tray +icon can still be displayed, but closing the system tray icon has no +effect on any &kalarm; windows.</para> +</listitem> + +<listitem><para><guilabel>Run continuously in system tray</guilabel>: +&kalarm; runs continuously and the system tray icon is always +displayed while it is running. In this mode, closing the system tray +icon closes all &kalarm; main windows, and if no message windows are +visible, quits the application. The options available in this mode +are:</para> + +<itemizedlist> +<listitem><para><guilabel>Disable alarms while not running</guilabel>: +Selecting this option has the effect that alarms will be disabled +whenever &kalarm;'s system tray icon is not visible.</para> + +<itemizedlist> +<listitem><para><guilabel>Warn before quitting</guilabel>: When alarms +are disabled while &kalarm; is not running, selecting this option +prompts you for confirmation if you attempt to terminate &kalarm; using +the system tray icon's <menuchoice><guimenu>Quit</guimenu></menuchoice> +option. This prevents accidental disabling of alarms. For safety, this +option is automatically re-enabled by default whenever you change run +mode.</para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> + +<!-- +<para>In this mode, if no system tray exists, &kalarm; runs +continuously in the background and alarms are always enabled.</para> +--> +</listitem> + +<listitem><para><guilabel>Autostart at login</guilabel>: In continuous +mode, this starts &kalarm; at &kde; session login, ensuring that +&kalarm; runs at all times unless you manually quit.</para> +</listitem> + +<listitem><para><guilabel>Autostart system tray icon at +login</guilabel>: In on-demand mode, this displays &kalarm;'s system +tray icon at login. &kalarm; will run until the system tray icon is +closed.</para> +</listitem> + +<listitem><para><guilabel>Start alarm monitoring at login</guilabel>: +This starts alarm monitoring at KDE session login, by starting the +<application>alarm daemon</application>. Note that in order for alarms +to be activated, you also need to select appropriate options in the +<guilabel>Run Mode</guilabel> group box.</para> + +<warning><para>This option should always be checked unless you intend +to discontinue use of &kalarm;.</para></warning> + +<note><para>This option is automatically reselected whenever &kalarm; +is run. So if you have unchecked this option and want to continue to +prevent the <application>alarm daemon</application> from running at +login, you need to uncheck this option again each time you run +&kalarm;.</para></note> +</listitem> +</itemizedlist> +</listitem> + +<listitem><para><guilabel>Start of day for date-only +alarms</guilabel>: Set the start-of-day time for the purposes of +triggering date-only alarms, &ie; ones for which the <guilabel>Any +time</guilabel> option was selected. On the date when they are due, +such alarms will be output at the earliest opportunity during the +24 hours starting from the start-of-day time.</para> +</listitem> + +<listitem><para>If you set up yearly recurrences for February 29th, +specify how these are to be handled in non-leap years by selecting one +of the following options:</para> + +<itemizedlist> +<listitem><para><guilabel>February 28th</guilabel>: the alarm will +occur on February 29th in leap years, and on February 28th in +non-leap years.</para> +</listitem> + +<listitem><para><guilabel>March 1st</guilabel>: the alarm will +occur on February 29th in leap years, and on March 1st in +non-leap years.</para> +</listitem> + +<listitem><para><guilabel>Do not repeat</guilabel>: the alarm will +occur on February 29th in leap years, but will be suppressed in +non-leap years.</para> +</listitem> +</itemizedlist> + +<note><para>Changing this option will not cause the next scheduled +recurrence of any existing alarms to be re-evaluated. It will only +affect new alarms, or existing alarms after they are next +triggered.</para></note> +</listitem> + +<listitem><para><guilabel>Confirm alarm deletions</guilabel>: Specify +whether you should be prompted for confirmation each time you delete +an alarm.</para> +</listitem> + +<listitem><para><guilabel>Expired Alarms</guilabel> group box: These +options control the storage of expired alarms.</para> +<itemizedlist> +<listitem><para><guilabel>Keep alarms after expiry</guilabel>: +Select this option to store expired and deleted alarms. Deselect it +to keep no record of alarms once they cease to be active. Note that +deleted alarms are only stored if they have previously been +triggered. If you delete an alarm before it ever triggers, it is +discarded.</para> +</listitem> + +<listitem><para><guilabel>Discard expired alarms after</guilabel>: +Set the number of days to store expired and deleted alarms, after which +they are permanently deleted.</para> +</listitem> + +<listitem><para><guibutton>Clear expired alarms</guibutton>: This +button discards all currently stored expired alarms. This has no +effect on alarms which subsequently expire; they will continue to be +stored according to the selected options.</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem><para><guilabel>Terminal for Command Alarms</guilabel>: +Here, you can select which type of terminal window should be used for +command alarms which are executed in a terminal window. Some of the +most common terminal window applications are preconfigured, ⪚ +<application>xterm</application>, &konsole;, although only those +which are installed on your system will be shown here. You can view +the actual command options used for each application by displaying the +context help for its radio button.</para> + +<para>If you want to use another application, or want to use one of +those listed but with different command options, select +<guilabel>Other</guilabel> and enter the command to invoke the +terminal window. By default, the alarm's command string will be +appended to what you specify. Alternatively, you may specify where the +alarm's command string should be inserted, by use of the following +codes:</para> + +<variablelist> +<varlistentry> +<term>%c</term> +<listitem> +<para>The alarm's command string will be substituted.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>%w</term> +<listitem> +<para>The alarm's command string will be substituted, with a <literal>sleep</literal> appended.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>%C</term> +<listitem> +<para>A temporary command file containing the alarm's command string will be created, and the command to execute the file will be substituted.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>%W</term> +<listitem> +<para>A temporary command file containing the alarm's command string will be created with a <literal>sleep</literal> appended, and the command to execute the file will be substituted.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>When the command alarm is triggered, its command string will be +quoted before being inserted into the terminal window command.</para> +</listitem> + +</itemizedlist> +</sect1> + +<sect1 id="preferences-email"> +<title>Email</title> + +<para>The <guilabel>Email</guilabel> section lets you choose options +for sending and addressing email alarms:</para> + +<itemizedlist> +<listitem> +<para><guilabel>Email client</guilabel>: Specify the email +client to be used to send email alarms:</para> + +<itemizedlist> +<listitem><para><guilabel>KMail</guilabel>: When an email alarm is +triggered, the email is sent using &kmail; (which is started first if +necessary) as follows:</para> + +<itemizedlist> +<listitem><para>If &kmail; is version 1.7 or later, the email is sent +automatically.</para> +</listitem> + +<listitem><para>If &kmail; is an older version, the email is added to +&kmail;'s <filename>outbox</filename> folder for later +transmission.</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem><para><guilabel>Sendmail</guilabel>: When an email alarm is +triggered, the email is sent automatically using +<application>sendmail</application>. This option will only work if +your system is configured to use <application>sendmail</application>, +or a <application>sendmail</application> compatible mail transport +agent such as <application>postfix</application> or +<application>qmail</application>.</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para><guilabel>Copy sent emails into &kmail;'s sent-items folder</guilabel>: +Select this option if, every time an email alarm is triggered, you +want a copy of the transmitted email to be stored in &kmail;'s +<filename>sent-items</filename> folder.</para> + +<note><para>This option is not available when &kmail; is selected as +the email client, since &kmail; automatically does this.</para></note> +</listitem> + +<listitem> +<para>Select your email address to be used as the sender's address in +email alarms:</para> + +<itemizedlist> +<listitem><para>Select <guilabel>From</guilabel> to enter an email +address.</para> +</listitem> + +<listitem><para>Select <guilabel>Use address from Control +Center</guilabel> to use the email address which is configured in the +&kde; Control Center.</para> +</listitem> + +<listitem><para>Select <guilabel>Use &kmail; identities</guilabel> to +be able to choose at the time you configure an email alarm which of +&kmail;'s email identities to use. &kmail;'s default identity will be +used for alarms which were already configured before you selected this +option.</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para>Select your email address to be used for sending blind copies of +email alarms to yourself when the +<guilabel>Copy email to self</guilabel> option is selected:</para> + +<itemizedlist> +<listitem><para>Select <guilabel>Bcc</guilabel> to enter an email +address. If blind copies are to be sent to your account on the +computer which &kalarm; runs on, you could simply enter your user +login name here.</para> +</listitem> + +<listitem><para>Select <guilabel>Use address from Control +Center</guilabel> to use the email address which is configured in the +&kde; Control Center.</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para><guilabel>Notify when remote emails are queued</guilabel>: +Select this option to display a notification whenever an email alarm +queues an email for sending to a remote system. This may be useful +if, for example, you have a dial-up connection, or email is queued in +&kmail;'s <filename>outbox</filename> folder, so that you can +ensure that you do whatever is needed to actually transmit +the email.</para> +</listitem> +</itemizedlist> +</sect1> + +<sect1 id="preferences-view"> +<title>View</title> + +<para>The <guilabel>View</guilabel> section lets you control some +aspects of &kalarm;'s appearance:</para> +<itemizedlist> + +<listitem> +<para><guilabel>System Tray Tooltip</guilabel> group box: These options +control what information is shown in the tooltip which appears when the +mouse cursor hovers over &kalarm;'s system tray icon.</para> + +<itemizedlist> +<listitem> +<para><guilabel>Show next 24 hours' alarms</guilabel>: When selected, +a summary of the first few alarms due in the next 24 hours is +displayed.</para> +</listitem> + +<listitem> +<para><guilabel>Maximum number of alarms to show</guilabel>: Deselect +this option to display all of the next 24 hours' alarms. Select it to +set the maximum number of alarms which will be displayed.</para> +</listitem> + +<listitem> +<para><guilabel>Show alarm time</guilabel>: Select this option to show +the time at which each alarm is scheduled.</para> +</listitem> + +<listitem> +<para><guilabel>Show time until alarm</guilabel>: Select this option to +show the length of time remaining before each alarm's next scheduled +occurrence. The length of time is shown in hours and minutes.</para> + +<itemizedlist> +<listitem> +<para><guilabel>Prefix</guilabel>: Specify a symbol or text to show in +front of the length of time until the alarm, to distinguish it from the +time at which the alarm is scheduled.</para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> +</listitem> + +<listitem><para><guilabel>Message windows have a title bar and take keyboard focus</guilabel>: This +option controls whether alarm message windows are modal or not, &ie; +whether they grab the keyboard focus when they appear. See the +<link linkend="message-window">Alarm message window</link> section for +details.</para> +</listitem> + +<listitem><para><guilabel>System tray icon update interval</guilabel>: Set +the frequency at which the &kalarm; system tray icon is updated to +reflect whether alarms are currently being monitored. This involves +checking whether the <application>alarm daemon</application> is +running.</para> +</listitem> +</itemizedlist> +</sect1> + +<sect1 id="preferences-fontcolour"> +<title>Font & Color</title> + +<para>The <guilabel>Font & Color</guilabel> section lets you set +the default appearance of alarm messages, and the colors to be used +in the alarm list:</para> +<itemizedlist> + +<listitem><para>Select the default font and background color to use +for alarm message display.</para> +</listitem> + +<listitem><para>Edit the color selection list which is displayed when +you click on the background color combo box:</para> +<itemizedlist> + +<listitem><para><guilabel>Add color...</guilabel>: Displays a color +selection dialog which lets you choose a color to add to the +list.</para> +</listitem> + +<listitem><para><guilabel>Remove color</guilabel>: Removes the color +currently displayed in the <guilabel>Background color</guilabel> +combo box from the list. The Custom color item cannot be removed from +the list, and when it is displayed, this button is disabled.</para> +</listitem> + +</itemizedlist> +</listitem> + +<listitem><para>Select the color to be used in the alarm list to show +disabled alarms.</para> +</listitem> + +<listitem><para>Select the color to be used in the alarm list to show +expired alarms.</para> +</listitem> + +</itemizedlist> +</sect1> + +<sect1 id="preferences-edit"> +<title>Edit</title> + +<para>The <guilabel>Edit</guilabel> section lets you choose +default values for the options in the +<link linkend="alarm-edit-dlg">alarm edit dialog</link>:</para> + +<para>For display alarms:</para> + +<itemizedlist> +<listitem><para>Set the default states for the <guilabel>Cancel if +late</guilabel>, <guilabel>Auto-close window after this +time</guilabel> and <guilabel>Confirm acknowledgment</guilabel> +checkboxes.</para> +</listitem> + +<listitem><para>Set the default reminder period units.</para> +</listitem> + +<listitem><para>Set the default special display alarm actions.</para> +</listitem> + +<listitem><para>Set the default sound options. Note that a default +sound file may be specified even if the sound type is not set to +<guilabel>Sound file</guilabel>.</para> +</listitem> +</itemizedlist> + +<para>For command alarms:</para> + +<itemizedlist> +<listitem><para>Set the default states for the <guilabel>Enter a +script</guilabel> and <guilabel>Execute in terminal window</guilabel> +checkboxes.</para> +</listitem> +</itemizedlist> + +<para>For email alarms:</para> + +<itemizedlist> +<listitem><para>Set the default state for the <guilabel>Copy email to +self</guilabel> checkbox.</para> +</listitem> +</itemizedlist> + +<para>For all alarm types:</para> + +<itemizedlist> +<listitem><para>Set the default recurrence type.</para> +</listitem> +</itemizedlist> +</sect1> + +</chapter> + +<chapter id="cmdline-operation"> +<title>Command line operation</title> + +<para>When command line parameters are supplied, &kalarm; does not +display the list of scheduled alarms as described in <link +linkend="using-kalarm">Using &kalarm;</link> above. Command line +options specific to &kalarm; may be used to perform the following +operations:</para> + +<itemizedlist> +<listitem><para>schedule a new alarm</para> +</listitem> +<listitem><para>control the <application>alarm daemon</application></para> +</listitem> +<listitem><para>control &kalarm;'s display mode</para> +</listitem> +<listitem><para>obtain help</para> +</listitem> +</itemizedlist> + +<para>Additional command line options are provided primarily to enable +other programs to interface to &kalarm;. They are described in the +chapter <link linkend="cmdline-interface">Developer's Guide to +&kalarm;</link>.</para> + +<para>The command line must only contain options applicable to one +&kalarm; operation. If you want to perform multiple operations, you +must invoke &kalarm; multiple times with a single set of options each +time.</para> + +<sect1 id="cmdline-schedule"> +<title>Schedule a new alarm</title> + +<para>The following options are used to schedule a new alarm:</para> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> + <entry>Option</entry> + <entry>Description</entry> +</row> +</thead> +<tbody> +<row> + <entry><option>-a</option>, <option>--ack-confirm</option></entry> + <entry>Prompt for confirmation when the alarm message is + acknowledged.</entry> +</row> +<row> + <entry><option>-A</option>, <option>--attach <replaceable>URL</replaceable></option></entry> + <entry>Specify the path or &URL; of a file which is to be attached + to the email. This option may be repeated as necessary. + <option>--mail</option> must be specified with this option.</entry> +</row> +<row> + <entry><option>--auto-close</option></entry> + <entry>Automatically close the alarm window after the expiry of the + <option>--late-cancel</option> period. + <option>--late-cancel</option> must be specified with this + option.</entry> +</row> +<row> + <entry><option>-b</option>, <option>--beep</option></entry> + <entry>Make an audible beep when the message is displayed. + <option>--speak</option>, <option>--play</option> and + <option>--play-repeat</option> cannot be specified with this + option.</entry> +</row> +<row> + <entry><option>--bcc</option></entry> + <entry>Blind copy the email to yourself. + <option>--mail</option> must be specified with this option.</entry> +</row> +<row> + <entry><option>-c</option>, <option>--color</option>, <option>--colour + <replaceable>color</replaceable></option></entry> + <entry>Set the message background color to the specified &Qt; + color name or hex code 0xRRGGBB.</entry> +</row> +<row> + <entry><option>-C</option>, <option>--colorfg</option>, <option>--colourfg + <replaceable>color</replaceable></option></entry> + <entry>Set the message foreground color to the specified &Qt; + color name or hex code 0xRRGGBB.</entry> +</row> +<row> + <entry><option>-d</option>, <option>--disable</option></entry> + <entry>Disable the alarm. It will not trigger until it has been + manually enabled.</entry> +</row> +<row> + <entry><option>-e</option>, <option>--exec <replaceable>commandline</replaceable></option></entry> + <entry>Specify a shell command to execute. If specified, this option + must be the last &kalarm; option in &kalarm;'s command line. All + subsequent command parameters and options are interpreted as + forming the command line to execute. <option>--file</option> and + <option>--mail</option> cannot be specified with this option. + <option>--ack-confirm</option>, <option>--beep</option>, + <option>--color</option> and <option>--colorfg</option> are ignored + with this option.</entry> +</row> +<row> + <entry><option>-f</option>, <option>--file <replaceable>URL</replaceable></option></entry> + <entry>Specify the path or &URL; of a text or image file whose + contents are to form the alarm message. <option>--exec</option> and + <option>--mail</option> cannot be specified, and + <replaceable>message</replaceable> must not be present with this + option.</entry> +</row> +<row> + <entry><option>-F</option>, <option>--from-id + <replaceable>ID</replaceable></option></entry> + <entry>Use the specified &kmail; identity as the sender of the + email. <option>--mail</option> must be specified with this + option.</entry> +</row> +<row> + <entry><option>-i</option>, <option>--interval + <replaceable>period</replaceable></option></entry> + <entry>Set the interval between repetitions of the alarm. + Hours/minutes are specified in the format + <replaceable>nHnM</replaceable>, where <replaceable>n</replaceable> + is a number, ⪚ 3H30M. Other time periods are specified in the + format <replaceable>nX</replaceable>, where + <replaceable>n</replaceable> is a number and + <replaceable>X</replaceable> is one of the following letters: Y + (years), M (months), W (weeks), D (days). If + <option>--recurrence</option> is also specified, Y (years) and M + (months) are not allowed. + Mandatory if <option>--repeat</option> or <option>--until</option> + is specified.</entry> +</row> +<row> + <entry><option>-k</option>, <option>--korganizer</option></entry> + <entry>Show the alarm as an event in &korganizer;'s active + calendar.</entry> +</row> +<row> + <entry><option>-l</option>, <option>--late-cancel + <replaceable>period</replaceable></option></entry> + <entry>Cancel the alarm if it cannot be triggered within the + specified <replaceable>period</replaceable> after the correct + time. The <replaceable>period</replaceable> period is specified in + the same format as described for <option>--reminder</option>. + The default value of <replaceable>period</replaceable> is 1 + minute.</entry> +</row> +<row> + <entry><option>-L</option>, <option>--login</option></entry> + <entry>Trigger the alarm every time you log in. + <option>--interval</option>, <option>--repeat</option> and + <option>--until</option> cannot be specified with this + option.</entry> +</row> +<row> + <entry><option>-m</option>, <option>--mail + <replaceable>address</replaceable></option></entry> + <entry>Send an email to the specified address. This option may be + repeated as necessary. <option>--exec</option> and + <option>--file</option> cannot be specified with this option. + <option>--ack-confirm</option>, <option>--beep</option>, + <option>--color</option> and <option>--colorfg</option> are ignored + with this option.</entry> +</row> +<row> + <entry><option>-p</option>, <option>--play <replaceable>URL</replaceable></option></entry> + <entry>Specify the path or &URL; of an audio file to be played once + when the alarm message is displayed. + <option>--play-repeat</option>, <option>--beep</option> and + <option>--speak</option> cannot be specified with this + option.</entry> +</row> +<row> + <entry><option>-P</option>, <option>--play-repeat <replaceable>URL</replaceable></option></entry> + <entry>Specify the path or &URL; of an audio file to be played + repeatedly for as long as the alarm message is displayed. + <option>--play</option>, <option>--beep</option> and + <option>--speak</option> cannot be specified with this + option.</entry> +</row> +<row> + <entry><option>--recurrence + <replaceable>spec</replaceable></option></entry> + <entry>Set the alarm to recur. Specify the recurrence using iCalendar + syntax (defined in + <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>), + ⪚ <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote>. + <option>--until</option> cannot be specified with this + option.</entry> +</row> +<row> + <entry><option>-r</option>, <option>--repeat + <replaceable>count</replaceable></option></entry> + <entry>Set the number of times the alarm should be triggered, or if + a recurrence is specified with <option>--recurrence</option>, the + number of times the alarm should be triggered each time + <option>--recurrence</option> activates it (&ie; a repetition within + a recurrence). If <option>--recurrence</option> is not present, + specify -1 to repeat the alarm indefinitely. + <option>--interval</option> must be, and <option>--until</option> + cannot be, specified with this option.</entry> +</row> +<row> + <entry><option>-R</option>, <option>--reminder + <replaceable>period</replaceable></option></entry> + <entry>Output a reminder alarm the specified length of time before + the main alarm and each of its recurrences (if any). Hours/minutes are + specified in the format <replaceable>nHnM</replaceable>, where + <replaceable>n</replaceable> is a number, ⪚ 3H30M. Other time + periods are specified in the format <replaceable>nX</replaceable>, + where <replaceable>n</replaceable> is a number and + <replaceable>X</replaceable> is one of the following letters: W + (weeks), D (days). This option cannot be specified with + <option>--exec</option>, <option>--mail</option> or + <option>--reminder-once</option>.</entry> +</row> +<row> + <entry><option>--reminder-once + <replaceable>period</replaceable></option></entry> + <entry>Output a reminder alarm once, the specified length of time + before the first recurrence of the alarm. No reminder will be + displayed before subsequent recurrences (if any). This option cannot + be specified with <option>--exec</option>, <option>--mail</option> + or <option>--reminder</option>.</entry> +</row> +<row> + <entry><option>-s</option>, <option>--speak</option></entry> + <entry>Speak the message when it is displayed. This option requires + <application>KTTSD</application> to be installed and configured, + together with a compatible speech synthesizer. + <option>--beep</option>, <option>--play</option> and + <option>--play-repeat</option> cannot be specified with this + option.</entry> +</row> +<row> + <entry><option>-S</option>, <option>--subject + <replaceable>subject</replaceable></option></entry> + <entry>The subject line of the email. <option>--mail</option> must + be specified with this option.</entry> +</row> +<row> + <entry><option>-t</option>, <option>--time + <replaceable>date/time</replaceable></option></entry> + <entry>Trigger alarm on the date or at the date/time specified. + Specify a date without a time in the format + <replaceable>yyyy-mm-dd</replaceable>; specify a date and time by + <replaceable>[[[yyyy-]mm-]dd-]hh:mm</replaceable> (where omitted, + date fields default to the values for today).</entry> +</row> +<row> + <entry><option>-v</option>, <option>--volume + <replaceable>percentage</replaceable></option></entry> + <entry>Set the audio volume for playing the audio file. This option + can only be used when <option>--play</option> or + <option>--play-repeat</option> is specified.</entry> +</row> +<row> + <entry><option>-u</option>, <option>--until + <replaceable>date/time</replaceable></option></entry> + <entry>Repeat the alarm until the date or date/time specified. + Specify a date without a time in the same format as for + <option>--time</option>. <option>--interval</option> must be, and + <option>--repeat</option> and <option>--recurrence</option> cannot + be, specified with this option.</entry> +</row> +<row> + <entry><replaceable>message</replaceable></entry> + <entry>Message text to display or, if <option>--mail</option> is + specified, the body of the email message.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para>Either a message text, <option>--file</option> or +<option>--exec</option> must be specified; except as noted above, all +the options are optional.</para> + +<para>Two alternative examples which display a multi-line message with +a red background at 10 p.m. on the 27th of this month are:</para> + +<informalexample><screen> +<prompt>%</prompt> <userinput><command>kalarm</command> <option>-c <replaceable>red</replaceable></option> <option>-t <replaceable>27-22:00</replaceable></option> <option><replaceable>"Remember to\nSTOP"</replaceable></option></userinput> +<prompt>%</prompt> <userinput><command>kalarm</command> <option>-c <replaceable>0xFF0000</replaceable></option> <option>-t <replaceable>27-22:00</replaceable></option> <option><replaceable>"Remember to\nSTOP"</replaceable></option></userinput> +</screen> +</informalexample> + +</sect1> + +<sect1 id="cmdline-other"> +<title>Other options</title> + +<para>The following options are used to reset or halt the +<application>alarm daemon</application>, to display the +<link linkend="alarm-edit-dlg">alarm edit dialog</link>, or to control +&kalarm;'s display mode.</para> + +<para>See the <link linkend="daemon-reset">Alarm daemon</link> section +for a discussion about resetting and stopping the <application>alarm +daemon</application>.</para> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> + <entry>Option</entry> + <entry>Description</entry> +</row> +</thead> +<tbody> +<row> + <entry><option>--edit <replaceable>eventID</replaceable></option></entry> + <entry>Display the alarm edit dialog to edit the alarm with the + specified event ID.</entry> +</row> +<row> + <entry><option>-n</option>, <option>--edit-new</option></entry> + <entry>Display the alarm edit dialog, in order to edit a new + alarm.</entry> +</row> +<row> + <entry><option>--edit-new-preset <replaceable>templateName</replaceable></option></entry> + <entry>Display the alarm edit dialog, preset with the alarm template + of the specified name, in order to edit a new alarm.</entry> +</row> +<row> + <entry><option>--reset</option></entry> + <entry>Reset the <application>alarm daemon</application>.</entry> +</row> +<row> + <entry><option>--stop</option></entry> + <entry>Stop the <application>alarm daemon</application>.</entry> +</row> +<row> + <entry><option>--tray</option></entry> + <entry>Display &kalarm; as an icon in the system tray.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para>For example, to reset the <application>alarm +daemon</application>:</para> + +<informalexample><screen> +<prompt>%</prompt> <userinput><command>kalarm</command> <option>--reset</option></userinput> +</screen> +</informalexample> + +</sect1> + +<sect1 id="cmdline-help"> +<title>Help options</title> + +<para>The following help options are common to all +&kde; programs:</para> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> + <entry>Option</entry> + <entry>Description</entry> +</row> +</thead> +<tbody> +<row> + <entry><option>--help</option></entry> + <entry>Shows a brief options help text.</entry> +</row> +<row> + <entry><option>--help-qt</option></entry> + <entry>Shows numerous generic &Qt;-specific options.</entry> +</row> +<row> + <entry><option>--help-kde</option></entry> + <entry>Shows numerous generic &kde;-specific options.</entry> +</row> +<row> + <entry><option>--help-all</option></entry> + <entry>Shows all options.</entry> +</row> +<row> + <entry><option>--author</option></entry> + <entry>Shows the names and email addresses of &kalarm; authors.</entry> +</row> +<row> + <entry><option>-v</option>, <option>--version</option></entry> + <entry>Shows the running versions of the &Qt; library , &kde; and + &kalarm;.</entry> +</row> +<row> + <entry><option>--license</option></entry> + <entry>Show license information.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</sect1> +</chapter> + +<chapter id="daemon"> +<title>Alarm daemon</title> + +<para>The <application>alarm daemon</application>, &kalarmd;, monitors +&kalarm;'s calendar file for alarms becoming due. When it determines +that an alarm is due, it tells &kalarm; to display or execute it, or +to cancel it if it is late and late trigger was not selected for that +alarm.</para> + +<para>The <application>alarm daemon</application> runs in the +background, with no user interface. It may be controlled as described +below.</para> + +<sect1 id="daemon-start"> +<title>Starting, resetting and stopping the <application>alarm daemon</application></title> + +<para>The <application>alarm daemon</application> is normally started +at &kde; session login (unless you disable auto start in the +<link linkend="preferences-general">Preferences dialog</link> and then +cease to use &kalarm;), and runs continuously until logout. If for any +reason it is not running, alarm monitoring will not occur and &kalarm; +will not display or execute any alarms.</para> + +<sect2> +<title>Starting the <application>alarm daemon</application></title> + +<para>To start the <application>alarm daemon</application>, you can +either run &kalarm; in its default graphical mode (&ie; without any +command line parameters other than <option>--tray</option>), enable +alarms using &kalarm;'s system tray icon menu, reset the daemon as +described <link linkend="daemon-reset">below</link>, or you can run +the <application>alarm daemon</application> directly from the command +line:</para> + +<screen width="40"> +<prompt>%</prompt> <userinput><command>kalarmd</command></userinput> +</screen> + +</sect2> + +<sect2 id="daemon-reset"> +<title>Resetting the <application>alarm daemon</application></title> + +<para>It is also possible to reset the <application>alarm +daemon</application> without stopping it. Resetting causes the +<application>alarm daemon</application> to re-read the list of +scheduled messages from the calendar file and re-initialize its +&kalarm;-related data.</para> + +<para>Why might you want to reset the <application>alarm +daemon</application>? It isn't a very likely occurrence, but if for +any reason &kalarm; was not able to run when the <application>alarm +daemon</application> told it to trigger an alarm, that alarm will +never be displayed or executed until the <application>alarm +daemon</application> is either reset or restarted.</para> + +<tip><para>Resetting starts the <application>alarm +daemon</application> if it is not currently running.</para></tip> + +<para>To reset the <application>alarm daemon</application>, either use +the menu command <menuchoice> +<guimenu>Actions</guimenu><guimenuitem>Refresh Alarms</guimenuitem> +</menuchoice> or type the following command:</para> + +<screen width="40"> +<prompt>%</prompt> <userinput><command>kalarm</command> <option>--reset</option></userinput> +</screen> + +</sect2> + +<sect2> +<title>Stopping the <application>alarm daemon</application></title> + +<para>Stopping the <application>alarm daemon</application> will +prevent any further monitoring of scheduled alarm messages until the +daemon is restarted.</para> + +<para>To stop the <application>alarm daemon</application>, type the +following command:</para> + +<screen width="40"> +<prompt>%</prompt> <userinput><command>kalarm</command> <option>--stop</option></userinput> +</screen> +</sect2> + +</sect1> +</chapter> + +<chapter id="developers"> +<title>Developer's Guide to &kalarm;</title> + +<para>&kalarm; provides an interface to allow other applications to +request the following functions:</para> + +<itemizedlist> +<listitem><para>schedule a new alarm</para></listitem> +<listitem><para>trigger or cancel an already scheduled +alarm</para></listitem> +<listitem><para>cancel an already scheduled alarm</para></listitem> +<listitem><para>trigger an already scheduled alarm</para></listitem> +<listitem><para>display the alarm edit dialog</para></listitem> +</itemizedlist> + +<para>Each of the above functions is implemented both by a &DCOP; call +and by the command line. &DCOP; calls should be used in preference if +&kalarm; is already running.</para> + +<sect1 id="dcop-interface"> +<title>&DCOP; interface</title> + +<para>The DCOP calls described in this document are all implemented in +&kalarm;'s <constant>request</constant> DCOP object. The interface is +defined in the file <filename>kalarmiface.h</filename>.</para> + +<note><para>In &kalarm; version 1.2, the DCOP interface was completely +revised to allow easier calling of functions, and to conform better to +the standard &kde; DCOP configuration. The old DCOP interface is +currently still usable for compatibility purposes, but will be removed +at some future date.</para></note> + +<refentry id="cancelEvent"> +<refmeta> +<refentrytitle>cancelEvent</refentrytitle> +</refmeta> +<refnamediv> +<refname>cancelEvent</refname> +<refpurpose>cancel an already scheduled alarm.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +void cancelEvent(const QString& <replaceable>calendarFile</replaceable>, + const QString& <replaceable>eventID</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>calendarFile</parameter></term> +<listitem> +<para>Specifies the &URL; (not path) of the calendar file containing +the event to be canceled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>eventID</parameter></term> +<listitem> +<para>Specifies the unique ID of the event to be canceled, as stored +in <replaceable>calendarFile</replaceable>.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><function>cancelEvent()</function> is a &DCOP; call to cancel +the specified alarm. &kalarm; deletes the alarm from the calendar file +without displaying or executing it.</para> + +<note><para>The <replaceable>calendarFile</replaceable> parameter is +only used for integrity checking: if the &URL; does not specify +&kalarm;'s current default calendar file, the request will be +ignored.</para></note> + +</refsect1> +</refentry> + +<refentry id="triggerEvent"> +<refmeta> +<refentrytitle>triggerEvent</refentrytitle> +</refmeta> +<refnamediv> +<refname>triggerEvent</refname> +<refpurpose>trigger an already scheduled alarm.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +void triggerEvent(const QString& <replaceable>calendarFile</replaceable>, + const QString& <replaceable>eventID</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>calendarFile</parameter></term> +<listitem> +<para>Specifies the &URL; (not path) of the calendar file containing +the event to be triggered.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>eventID</parameter></term> +<listitem> +<para>Specifies the unique ID of the event to be triggered, as stored +in <replaceable>calendarFile</replaceable>.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><function>triggerEvent()</function> is a &DCOP; call to trigger +the immediate display or execution of the specified alarm (regardless +of what time it is scheduled for). &kalarm; retrieves the alarm from +the calendar file and then displays or executes it.</para> + +<para>If the alarm is already due, &kalarm; then deletes all scheduled +occurrences of the alarm up to the current time, and if no repetitions +of the alarm still remain, the alarm is deleted from the calendar +file. If the alarm is not due yet, its scheduled occurrences are left +unchanged.</para> + +<note><para>The <replaceable>calendarFile</replaceable> parameter is +only used for integrity checking: if the &URL; does not specify +&kalarm;'s current default calendar file, the request will be +ignored.</para></note> + +</refsect1> +</refentry> + +<refentry id="handleEvent"> +<refmeta> +<refentrytitle>handleEvent</refentrytitle> +</refmeta> +<refnamediv> +<refname>handleEvent</refname> +<refpurpose>trigger or cancel an already scheduled alarm.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +void handleEvent(const QString& <replaceable>calendarFile</replaceable>, + const QString& <replaceable>eventID</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>calendarFile</parameter></term> +<listitem> +<para>Specifies the &URL; (not path) of the calendar file containing +the event to be displayed/executed or canceled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>eventID</parameter></term> +<listitem> +<para>Specifies the unique ID of the event to be displayed/executed or +canceled, as stored in +<replaceable>calendarFile</replaceable>.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><function>handleEvent()</function> is a &DCOP; call to +display/execute or cancel the specified alarm. &kalarm; retrieves the +alarm from the calendar file and then determines what action to take +depending on when the alarm is due.</para> + +<itemizedlist> +<listitem><para>If the alarm is not yet due, nothing happens.</para> +</listitem> + +<listitem><para>If the alarm is due, it acts as follows. If a +late-cancel value is set and the alarm is too late, &ie; the scheduled +trigger time was longer than late-cancel minutes ago, &kalarm; does +not display or execute the alarm; otherwise, &kalarm; displays or +executes the alarm. If no repetitions of the alarm are still +scheduled, &kalarm; then deletes the alarm from the calendar +file.</para> +</listitem> +</itemizedlist> + +<note><para>The <replaceable>calendarFile</replaceable> parameter is +only used for integrity checking: if the &URL; does not specify +&kalarm;'s current default calendar file, the request will be +ignored.</para></note> + +</refsect1> +</refentry> + +<refentry id="scheduleMessage"> +<refmeta> +<refentrytitle>scheduleMessage</refentrytitle> +</refmeta> +<refnamediv> +<refname>scheduleMessage</refname> +<refpurpose>schedule a new alarm message.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +bool scheduleMessage(const QString& <replaceable>message</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const QString& <replaceable>fgColor</replaceable>, + const QString& <replaceable>font</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + const QString& <replaceable>recurrence</replaceable>, + int <replaceable>subRepeatInterval</replaceable>, + int <replaceable>subRepeatCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleMessage(const QString& <replaceable>message</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const QString& <replaceable>fgColor</replaceable>, + const QString& <replaceable>font</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + int <replaceable>recurCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleMessage(const QString& <replaceable>message</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const QString& <replaceable>fgColor</replaceable>, + const QString& <replaceable>font</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + const QString& <replaceable>endDateTime</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>message</parameter></term> +<listitem> +<para>Specifies the text of the message to be scheduled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>dateTime</parameter></term> +<listitem> +<para>Specifies the scheduled date, or date and time, at which the +message should be displayed. For a date-only alarm, the string should +be in the format <quote>YYYY-MM-DD</quote> (as returned by +<methodname>QDate::toString(Qt::ISODate)</methodname>). For an alarm +with a date and time, the string should be in the format +<quote>YYYY-MM-DDTHH:MM[:SS]</quote> (as returned by +<methodname>QDateTime::toString(Qt::ISODate)</methodname>) or +<quote>HH:MM[:SS]</quote> (as returned by +<methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is +specified, today's date is used. Note that any seconds value is +ignored.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>lateCancel</parameter></term> +<listitem> +<para>Causes the alarm to be canceled if it cannot be triggered within +the specified number of minutes after the alarm's scheduled time. If +the value is 0, the alarm will not be canceled no matter how late it +is triggered.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>flags</parameter></term> +<listitem> +<para>Specifies the logical OR of the desired alarm flags. The flag +bits are those defined in class <classname>KAlarmIface</classname> in +<filename>kalarmiface.h</filename>. Note that not all flag bits are +applicable to message alarms.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>bgColor</parameter></term> +<listitem> +<para>Specifies the background color for displaying the message. The +string may be in the format <quote>#RRGGBB</quote> (as returned by +<methodname>QColor::name()</methodname>) where RR, GG and BB are +two-digit hexadecimal values for red, green and blue. Alternatively +the string may be in any of the other formats accepted by +<methodname>QColor::setNamedColor()</methodname>, such as a name from +the X color database (⪚ <quote>red</quote> or +<quote>steelblue</quote>). Set the string to null to specify the +current default background color.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>fgColor</parameter></term> +<listitem> +<para>Specifies the foreground color for displaying the message. The +format of the string is the same as for +<parameter>bgColor</parameter>, or alternatively set the string to +null to specify the current default foreground color.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>font</parameter></term> +<listitem> +<para>Specifies the font for displaying the message. The format of the +string is that output by <methodname>QFont::toString()</methodname>. +Set the string to null to use the default message font current at the +time the message is displayed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>audioURL</parameter></term> +<listitem> +<para>Specifies the audio file which is to be played when the message +is displayed. Set the value to null if no audio file is to be +played.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>reminder</parameter></term> +<listitem> +<para>Specifies the number of minutes in advance of the main alarm +and of each of its recurrences (if any) at which a reminder alarm +should be displayed. Specify 0 if no reminder is required.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurrence</parameter></term> +<listitem> +<para>Specifies a regular recurrence for the alarm, using iCalendar +syntax as defined in +<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. +For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> +would specify 4 repetitions at 3-monthly intervals on the last Monday +of the month. For a non-recurring alarm, specify an empty +string.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurType</parameter></term> +<listitem> +<para>Specifies the recurrence type for the alarm. The permissible +values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These +are defined in class <classname>KAlarmIface</classname> in +<filename>kalarmiface.h</filename>. Monthly recurrences are of the +day of the month type, and yearly recurrences are of the date in +the year type, with the date in both cases taken from the +<parameter>dateTime</parameter> parameter.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurInterval</parameter></term> +<listitem> +<para>Specifies the number of periods +(minutes/days/weeks/months/years as specified by +<parameter>recurType</parameter>) between recurrences of the +alarm.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurCount</parameter></term> +<listitem> +<para>Specifies the number of times that the alarm should be +repeated. Specify -1 to repeat the alarm indefinitely.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>endDateTime</parameter></term> +<listitem> +<para>Specifies the end date, or date and time, for recurrences of the +alarm. If <parameter>dateTime</parameter> includes a time, this +parameter must also include a time; if <parameter>dateTime</parameter> +contains only a date, this parameter must also contain only a +date.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subRepeatInterval</parameter></term> +<listitem> +<para>Specifies the number of minutes between sub-repetitions of +the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence +is specified.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subRepeatCount</parameter></term> +<listitem> +<para>Specifies the number of sub-repetitions of the alarm, +including the initial occurrence.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> +</refsynopsisdiv> + +<refsect1 id="scheduleMessage-descrip"> +<title>Description</title> +<para><function>scheduleMessage()</function> is a &DCOP; call to +schedule the specified alarm message for display at the specified date +and time. It has three forms. The most general form allows an +arbitrary recurrence to be specified – use this also for +non-repeating alarms. The other forms provide convenient access to a +restricted set of alarm recurrence types, one specifying a repetition +count and the other an end time.</para> + +<para>If the scheduled time (including any repetitions) has already +passed, &kalarm; immediately displays the message (unless the +<parameter>lateCancel</parameter> value indicates that it is now too +late to display the alarm, in which case &kalarm; ignores the +request). If the scheduled time (or a repetition) is in the future, +&kalarm; adds the alarm message to the calendar file for later +display.</para> +</refsect1> +</refentry> + +<refentry id="scheduleFile"> +<refmeta> +<refentrytitle>scheduleFile</refentrytitle> +</refmeta> +<refnamediv> +<refname>scheduleFile</refname> +<refpurpose>schedule a new alarm which displays the contents of a +text or image file.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +bool scheduleFile(const KURL& <replaceable>URL</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + const QString& <replaceable>recurrence</replaceable>, + int <replaceable>subRepeatInterval</replaceable>, + int <replaceable>subRepeatCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleFile(const KURL& <replaceable>URL</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + int <replaceable>recurCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleFile(const KURL& <replaceable>URL</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + const QString& <replaceable>endDateTime</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>URL</parameter></term> +<listitem> +<para>Specifies the text or image file whose contents are to be +displayed in the message to be scheduled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>dateTime</parameter></term> +<listitem> +<para>Specifies the scheduled date, or date and time, at which the +file should be displayed. For a date-only alarm, the string should +be in the format <quote>YYYY-MM-DD</quote> (as returned by +<methodname>QDate::toString(Qt::ISODate)</methodname>). For an alarm +with a date and time, the string should be in the format +<quote>YYYY-MM-DDTHH:MM[:SS]</quote> (as returned by +<methodname>QDateTime::toString(Qt::ISODate)</methodname>) or +<quote>HH:MM[:SS]</quote> (as returned by +<methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is +specified, today's date is used. Note that any seconds value is +ignored.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>lateCancel</parameter></term> +<listitem> +<para>Causes the alarm to be canceled if it cannot be triggered within +the specified number of minutes after the alarm's scheduled time. If +the value is 0, the alarm will not be canceled no matter how late it +is triggered.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>flags</parameter></term> +<listitem> +<para>Specifies the logical OR of the desired alarm flags. The flag +bits are those defined in class <classname>KAlarmIface</classname> in +<filename>kalarmiface.h</filename>. Note that not all flag bits are +applicable to file alarms.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>bgColor</parameter></term> +<listitem> +<para>Specifies the background color for displaying the file. The +string may be in the format <quote>#RRGGBB</quote> (as returned by +<methodname>QColor::name()</methodname>) where RR, GG and BB are +two-digit hexadecimal values for red, green and blue. Alternatively +the string may be in any of the other formats accepted by +<methodname>QColor::setNamedColor()</methodname>, such as a name from +the X color database (⪚ <quote>red</quote> or +<quote>steelblue</quote>). Set the string to null to specify the +current default background color.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>audioURL</parameter></term> +<listitem> +<para>Specifies the audio file which is to be played when the message +is displayed. Set the value to null if no audio file is to be +played.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>reminder</parameter></term> +<listitem> +<para>Specifies the number of minutes in advance of the main alarm +and of each of its recurrences (if any) at which a reminder alarm +should be displayed. Specify 0 if no reminder is required.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurrence</parameter></term> +<listitem> +<para>Specifies a regular recurrence for the alarm, using iCalendar +syntax as defined in +<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. +For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> +would specify 4 repetitions at 3-monthly intervals on the last Monday +of the month. For a non-recurring alarm, specify an empty +string.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurType</parameter></term> +<listitem> +<para>Specifies the recurrence type for the alarm. The permissible +values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These +are defined in class <classname>KAlarmIface</classname> in +<filename>kalarmiface.h</filename>. Monthly recurrences are of the +day of the month type, and yearly recurrences are of the date in +the year type, with the date in both cases taken from the +<parameter>dateTime</parameter> parameter.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurInterval</parameter></term> +<listitem> +<para>Specifies the number of periods +(minutes/days/weeks/months/years as specified by +<parameter>recurType</parameter>) between recurrences of the +alarm.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurCount</parameter></term> +<listitem> +<para>Specifies the number of times that the alarm should be +repeated. Specify -1 to repeat the alarm indefinitely.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>endDateTime</parameter></term> +<listitem> +<para>Specifies the end date, or date and time, for recurrences of the +alarm. If <parameter>dateTime</parameter> includes a time, this +parameter must also include a time; if <parameter>dateTime</parameter> +contains only a date, this parameter must also contain only a +date.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subRepeatInterval</parameter></term> +<listitem> +<para>Specifies the number of minutes between sub-repetitions of +the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence +is specified.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subRepeatCount</parameter></term> +<listitem> +<para>Specifies the number of sub-repetitions of the alarm, +including the initial occurrence.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para><function>scheduleFile()</function> is a &DCOP; call to schedule +the specified text or image file for display at the specified date and +time. Apart from specifying a file path or &URL; and omitting the +foreground color and font, its usage is identical to +<link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link> +- see the description of that function for further details.</para> +</refsect1> +</refentry> + + +<refentry id="scheduleCommand"> +<refmeta> +<refentrytitle>scheduleCommand</refentrytitle> +</refmeta> +<refnamediv> +<refname>scheduleCommand</refname> +<refpurpose>schedule a new alarm which executes a shell +command.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +bool scheduleCommand(const QString& <replaceable>commandLine</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>recurrence</replaceable>, + int <replaceable>subRepeatInterval</replaceable>, + int <replaceable>subRepeatCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleCommand(const QString& <replaceable>commandLine</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + int <replaceable>recurCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleCommand(const QString& <replaceable>commandLine</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + const QString& <replaceable>endDateTime</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>commandLine</parameter></term> +<listitem> +<para>Specifies the command whose execution is to be scheduled. The +<parameter>flags</parameter> parameter indicates whether this +parameter contains a shell command line or a command script.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>dateTime</parameter></term> +<listitem> +<para>Specifies the scheduled date, or date and time, at which the +command should be executed. For a date-only alarm, the string should +be in the format <quote>YYYY-MM-DD</quote> (as returned by +<methodname>QDate::toString(Qt::ISODate)</methodname>). For an alarm +with a date and time, the string should be in the format +<quote>YYYY-MM-DDTHH:MM[:SS]</quote> (as returned by +<methodname>QDateTime::toString(Qt::ISODate)</methodname>) or +<quote>HH:MM[:SS]</quote> (as returned by +<methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is +specified, today's date is used. Note that any seconds value is +ignored.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>lateCancel</parameter></term> +<listitem> +<para>Causes the alarm to be canceled if it cannot be triggered within +the specified number of minutes after the alarm's scheduled time. If +the value is 0, the alarm will not be canceled no matter how late it +is triggered.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>flags</parameter></term> +<listitem> +<para>Specifies the logical OR of the desired alarm flags. The flag +bits are those defined in class <classname>KAlarmIface</classname> in +<filename>kalarmiface.h</filename>. Note that not all flag bits are +applicable to command alarms.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurrence</parameter></term> +<listitem> +<para>Specifies a regular recurrence for the alarm, using iCalendar +syntax as defined in +<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. +For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> +would specify 4 repetitions at 3-monthly intervals on the last Monday +of the month. For a non-recurring alarm, specify an empty +string.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurType</parameter></term> +<listitem> +<para>Specifies the recurrence type for the alarm. The permissible +values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These +are defined in class <classname>KAlarmIface</classname> in +<filename>kalarmiface.h</filename>. Monthly recurrences are of the +day of the month type, and yearly recurrences are of the date in +the year type, with the date in both cases taken from the +<parameter>dateTime</parameter> parameter.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurInterval</parameter></term> +<listitem> +<para>Specifies the number of periods +(minutes/days/weeks/months/years as specified by +<parameter>recurType</parameter>) between recurrences of the +alarm.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurCount</parameter></term> +<listitem> +<para>Specifies the number of times that the alarm should be +repeated. Specify -1 to repeat the alarm indefinitely.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>endDateTime</parameter></term> +<listitem> +<para>Specifies the end date, or date and time, for recurrences of the +alarm. If <parameter>dateTime</parameter> includes a time, this +parameter must also include a time; if <parameter>dateTime</parameter> +contains only a date, this parameter must also contain only a +date.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subRepeatInterval</parameter></term> +<listitem> +<para>Specifies the number of minutes between sub-repetitions of +the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence +is specified.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subRepeatCount</parameter></term> +<listitem> +<para>Specifies the number of sub-repetitions of the alarm, +including the initial occurrence.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para><function>scheduleCommand()</function> is a &DCOP; call to +schedule the specified shell command line, or command script, for +execution at the specified date and time. Apart from specifying a +command and omitting the message color, font and audio file +parameters, its usage is identical to +<link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link> +- see the description of that function for further details.</para> +</refsect1> +</refentry> + + +<refentry id="scheduleEmail"> +<refmeta> +<refentrytitle>scheduleEmail</refentrytitle> +</refmeta> +<refnamediv> +<refname>scheduleEmail</refname> +<refpurpose>schedule a new alarm which sends an email.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +bool scheduleEmail(const QString& <replaceable>fromID</replaceable>, + const QString& <replaceable>addresses</replaceable>, + const QString& <replaceable>subject</replaceable>, + const QString& <replaceable>message</replaceable>, + const QString& <replaceable>attachments</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>recurrence</replaceable>, + int <replaceable>subRepeatInterval</replaceable>, + int <replaceable>subRepeatCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleEmail(const QString& <replaceable>fromID</replaceable>, + const QString& <replaceable>addresses</replaceable>, + const QString& <replaceable>subject</replaceable>, + const QString& <replaceable>message</replaceable>, + const QString& <replaceable>attachments</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + int <replaceable>recurCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleEmail(const QString& <replaceable>fromID</replaceable>, + const QString& <replaceable>addresses</replaceable>, + const QString& <replaceable>subject</replaceable>, + const QString& <replaceable>message</replaceable>, + const QString& <replaceable>attachments</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + nt <replaceable>flags</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + const QString& <replaceable>endTime</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>fromID</parameter></term> +<listitem> +<para>The &kmail; identity to use as the sender of the email. If +empty, the sender's email address will be that configured in +&kalarm;'s +<link linkend="preferences-email">Email preferences</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>addresses</parameter></term> +<listitem> +<para>A comma separated list of recipients' email addresses.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subject</parameter></term> +<listitem> +<para>Specifies the subject line of the email.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>message</parameter></term> +<listitem> +<para>Specifies the email message body.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>attachments</parameter></term> +<listitem> +<para>A comma-separated list of paths or &URL;s of files to send as +email attachments.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>dateTime</parameter></term> +<listitem> +<para>Specifies the scheduled date, or date and time, at which the +email should be sent. For a date-only alarm, the string should +be in the format <quote>YYYY-MM-DD</quote> (as returned by +<methodname>QDate::toString(Qt::ISODate)</methodname>). For an alarm +with a date and time, the string should be in the format +<quote>YYYY-MM-DDTHH:MM[:SS]</quote> (as returned by +<methodname>QDateTime::toString(Qt::ISODate)</methodname>) or +<quote>HH:MM[:SS]</quote> (as returned by +<methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is +specified, today's date is used. Note that any seconds value is +ignored.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>lateCancel</parameter></term> +<listitem> +<para>Causes the alarm to be canceled if it cannot be triggered within +the specified number of minutes after the alarm's scheduled time. If +the value is 0, the alarm will not be canceled no matter how late it +is triggered.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>flags</parameter></term> +<listitem> +<para>Specifies the logical OR of the desired alarm flags. The flag +bits are those defined in class <classname>KAlarmIface</classname> in +<filename>kalarmiface.h</filename>. Note that not all flag bits are +applicable to email alarms.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurrence</parameter></term> +<listitem> +<para>Specifies a regular recurrence for the alarm, using iCalendar +syntax as defined in +<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. +For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> +would specify 4 repetitions at 3-monthly intervals on the last Monday +of the month. For a non-recurring alarm, specify an empty +string.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurType</parameter></term> +<listitem> +<para>Specifies the recurrence type for the alarm. The permissible +values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These +are defined in class <classname>KAlarmIface</classname> in +<filename>kalarmiface.h</filename>. Monthly recurrences are of the +day of the month type, and yearly recurrences are of the date in +the year type, with the date in both cases taken from the +<parameter>dateTime</parameter> parameter.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurInterval</parameter></term> +<listitem> +<para>Specifies the number of periods +(minutes/days/weeks/months/years as specified by +<parameter>recurType</parameter>) between recurrences of the +alarm.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>recurCount</parameter></term> +<listitem> +<para>Specifies the number of times that the alarm should be +repeated. Specify -1 to repeat the alarm indefinitely.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>endDateTime</parameter></term> +<listitem> +<para>Specifies the end date, or date and time, for recurrences of the +alarm. If <parameter>dateTime</parameter> includes a time, this +parameter must also include a time; if <parameter>dateTime</parameter> +contains only a date, this parameter must also contain only a +date.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subRepeatInterval</parameter></term> +<listitem> +<para>Specifies the number of minutes between sub-repetitions of +the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence +is specified.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>subRepeatCount</parameter></term> +<listitem> +<para>Specifies the number of sub-repetitions of the alarm, +including the initial occurrence.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para><function>scheduleEmail()</function> is a &DCOP; call to +schedule the specified email for sending at the specified date and +time. Apart from specifying the email header and contents and omitting +the message color, font and audio file parameters, its usage is +identical to +<link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link> +- see the description of that function for further details.</para> +</refsect1> +</refentry> + +<refentry id="dcop_edit"> +<refmeta> +<refentrytitle>edit</refentrytitle> +</refmeta> +<refnamediv> +<refname>edit</refname> +<refpurpose>Display the <link linkend="alarm-edit-dlg">alarm edit +dialog</link> to edit an alarm.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +bool edit(const QString& <replaceable>eventID</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>eventID</parameter></term> +<listitem> +<para>Specifies the unique ID of the event to be edited.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> + +<refsect2> +<title>Return value</title> +<para><returnvalue>false</returnvalue> if the specified +alarm could not be found or is read-only, +<returnvalue>true</returnvalue> otherwise.</para> +</refsect2> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><function>edit()</function> is a &DCOP; call to display the +<link linkend="alarm-edit-dlg">alarm edit dialog</link> to edit the +specified alarm.</para> + +</refsect1> +</refentry> + +<refentry id="dcop_editnew"> +<refmeta> +<refentrytitle>editNew</refentrytitle> +</refmeta> +<refnamediv> +<refname>editNew</refname> +<refpurpose>Display the <link linkend="alarm-edit-dlg">alarm edit +dialog</link> to edit a new alarm.</refpurpose> +</refnamediv> +<refsynopsisdiv> +<synopsis> +bool editNew(const QString& <replaceable>templateName</replaceable>) +</synopsis> + +<refsect2> +<title>Parameters</title> +<variablelist> +<varlistentry> +<term><parameter>templateName</parameter></term> +<listitem> +<para>Specifies the name of an alarm template to base the new alarm +on, or empty if no template should be used.</para> +</listitem> +</varlistentry> +</variablelist> +</refsect2> + +<refsect2> +<title>Return value</title> +<para><returnvalue>false</returnvalue> if +<parameter>templateName</parameter> is non-empty but a template of +that name cannot be found, <returnvalue>true</returnvalue> +otherwise.</para> +</refsect2> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para><function>editNew()</function> is a &DCOP; call to display the +<link linkend="alarm-edit-dlg">alarm edit dialog</link> to edit a new +alarm. If an alarm template name is specified as a parameter, the +dialog is preset with details from the template. If the specified +template cannot be found, the +<link linkend="alarm-edit-dlg">alarm edit dialog</link> is still +displayed but is (obviously) not preset with the template.</para> + +</refsect1> +</refentry> + +</sect1> + +<sect1 id="cmdline-interface"> +<title>Command line interface</title> + +<para>Command line options are provided to enable other programs (such +as the <application>alarm daemon</application>) to start up &kalarm; +if it is not already running, in order to trigger or cancel scheduled +alarms, or schedule new alarms. The reason for using command line +options for this purpose is that if &kalarm; were started without any +command line parameters and then sent &DCOP; requests, it would start +in its default graphical mode, which is clearly undesirable for an +inter-program request.</para> + +<note><para>Programs should first check whether &kalarm; is already +running; if it is, they should instead use &DCOP; calls to request these +operations.</para></note> + +<para>The command line options for scheduling a new alarm are as +described in the chapter <link linkend="cmdline-operation">Command line +operation</link>. The options for triggering and canceling scheduled +alarms are as follows:</para> + +<note><para>Normal users may also if they wish use these command line +options (assuming that they can supply the necessary parameter +information).</para></note> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> + <entry>Option</entry> + <entry>Description</entry> +</row> +</thead> +<tbody> +<row> + <entry><option>--calendarURL <replaceable>url</replaceable></option></entry> + <entry>Use the calendar file with the specified &URL;. This option + is only used for integrity checking: if the &URL; doesn't specify + &kalarm;'s current default calendar file, the request will be + ignored.</entry> +</row> +<row> + <entry><option>--cancelEvent <replaceable>eventID</replaceable></option></entry> + <entry>Cancel the alarm with the specified event ID.</entry> +</row> +<row> + <entry><option>--triggerEvent <replaceable>eventID</replaceable></option></entry> + <entry>Trigger the alarm with the specified event ID. The action + taken is the same as for the + <link linkend="triggerEvent">triggerEvent()</link> &DCOP; + call.</entry> +</row> +<row> + <entry><option>--handleEvent <replaceable>eventID</replaceable></option></entry> + <entry>Trigger or cancel the alarm with the specified event + ID. &kalarm; determines which action to take in the same way as for + the <link linkend="handleEvent">handleEvent()</link> &DCOP; call.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para><option>--cancelEvent</option>, <option>--triggerEvent</option> +and <option>--handleEvent</option> are mutually +exclusive. <option>--calendarURL</option> is optional, but can only be +used with one of the other three options.</para> + +<para>Examples are:</para> + +<informalexample><screen> +<prompt>%</prompt> <userinput><command>kalarm</command> <option>--triggerEvent <replaceable>&kalarm;-387486299.702</replaceable></option> <option>--calendarURL <replaceable>file:/home/zaphod/hydra.ics</replaceable></option></userinput> +<prompt>%</prompt> <userinput><command>kalarm</command> <option>--cancelEvent <replaceable>&kalarm;-388886299.793</replaceable></option></userinput> +</screen> +</informalexample> + +</sect1> +</chapter> + + +<chapter id="faq"> +<title>Questions and Answers</title> + +&reporting.bugs; +&updating.documentation; + +<qandaset id="faqlist"> +<qandaentry> +<question> +<para>What is the alarm daemon?</para> +</question> +<answer> +<para>The <application>alarm daemon</application> is an application +which runs in the background, monitoring alarms and telling &kalarm; +to trigger them when they become due.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What configuration files does &kalarm; use?</para> +</question> +<answer> +<para>The file <filename>$KDEHOME/share/config/kalarmrc</filename> +holds your &kalarm; preferences.</para> + +<para>The calendar file which stores your pending alarms is +<filename>$KDEHOME/share/apps/kalarm/calendar.ics</filename>, unless +a different calendar file is specified in the preferences file by a +<parameter>Calendar</parameter> entry in the +<parameter>General</parameter> section.</para> + +<para>The calendar file which stores your expired alarms is +<filename>$KDEHOME/share/apps/kalarm/expired.ics</filename>, unless +a different calendar file is specified in the preferences file by an +<parameter>ExpiredCalendar</parameter> entry in the +<parameter>General</parameter> section.</para> + +<para>The calendar file which stores your alarm templates is +<filename>$KDEHOME/share/apps/kalarm/template.ics</filename>, unless +a different calendar file is specified in the preferences file by a +<parameter>TemplateCalendar</parameter> entry in the +<parameter>General</parameter> section.</para> + +<para>Details of alarms currently being displayed are stored in the +calendar file +<filename>$KDEHOME/share/apps/kalarm/displaying.ics</filename>.</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What configuration files does the <application>alarm +daemon</application> use?</para> +</question> +<answer> +<para>The file <filename>$KDEHOME/share/config/kalarmdrc</filename> +holds your <application>alarm daemon</application> preferences, +together with details of the &kalarm; client application.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What format are alarms stored in?</para> +</question> +<answer> +<para>The calendar files in which &kalarm; stores its alarms are text +files whose format is defined by the document +<ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445 - +Internet Calendaring and Scheduling Core Object Specification +(iCalendar)</ulink>. This is the standard format used by all kdepim +applications. &kalarm; uses certain non-standard properties in the +Alarm component, in conformance with RFC2445: +<literal>X-KDE-KALARM-NEXTRECUR</literal>, +<literal>X-KDE-KALARM-REPEAT</literal>, +<literal>X-KDE-KALARM-TYPE</literal>, +<literal>X-KDE-KALARM-NEXTREPEAT</literal>, +<literal>X-KDE-KALARM-FONTCOLOR</literal>, +<literal>X-KDE-KALARM-VOLUME</literal>, +<literal>X-KDE-KALARM-SPEAK</literal>, +<literal>X-KDE-KALARM-EMAILID</literal>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What are the application names of &kalarm; and the +<application>alarm daemon</application>?</para> +</question> +<answer> +<para>&kalarm;'s application name is <application>kalarm</application>, +and the <application>alarm daemon</application>'s application name is +<application>kalarmd</application>.</para> +</answer> +</qandaentry> + +</qandaset> +</chapter> + + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kalarm; +</para> +<para> +Program copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 David Jarvie <email>&David.Jarvie.mail;</email> +</para> +<para> +Alarm daemon authors: +<itemizedlist> +<listitem><para>Preston Brown <email>pbrown@kde.org</email></para> +</listitem> +<listitem><para>David Jarvie <email>&David.Jarvie.mail;</email></para> +</listitem> +<listitem><para>Cornelius Schumacher <email>schumacher@kde.org</email></para> +</listitem> +</itemizedlist> +</para> + +<para> +Documentation copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 David Jarvie <email>&David.Jarvie.mail;</email> +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> + +&underGPL; <!-- GPL License --> + +<para>Thanks go to the author of the &kde; 1 KAlarm application, +Stefan Nikolaus <email>stefan.nikolaus@stuco.uni-oldenburg.de</email>, +who kindly agreed to allow the name &kalarm; to be used by this +&kde; 2 / &kde; 3 application. +</para> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kalarm"> +<title>How to obtain &kalarm;</title> + +&install.intro.documentation; + +<para>&kalarm; is available for &kde; 2 and as a standalone package for +&kde;3 from <ulink url="http://www.astrojar.org.uk/kalarm">http://www.astrojar.org.uk/kalarm</ulink> +</para> + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>&kalarm; requires the standard &kde; libraries to be installed +(the <filename>kdelibs</filename> package). To compile from source, +you also need the &Qt; and <filename>kdelibs</filename> development +packages. The X11 development package, if present, is used to improve +&kalarm;'s ability to function under &kde; without a system +tray.</para> + +<para>The following optional packages enhance &kalarm; at runtime if +they are installed:</para> + +<itemizedlist> +<listitem><para>&kmix; (from kdemultimedia package): if installed, it +allows &kalarm; to set the absolute sound volume when playing audio +files.</para> +</listitem> + +<listitem><para><application>KTTSD</application> (from +kdeaccessibility package): if installed and configured, together with +a compatible speech synthesizer package, it allows &kalarm; to speak +alarm messages when they are displayed.</para> +</listitem> +</itemizedlist> + +<para>&kalarm; uses about 12 Mb and the <application>alarm +daemon</application> uses about 2.5 Mb of memory to run, but this may +vary depending on your platform and configuration.</para> + +<para>You can find a list of changes in the +<filename>ChangeLog</filename> file, or at <ulink +url="http://www.astrojar.org.uk/kalarm">http://www.astrojar.org.uk/kalarm</ulink>.</para> +</sect1> + +<sect1 id="compilation"> +<title>Compilation and installation</title> + +<para>If you cannot obtain a suitable precompiled binary package, you +need to compile &kalarm; yourself from source files. Get the source +package file <filename>kdepim-x.x.tar.bz2</filename> or +<filename>kalarm-x.x.tar.bz2</filename> (or similar), depending on +whether you want to install &package; or just &kalarm;. Unpack it in a +new folder using a command similar to +<userinput><command>tar</command> <option>xvfj +<replaceable>package.tar.bz2</replaceable></option></userinput>, and +change to the folder which has been created.</para> + +&install.compile.documentation; + +<note><para>If you have more than one version of &kde; installed +(e.g. &kde; 2 and &kde; 3), this may possibly install &kalarm; into +the wrong &kde; folder. If necessary, you can give the &kde; folder +as a parameter to +<userinput><command>./configure</command></userinput> . For example, +if your &kde; is installed in <filename>/opt/kde2</filename>:</para> + +<para><userinput><command>./configure</command> --prefix=<replaceable>/opt/kde2</replaceable></userinput></para> +</note> + +<warning><para>If you install &kalarm; into a folder different from +where &kde; is installed, it will not run correctly unless you make +its location known to &kde;. To do this, you must prefix the +<envar>KDEDIRS</envar> environment variable with &kalarm;'s location, +each time before you start &kde;.</para> + +<para>For example, if &kde; is installed in +<literal>/opt/kde</literal>, <envar>KDEDIRS</envar> might normally +be set to <literal>/etc/opt/kde:/opt/kde</literal>. If you install +&kalarm; into <literal>/usr/local</literal>, you would need to set +<envar>KDEDIRS</envar> to +<literal>/usr/local:/etc/opt/kde:/opt/kde</literal> before starting +&kde;.</para></warning> + +<para>The standalone version of &kalarm; has a special configuration +option which allows you to select which languages documentation is to +be installed for by specifying a language code, or a list of language +codes, as a parameter to <command>./configure</command>. By default, +documentation in all available languages is installed. A list of +documentation languages included in the package, together with their +codes, is in the <filename>DOC-LANGUAGES</filename> file. For example, +to install only French and British English documentation:</para> + +<para><userinput><command>./configure</command> --enable-doc-language=<replaceable>"fr en_GB"</replaceable></userinput></para> + +<para>Note that this option has no effect on which user interface +translations are installed.</para> + +</sect1> + +<sect1 id="configuration"> +<title>Configuration</title> + +<para>No special configuration is required to set up &kalarm; to run +on the &kde; desktop. Once you have run &kalarm; for the first time, +the <application>alarm daemon</application> will start every time you +log in, in order to monitor scheduled alarms.</para> + +<para>To run &kalarm; on a non-&kde; desktop, the main requirement is +to ensure that the <application>alarm daemon</application> is run +automatically whenever you log in. More detailed instructions are +contained in the <filename>INSTALL</filename> file which is +distributed with &kalarm;.</para> + +</sect1> + +</appendix> + +&documentation.index; +</book> +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: +--> + |