2 <!DOCTYPE book PUBLIC
"-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
3 <!ENTITY kappname
"&kalarm;">
4 <!ENTITY package
"kdepim">
5 <!ENTITY % addindex
"IGNORE">
6 <!ENTITY % English
"INCLUDE"><!-- change language only here -->
9 <!-- The language must NOT be changed here. -->
11 <book lang=
"&language;">
14 <title>The
&kalarm; Handbook
</title>
18 <firstname>David
</firstname>
19 <surname>Jarvie
</surname>
21 <address>&David.Jarvie.mail;
</address>
25 <othercredit role=
"developer">
26 <firstname>David
</firstname>
27 <surname>Jarvie
</surname>
28 <affiliation><address>&David.Jarvie.mail;
</address></affiliation>
29 <contrib>Developer
</contrib>
32 <!-- TRANS:ROLES_OF_TRANSLATORS -->
36 <year>2001</year><year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year><year>2007</year><year>2008</year><year>2009</year><year>2010</year><year>2011</year>
37 <holder>&David.Jarvie;
</holder>
40 <legalnotice>&FDLNotice;</legalnotice>
42 <!-- Don't change format of date and version of the documentation -->
44 <date>2011-
05-
13</date>
45 <releaseinfo>2.07.00 (
&kde; 4.7)
</releaseinfo>
48 <para>&kalarm; is a personal alarm message, command and email scheduler for
&kde;.
</para>
53 <keyword>KDE
</keyword>
54 <keyword>kdepim
</keyword>
55 <keyword>kalarm
</keyword>
56 <keyword>alarm
</keyword>
57 <keyword>reminder
</keyword>
58 <keyword>scheduler
</keyword>
64 <chapter id=
"introduction">
65 <title>Introduction
</title>
67 <para>&kalarm; lets you schedule the display of personal alarm
68 messages, the playing of sound files, the execution of commands and
69 the sending of emails.
</para>
71 <para>In its default graphical mode,
&kalarm; displays the list of
72 pending alarms, showing their times and details. You can create new
73 alarms, or you can select existing alarms for modification or
74 deletion. You can also optionally view expired alarms.
</para>
76 <para>When configuring an alarm, you can choose whether it should
77 repeat, and whether the alarm should be canceled if it cannot be
78 triggered at its scheduled time. For display alarms, you can type in
79 a message text, specify a text or image file to display, or specify a
80 command whose output should be displayed. You can also choose the
81 color of the alarm message, and whether to play a sound or speak the
84 <para>Alarms may also be scheduled from the command line, or via
&DBus;
85 calls from programs.
</para>
87 <para>When an alarm message is due, it is displayed on each
&kde;
88 desktop to ensure that you don't miss it. The message window shows the
89 time for which the alarm was scheduled. It usually has a defer option
90 to ask for the alarm to be displayed again later. An example of an
94 <screeninfo>Screenshot of the
&kalarm; message window
</screeninfo>
97 <imagedata fileref=
"alarmmessage.png" format=
"PNG"/>
100 <phrase>Alarm message
</phrase>
105 <para>When the alarm specifies a command to execute or an email to
106 send,
&kalarm; displays nothing.
</para>
108 <para>&kalarm; usually shows an icon in the system tray, although this
109 can be hidden if desired.
</para>
113 <chapter id=
"using-kalarm">
114 <title>Using
&kalarm;</title>
116 <para>When it is run with no command line parameters,
&kalarm; starts
117 in graphical mode, and displays the current list of outstanding
120 <tip><para>All spin boxes in
&kalarm; have an acceleration facility.
121 To make the value change by larger steps, hold down the
122 &Shift; key while you click on the spin arrow
127 <imagedata fileref=
"spinbox.png" format=
"PNG"/>
132 <sect1 id=
"alarm-types">
133 <title>Alarm Types
</title>
135 <para>The basic functions available from the different alarm types
136 which
&kalarm; provides are:
</para>
140 <para>Display alarms display either a text message which you type in,
141 or the contents of a text or image file, or the textual output from a
142 command which is run when the alarm triggers. In addition to
143 displaying one of these items, they can also play audio files, have
144 their text spoken, or emit a simple beep. You can also specify
145 commands to be executed before and after the alarm message is
150 <para>Command alarms execute either a command or a shell script which
151 you can type in. Nothing is displayed unless an error occurs.
</para>
155 <para>Email alarms send a email. Nothing is displayed unless an error
160 <para>Audio alarms play an audio file. Nothing is displayed unless an
166 <title>Error Handling
</title>
168 <para>If an error occurs when an alarm triggers, an error message will
169 be displayed (unless you have previously specified not to show that
170 type of message again).
</para>
172 <para>If an execution error occurred the last time a command alarm
173 triggered, a white on red exclamation mark is shown in the message
174 color column. Details of the error are displayed in a tooltip if you
175 position the cursor over that line in the alarm list. The same error
176 indications are shown for display alarms if an execution error
177 occurred for a pre- or post-alarm command specified in the Special
178 Actions dialog, except that the color column is not changed to a red
184 <sect1 id=
"alarm-list">
185 <title>Alarm List
</title>
187 <para>The main
&kalarm; window displays the current list of pending
188 alarms, showing their times, repetition intervals, colors, and
189 message texts, names of files to play or display, commands to execute
190 or email subjects. (For a recurring alarm, the time shown is its next
191 scheduled trigger time. For an alarm with a reminder, the time shown
192 is the time of the alarm proper, not the reminder time.) An icon at
193 the left of each alarm text/file/command/email subject indicates the
194 type of alarm.
</para>
197 <screeninfo>Screenshot of the
&kalarm; main window
</screeninfo>
200 <imagedata fileref=
"mainwindow.png" format=
"PNG"/>
203 <phrase>Main window
</phrase>
208 <para>For a repeated alarm, the list shows its next scheduled trigger
209 time and its basic repetition interval (
⪚ <quote>1 Day
</quote> for
210 a daily recurrence,
<quote>3 Weeks
</quote> for a recurrence which
211 triggers on Monday and Wednesday every third week,
212 <quote>Login
</quote> for a repeat-at-login alarm).
</para>
214 <para>If an execution error occurred the last time a command alarm
215 triggered, or the last time a display alarm's pre- or post-alarm
216 command was executed, an error indication is shown in the color
217 column, as described in
<link linkend=
"errors">Error Handling
</link>
220 <sect2 id=
"listappear">
221 <title>Changing the Alarm List Appearance
</title>
223 <para>The alarms may be ordered by date/time, repeat interval, color,
224 type or text by clicking on the titlebar for the appropriate column.
225 To reverse the sort order, click the column titlebar again.
</para>
227 <para>You can optionally show the remaining time until each alarm is
228 due, together with, or instead of, the alarm's scheduled time.
229 To show or hide the alarm time column, select
230 <menuchoice><guimenu>View
</guimenu><guimenuitem>Show Alarm
231 Times
</guimenuitem></menuchoice>.
232 To show or hide the time-to-alarm column, select
233 <menuchoice><guimenu>View
</guimenu><guimenuitem>Show Time To
234 Alarms
</guimenuitem></menuchoice>. At least one of these columns is
237 <para>If you use multiple alarm calendars, you can color code alarms
238 according to which calendar they belong to, by selecting a different
239 background color for each calendar.
</para>
244 <title>Archived Alarms
</title>
246 <para>By default,
&kalarm; archives alarms for a limited period once
247 they have expired or been deleted. (But note that alarms which you
248 delete are stored only if they have already triggered at least once.)
249 You can control whether
&kalarm; archives expired alarms, and for how
251 <link linkend=
"preferences-storage">Configuration dialog
</link>.
</para>
253 <para>Archived alarms may be shown in the alarm list by selecting
254 <menuchoice><guimenu>View
</guimenu><guimenuitem>Show Archived
255 Alarms
</guimenuitem></menuchoice>. To hide them again, deselect
256 <menuchoice><guimenu>View
</guimenu><guimenuitem>Show Archived
257 Alarms
</guimenuitem></menuchoice>.
</para>
262 <title>Searching the Alarm List
</title>
264 <para>You can search through the alarm list to find alarms containing
265 a search text. To invoke this, select
<menuchoice>
266 <guimenu>Edit
</guimenu><guimenuitem>Find...
</guimenuitem></menuchoice>.
267 In the search dialog, select the alarm types which you wish to search.
268 To continue searching for more alarms which match, use
<menuchoice>
269 <guimenu>Edit
</guimenu><guimenuitem>Find Next
</guimenuitem></menuchoice>
271 <guimenu>Edit
</guimenu><guimenuitem>Find Previous
</guimenuitem>
272 </menuchoice>.
</para>
274 <para>Searching is performed as follows:
</para>
278 <para>Text message alarms: the message text is searched.
</para>
282 <para>File display alarms: the file path/
&URL; is searched.
</para>
286 <para>Command alarms: the command line or command script is
291 <para>Email alarms: in addition to the subject and body of the email,
292 the recipients and the URLs of attachments are searched.
</para>
296 <para>Audio alarms: the file path/
&URL; is searched.
</para>
300 <note><para>Only alarms currently shown in the alarm list can be
301 selected for searching. So if you want to search archived alarms, you
302 must first display them as described in the section above.
</para></note>
306 <sect1 id=
"create-edit">
307 <title>Creating and Manipulating Alarms
</title>
310 <title>Creating a New Alarm
</title>
312 <para>To create a new alarm, do one of the following, and then select
313 the type of alarm from the list which appears. This displays the
314 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> through which
315 you configure the alarm.
</para>
319 <para>Select
<menuchoice><guimenu>File
</guimenu>
320 <guimenuitem>New
</guimenuitem></menuchoice>.
</para>
324 <para><mousebutton>Right
</mousebutton> click on the system tray icon
326 <menuchoice><guimenuitem>New Alarm
</guimenuitem></menuchoice>
327 from the context menu.
</para>
331 <para><mousebutton>Right
</mousebutton> click in the alarm list and
332 choose
<menuchoice><guimenuitem>New
</guimenuitem></menuchoice> from
333 the context menu.
</para>
337 <para>Alternatively, you can create new alarms preconfigured from
338 various sources:
</para>
342 <para>To base your new alarm on an alarm template, follow the
343 instructions in the
<link linkend=
"templates">Alarm Templates
</link>
348 <para>To base your new alarm on an existing one, highlight the existing
349 alarm in the list and select
<menuchoice>
350 <guimenu>File
</guimenu><guimenuitem>Copy
</guimenuitem></menuchoice>.
351 This opens the
<link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>
352 already filled in with a copy of the selected alarm's details.
</para>
356 <para>To create a new alarm which displays an existing email message,
357 drag the email from
&kmail; onto
&kalarm;'s main window or system tray
358 icon. This opens the
<link linkend=
"alarm-edit-dlg">Alarm Edit
359 dialog
</link> with the entire email message (including sender,
360 recipient,
&etc;) as the alarm text.
</para>
364 <para>To create a new email alarm to send a copy of an existing email
365 message, drag the email from
&kmail; onto
&kalarm;'s main window or
366 system tray icon. Then select the
<guilabel>Email
</guilabel> option.
367 The
<link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> is preset
368 with the entire email message except sender.
</para>
372 <para>To create a new alarm which displays a summary of an existing
373 to-do, drag the to-do from
&korganizer; or other application onto
374 &kalarm;'s main window or system tray icon. This opens the
375 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> with the
376 to-do contents as the alarm text.
</para>
380 <para>Dragging any piece of text onto
&kalarm;'s main window or system
381 tray icon opens the
<link linkend=
"alarm-edit-dlg">Alarm Edit
382 dialog
</link> and sets the alarm text.
</para>
386 <para>To create a file display alarm, drag a text or image file
&URL;
387 onto
&kalarm;'s main window or system tray icon. This opens the
388 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> and sets the
393 <para>To create an audio alarm, drag an audio file
&URL; onto
394 &kalarm;'s main window or system tray icon. This opens the
395 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> and sets the
400 <para>You can automatically create birthday alarms for people in
401 &kaddressbook; as described in
<link linkend=
"birthdays">Importing
402 Birthdays from
&kaddressbook;</link>.
</para>
409 <sect2 id=
"edit-alarm">
410 <title>Modifying an Existing Alarm
</title>
412 <para>To modify an existing pending alarm (expired alarms cannot be
413 amended), do one of the following:
</para>
417 <para>Double click on its entry in the alarm list.
</para>
421 <para>Select it by clicking on its entry in the alarm list. Then
422 choose
<menuchoice><guimenu>Edit
</guimenu>
423 <guimenuitem>Edit
</guimenuitem></menuchoice>.
</para>
427 <para><mousebutton>Right
</mousebutton> click on its entry in the alarm
429 <menuchoice><guimenuitem>Edit
</guimenuitem></menuchoice> from the
434 <para>This displays the
<link linkend=
"alarm-edit-dlg">Alarm Edit
435 dialog
</link>.
</para>
440 <title>Deleting/Reactivating an Alarm
</title>
442 <para>To delete existing alarms, select one or more by clicking on
443 their entries in the alarm list. Then do one of the following:
</para>
447 <para>Choose
<menuchoice>
448 <guimenu>Edit
</guimenu><guimenuitem>Delete
</guimenuitem>
449 </menuchoice>.
</para>
452 <para><mousebutton>Right
</mousebutton> click on the selected entries
454 <menuchoice><guimenuitem>Delete
</guimenuitem></menuchoice>
455 from the context menu.
</para>
458 <para>To delete them without a confirmation prompt, type
459 &Shift;-
<keycap>Delete
</keycap>.
</para>
463 <para>When you delete an active alarm, it is archived, provided that
464 it has triggered at least once before being deleted, and provided that
465 expired alarms are archived at all. (Use the
466 <link linkend=
"preferences-storage">Configuration dialog
</link> to
467 control whether and for how long archived alarms are stored.) When you
468 delete an archived alarm, or an active alarm which has not yet
469 triggered, it is removed permanently.
</para>
471 <para>You can reactivate a deleted alarm from the archived alarms list,
472 provided that it has not yet expired. To do this, first display
473 archived alarms, as described in
474 <link linkend=
"expired">Archived Alarms
</link>. Then:
</para>
478 <para>Select one or more appropriate archived alarms by clicking on
479 their entries in the alarm list. Then choose
<menuchoice>
480 <guimenu>Actions
</guimenu><guimenuitem>Reactivate
</guimenuitem>
481 </menuchoice>.
</para>
484 <para><mousebutton>Right
</mousebutton> click on the desired entries in
485 the archived alarm list and choose
486 <menuchoice><guimenuitem>Reactivate
</guimenuitem></menuchoice>
487 from the context menu.
</para>
494 <title>Enabling/Disabling an Alarm
</title>
496 <para>See
<link linkend=
"enable-disable">Enabling and Disabling Alarms
</link>
497 for how to enable and disable alarms, either individually or as a whole.
</para>
502 <title>Setting an Alarm to Wake from Suspend
</title>
504 <para>See
<link linkend=
"wake-suspend">Wake From Suspend
</link> for
505 how to configure an alarm to wake up your system from suspension or
511 <title>Acknowledging an Alarm
</title>
513 <para>See
<link linkend=
"message-window">Alarm Message Window
</link>
514 for how to acknowledge alarms.
</para>
518 <sect2 id=
"templates">
519 <title>Alarm Templates
</title>
521 <para>If you frequently want to set up similar alarms, you can create
522 an alarm template to avoid having to enter all the details from
523 scratch each time. A template can contain all the details which an
524 alarm can contain, apart from the start date.
</para>
526 <para>As an example, you may regularly want to set an
527 alarm to remind you about a television program whose time varies
528 from week to week. The template would contain all the alarm details
529 (message text, whether to play a sound,
&etc;) except for the time and
530 date. Now, to create the alarm, all you need to do is open the
531 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> with that
532 template and then enter the time and date.
</para>
534 <para>To create an alarm based on a template, open the
535 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> preset with
536 the template details:
</para>
540 <para>Select the
<menuchoice>
541 <guimenu>File
</guimenu><guimenuitem>New From Template
</guimenuitem>
542 </menuchoice> menu item, and then select the desired template.
</para>
546 <para><mousebutton>Right
</mousebutton> click on the system tray icon
548 <menuchoice><guimenuitem>New Alarm From Template
</guimenuitem></menuchoice>
549 from the context menu. Then select the desired template.
</para>
553 <para>Open the
<link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>
554 in the usual way, and click the
555 <guibutton>Load Template...
</guibutton> button to select a template to
556 preset the dialog with.
</para>
561 <title>Configuring Templates
</title>
563 <para>You can create, modify or delete templates using the Alarm
564 Templates dialog, or you can create a new alarm template based on an
565 existing alarm.
</para>
567 <para>To create a new alarm template, do one of the following:
</para>
571 <para>Display the Alarm Templates dialog by selecting the
<menuchoice>
572 <guimenu>File
</guimenu><guimenuitem>Templates...
</guimenuitem>
573 </menuchoice> menu item, clicking
<guibutton>New
</guibutton>, and
574 choosing the alarm type from the list which appears. This displays a
575 blank Template Edit dialog.
</para>
579 <para>Display the Alarm Templates dialog by selecting the
<menuchoice>
580 <guimenu>File
</guimenu><guimenuitem>Templates...
</guimenuitem>
581 </menuchoice> menu item, select an existing template from the list and
582 click
<guibutton>Copy
</guibutton>. This opens the Template Edit dialog
583 already filled in with a copy of the existing template's
588 <para>Highlight an alarm in the alarm list and select
<menuchoice>
589 <guimenu>File
</guimenu><guimenuitem>Create Template...
</guimenuitem>
590 </menuchoice>. This opens the Template Edit dialog already filled in
591 with a copy of the selected alarm's details.
</para>
595 <para>To modify an existing template, display the Alarm Templates
596 dialog by selecting the
<menuchoice>
597 <guimenu>File
</guimenu><guimenuitem>Templates...
</guimenuitem>
598 </menuchoice> menu item and click
<guibutton>Edit
</guibutton>. This
599 displays the Template Edit dialog which is described below.
</para>
601 <para>To delete existing templates, display the Alarm Templates
602 dialog by selecting the
<menuchoice>
603 <guimenu>File
</guimenu><guimenuitem>Templates...
</guimenuitem>
604 </menuchoice> menu item, select one or more templates and click
605 <guibutton>Delete
</guibutton>. A confirmation prompt is issued to
606 prevent accidental deletions.
</para>
611 <title>Template Edit Dialog
</title>
613 <para>The Template Edit dialog is similar to the
614 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>. The
615 following controls are different:
</para>
619 <para>Enter the template's name in
<guilabel>Template name
</guilabel>.
620 It is the template's name which is displayed in template selection
621 lists, so it is best to choose a name which will remind you of its
622 function. Each template's name must be unique.
</para>
626 <para>In the
<guilabel>Time
</guilabel> group box, select one of:
</para>
630 <para><guilabel>Default time
</guilabel> if you do not wish to specify
631 any trigger time. Alarms based on this template will initially
632 use the normal default trigger time for new alarms.
</para>
636 <para>Check
<guilabel>Time
</guilabel> to enter a time when the alarm
637 is to be triggered.
</para>
641 <para>Check
<guilabel>Date only
</guilabel> to specify that the alarm
642 should only have a date, not a time.
</para>
646 <para>Check
<guilabel>Time from now
</guilabel> to enter how long (in
647 hours and minutes) after the alarm is created, that it should be
654 <para>In the
<guilabel>Recurrence Rule
</guilabel> group box in the
655 <guilabel>Recurrence
</guilabel> tab, no day or month need be selected
656 for weekly or yearly recurrences, respectively.
</para>
664 <sect2 id=
"calendars">
665 <title>Alarm Calendars
</title>
667 <para>If you only use one computer and work independently, it may not
668 matter to you where
&kalarm; stores its alarms. But if you need to
669 access alarms on more than one computer, or in more than one location
670 on your local computer, you can define
<quote>alarm calendars
</quote>
671 to tell
&kalarm; to use other alarm calendars additional to, or in
672 place of, its default ones.
</para>
674 <para>You can view and manipulate calendars via the calendar list,
675 which can be displayed alongside the alarm list in
&kalarm;'s main
676 window. Alarms from all alarm calendars are shown merged together in
677 the alarm list. When you save a new alarm, you can set a configuration
678 option to determine whether it is automatically saved into the default
679 calendar, or whether you will be prompted to choose a calendar. When
680 you edit an existing alarm, it is automatically saved back into its
681 original alarm calendar.
</para>
684 <screeninfo>Screenshot of the
&kalarm; main window, showing the
685 calendar list
</screeninfo>
688 <imagedata fileref=
"mainwindow-calendars.png" format=
"PNG"/>
691 <phrase>Main window showing the calendar list
</phrase>
697 <title>Calendar Types and Options
</title>
699 <para>Alarm calendars are categorized by alarm type and storage type.
700 They can be disabled, set read-only, or made the default calendar for
701 their alarm type.
</para>
705 <term>Alarm type
</term>
707 <para>The three alarm entity types
– active alarms, archived
708 alarms and alarm templates
–
709 are stored in separate alarm calendars.
&kalarm; therefore has three
710 standard default calendars, one for each type (see
711 <link linkend=
"faq">Questions and Answers
</link> for details), which
712 you can change if you wish.
</para>
717 <term>Storage type
</term>
719 <para>&kalarm; handles three alarm calendar storage
723 <listitem><para>Local file: Alarms are stored in a single local file
724 in iCalendar format.
&kalarm; uses local file calendars by default
725 (see
<link linkend=
"faq">Questions and Answers
</link> for details).
726 <quote>Local files
</quote>, in addition to files on the local
727 computer, can include alarm calendars on the local network as long as
728 their location can be represented by a path name starting with
729 <literal>/
</literal>.
</para>
732 <listitem><para>Local directory: Alarms are stored in a local folder,
733 each alarm being stored in a separate iCalendar file within the
734 folder. This storage method has the advantage that in the event of
735 file corruption, you should lose only one alarm, not the entire
739 <listitem><para>Remote file: Alarms are stored in a single remote
740 file in iCalendar format. This storage method allows you to access
741 your alarm data remotely no matter where you are, or enables alarm
742 calendars to be viewed by other people. When using remote files,
743 &kalarm; works with a local cache of the data.
</para>
745 <warning><para>If a remote alarm calendar is shared between users,
746 changes made by one person may not be automatically made available to
747 another user, or there could be a time delay before the other user
748 sees it. So one user could make a change which is then overwritten by
749 another user without either person noticing what has happened. The
750 technical reason for this is that a change made by person A will only
751 be available to person B after person A's cached copy has first been
752 saved to the remote file, and then person B's cached copy
753 of the remote file has been reloaded. When and if the calendar is
754 saved and reloaded depends on the calendar configuration parameters
755 which each user has set for that alarm calendar.
</para>
757 <para>Ways to avoid this problem include adjusting the calendar save
758 and reload configuration parameters, or adopting a policy that users
759 other than the alarm calendar's owner should open it in read-only
760 mode.
</para></warning>
767 <term>Enabled/disabled status
</term>
769 <para>Disabling a calendar has the same
770 effect as removing it, except that it still appears in the calendar
771 list for easy re-enabling. When disabled, its alarms are ignored and
772 do not appear in the alarm list or list of templates. When it is
773 re-enabled, its alarms are once again shown and, if it is an active
774 alarm calendar, made active.
</para>
779 <term>Read-only status
</term>
781 <para>A read-only calendar's alarms cannot be
782 changed or added to. So you cannot edit its alarms, or save new alarms
783 to it. Also, it is not possible to defer its alarms, since to do so
784 would need the deferral time to be saved into the alarm. After its
785 alarms trigger, they are not removed from the calendar and archived
786 until you or another user accesses the calendar in read-write
789 <para>You can set the read-only status of a calendar in the calendar
790 configuration dialog. However, some calendars cannot be made
791 writeable, for various reasons:
</para>
794 <listitem><para>If a calendar was created by another application, it
795 would be unsafe to allow
&kalarm; to update it, since differences in
796 data format might make it unusable by the creating application.
</para>
799 <listitem><para>If the calendar was created by a later version of
800 &kalarm;, data might be lost if your version of
&kalarm; updated
804 <listitem><para>If the calendar was created by a previous version of
805 &kalarm;, data could be lost or it could be made unusable for the
806 previous
&kalarm; version if your version of
&kalarm; updated it. You
807 will be prompted whether to convert its format so as to make it
808 writeable, bearing in mind the potential compatibility problems if the
809 previous
&kalarm; version needs to access it again.
</para>
812 <listitem><para>If you do not have permission to write to the
813 calendar file or folder.
</para>
817 <para>If you need write access to alarms in a calendar which cannot be
818 made writeable, you can copy its alarms by importing them into a
819 writeable calendar using the latter calendar's
820 <menuchoice><guimenuitem>Import...
</guimenuitem></menuchoice> context
821 menu option (see
<link linkend=
"import">Importing Alarms from External
822 Calendars
</link>).
</para>
827 <term>Default calendar status
</term>
829 <para>One calendar of each alarm type can optionally be made the
830 default calendar for that alarm type. New alarms are automatically
831 saved to the default calendar for the appropriate alarm type, unless
832 you have selected the prompt option for new alarms and templates in the
833 <link linkend=
"preferences-storage">Configuration dialog
</link>.
</para>
841 <title>Using Calendars
</title>
843 <para>You can view and manipulate calendars via the calendar list,
844 which can be displayed or hidden by
<menuchoice>
845 <guimenu>View
</guimenu><guimenuitem>Show Calendars
</guimenuitem>
846 </menuchoice>. When using the calendar list, first select the alarm
847 type using the combo box above the list. Then either click on one of
848 the buttons below the list, or
<mousebutton>Right
</mousebutton> click
849 on the appropriate calendar in the list and choose an item from the
850 context menu. The actions available are:
</para>
854 <term><menuchoice><guimenuitem>Add...
</guimenuitem></menuchoice></term>
856 <para>Add a calendar of the selected type to the list. You are asked
857 to choose a storage type, following which the calendar configuration
858 dialog is displayed, where you can enter the location of the calendar
859 and its characteristics. If there is no existing alarm calendar in
860 the specified location, a new one will be created.
</para>
865 <term><menuchoice><guimenuitem>Remove
</guimenuitem></menuchoice></term>
867 <para>Remove the selected calendar from the list. The calendar itself
868 is left intact; it is simply removed from the list, and may
869 subsequently be reinstated in the list if desired.
</para>
874 <term><menuchoice><guimenuitem>Edit...
</guimenuitem></menuchoice></term>
876 <para>Edit the selected calendar. This displays the configuration
877 dialog for the selected calendar.
</para>
882 <term><menuchoice><guimenuitem>Reload
</guimenuitem></menuchoice></term>
884 <para>Reload the selected calendar. The calendar is re-read from its
885 storage location, ensuring that there is no discrepancy between what
886 &kalarm; displays and the current state of the calendar. If the
887 calendar is shared with other users, any changes which they have made
888 will now be seen by
&kalarm;.
</para>
890 <warning><para>If you reload a remote calendar, any changes to alarms
891 which you have made since the calendar was last saved will be lost.
892 Also, any alarms which have expired since the last save may be
893 retriggered.
</para></warning>
898 <term><menuchoice><guimenuitem>Save
</guimenuitem></menuchoice></term>
900 <para>Save any changes to the selected calendar. The calendar is
901 updated with any alarm changes which have occurred since the last time
902 the calendar was saved or reloaded. This is only useful for remote
903 calendars, since local calendars are automatically saved after every
904 change. You can configure when and how frequently a remote calendar
905 should be automatically saved, using its configuration dialog (via
906 the
<menuchoice><guimenuitem>Edit...
</guimenuitem></menuchoice>
907 context menu option).
</para>
909 <warning><para>If you save a remote calendar which is shared with other
910 users, any changes which they have made since you last reloaded the
911 calendar (automatically or manually) will be lost.
</para></warning>
916 <term><menuchoice><guimenuitem>Import...
</guimenuitem></menuchoice></term>
918 <para>Import alarms from an external calendar file into the selected
919 calendar. This is described in
920 <link linkend=
"import">Importing Alarms from External Calendars
</link>.
921 This option is not available for disabled or read-only
927 <term><menuchoice><guimenuitem>Export...
</guimenuitem></menuchoice></term>
929 <para>Export all the alarms in the selected calendar to an external calendar
930 file. This is described in
931 <link linkend=
"export">Exporting Alarms to External Calendars
</link>.
932 This option is not available for disabled calendars.
</para>
937 <term><menuchoice><guimenuitem>Show Details
</guimenuitem></menuchoice></term>
939 <para>Display details about the selected calendar. This shows the
940 calendar's location, storage type and status information.
946 <term><menuchoice><guimenuitem>Use as Default
</guimenuitem></menuchoice></term>
948 <para>Make the selected calendar the default calendar for the selected
949 calendar type. This option is not available for disabled or read-only
955 <term><menuchoice><guimenuitem>Set Color...
</guimenuitem></menuchoice></term>
957 <para>Select a background color for highlighting this calendar's alarms
958 in the alarm list. This enables you to see at a glance which alarms
959 belong to a particular calendar.
</para>
964 <term><menuchoice><guimenuitem>Clear Color
</guimenuitem></menuchoice></term>
966 <para>Clear color highlighting for this calendar's alarms in the alarm
977 <title>Importing Alarms from External Calendars
</title>
979 <para>You can import alarms from other calendar files into
&kalarm;.
980 The import function scans the selected calendar
981 file for events containing alarms, and copies them (with new unique
982 IDs) into
&kalarm;'s calendar. Events without alarms, and calendar
983 entries other than events, are ignored. There are two ways to import
988 <para>Use
<menuchoice><guimenu>File
</guimenu>
989 <guimenuitem>Import Alarms...
</guimenuitem></menuchoice> to import
990 alarms of all types (active alarms, archived alarms and alarm
991 templates) from the calendar.
</para>
993 <para>If you have configured
994 <link linkend=
"calendars">alarm calendars
</link>, alarms of each type
995 will be added to the appropriate default calendar, or if you have
996 selected the prompt option for new alarms and templates in the
997 <link linkend=
"preferences-storage">Configuration dialog
</link>, you will
998 be prompted for the calendar to use.
</para>
1002 <para><mousebutton>Right
</mousebutton> click on a calendar in the
1003 calendar list, and choose
1004 <menuchoice><guimenuitem>Import...
</guimenuitem></menuchoice> from the
1005 context menu. This imports alarms of the currently selected type into
1006 that calendar. For example, if the selected calendar type is alarm
1007 templates, alarm templates (and not active alarms or archived alarms)
1008 will be imported.
</para>
1012 <warning><para>If you import alarms from calendar files which were
1013 created by applications other than
&kalarm;, the alarms may be changed
1014 by the import process
– even alarm times may change. This depends
1015 on the data storage conventions used by the other application, and is
1016 unavoidable if those conventions differ from what
&kalarm; expects.
1017 Always check imported alarms for unexpected changes, and adjust them
1018 as necessary.
</para></warning>
1023 <title>Exporting Alarms to External Calendars
</title>
1025 <para>You can export alarms from
&kalarm; to other calendar files,
1026 either the alarms currently selected in the alarm list, or all the
1027 alarms from an alarm calendar. The methods to do this are given below.
1028 Whichever method is used, you can either create a new calendar file
1029 or append the exported alarms to an existing calendar file. To append
1030 the alarms, check
<guilabel>Append to existing file
</guilabel> in the
1031 file selection dialog; otherwise, any existing file is
1036 <para>To export the alarms currently selected in the alarm list,
1037 <mousebutton>Right
</mousebutton> click on the selection and choose
1038 <menuchoice><guimenuitem>Export...
</guimenuitem></menuchoice> from the
1039 context menu, or use
<menuchoice><guimenu>File
</guimenu>
1040 <guimenuitem>Export Selected Alarms...
</guimenuitem></menuchoice> in
1041 the main menu.
</para>
1045 <para>To export all the alarms from a calendar,
1046 <mousebutton>Right
</mousebutton> click on a calendar in the calendar
1048 <menuchoice><guimenuitem>Export...
</guimenuitem></menuchoice> from the
1049 context menu.
</para>
1055 <sect2 id=
"birthdays">
1056 <title>Importing Birthdays from
&kaddressbook;</title>
1058 <para>You can set up display alarms for birthdays stored in
1059 &kaddressbook;, by
<menuchoice><guimenu>File
</guimenu>
1060 <guimenuitem>Import Birthdays...
</guimenuitem></menuchoice>. This
1061 displays a dialog which allows you to select which birthdays to create
1066 <para>In the
<guilabel>Alarm Text
</guilabel> group box, you can set up
1067 the text to be displayed in the birthday alarm messages. The message
1068 text is created by combining the
<guilabel>Prefix
</guilabel> text
1069 followed by the person's name followed by the
1070 <guilabel>Suffix
</guilabel> text. No spaces are added, so remember to
1071 include any necessary trailing space in
<guilabel>Prefix
</guilabel>
1072 and leading space in
<guilabel>Suffix
</guilabel>.
</para>
1074 <note><para>If you change the alarm text, the birthday selection list
1075 will be re-evaluated.
</para></note>
1079 <para>In the
<guilabel>Select Birthdays
</guilabel> list, select the
1080 birthdays which you want to create alarms for. Note that the list
1081 shows only those entries in
&kaddressbook; which contain a birthday
1082 and which do not already have a birthday alarm in the format currently
1083 defined in the
<guilabel>Alarm Text
</guilabel> group box.
</para>
1087 <para>The remaining controls are the same as for
1088 <guilabel>Text
</guilabel> alarms in the
1089 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>.
</para>
1093 <para>If you have configured
1094 <link linkend=
"calendars">alarm calendars
</link>, the alarms will be
1095 added to the default active alarm calendar, or if you have selected the
1096 prompt option for new alarms and templates in the
1097 <link linkend=
"preferences-storage">Configuration dialog
</link>, you will
1098 be prompted for the calendar to use.
</para>
1103 <title>Undo / Redo
</title>
1105 <para>You can undo and redo the most recent changes which you have
1106 made during the current session of
&kalarm;. Most actions can be
1107 undone, including creation, edit and deletion of alarms and alarm
1108 templates, and reactivation of alarms. To prevent excessive resources
1109 being used by the undo history, the number of changes stored is
1110 limited to the last
12.
</para>
1112 <para>To undo the last change, select
<menuchoice>
1113 <guimenu>Edit
</guimenu><guimenuitem>Undo
</guimenuitem></menuchoice>.
1114 To redo the last change which was undone, select
<menuchoice>
1115 <guimenu>Edit
</guimenu><guimenuitem>Redo
</guimenuitem>
1116 </menuchoice>.
</para>
1118 <para>To undo a change other than the last one, click on the
1119 <guibutton>Undo
</guibutton> button in the toolbar and hold the mouse
1120 button down. A list of actions will be displayed from which you can
1121 choose the one to undo. If you don't see the action which you are
1122 looking for, remember that you may need to undo more recent changes
1123 first, which the desired change depends on. For example, if you edited
1124 an alarm and then deleted it, you cannot undo the edit until you have
1125 first undone the deletion.
</para>
1127 <para>Redoing a change other than the last one can be done in a
1128 similar manner, using the
<guibutton>Redo
</guibutton> toolbar
1134 <sect1 id=
"alarm-edit-dlg">
1135 <title>The Alarm Edit Dialog
</title>
1137 <para>The Alarm Edit dialog enables you to view and edit an alarm.
1138 When you first use
&kalarm;, a simplified form of the dialog is
1139 displayed, with only a small number of options visible. To see all
1140 options, click the
<guibutton>More Options
</guibutton> button; to
1141 revert to the simplified dialog, click the
1142 <guibutton>Less Options
</guibutton> button.
&kalarm; always remembers
1143 your last display choice whenever the Alarm Edit dialog is
1146 <para>You can configure the default values of many of the settings in
1147 the Alarm Edit dialog using the
1148 <link linkend=
"preferences-edit">Configuration dialog's Edit tab
</link>.
</para>
1151 <screeninfo>Screenshot of the simplified Alarm Edit dialog
</screeninfo>
1154 <imagedata fileref=
"editwindow-simple.png" format=
"PNG"/>
1157 <phrase>Simplified Alarm Edit dialog for a display alarm
</phrase>
1159 <caption><para>Simplified Alarm Edit dialog for a display alarm
</para></caption>
1164 <screeninfo>Screenshot of the Alarm Edit dialog showing all options
</screeninfo>
1167 <imagedata fileref=
"editwindow.png" format=
"PNG"/>
1170 <phrase>Alarm Edit dialog for a display alarm, showing all options
</phrase>
1172 <caption><para>Alarm Edit dialog for a display alarm, showing all options
</para></caption>
1177 <title>Alarm Action
</title>
1179 <para>The controls in the
<guilabel>Action
</guilabel> group box vary
1180 depending on the type of alarm being edited.
</para>
1183 <title>Display Alarms
</title>
1185 <para>Display alarms display a window when the alarm triggers. Select
1186 the method used to generate the alarm window contents, using the combo
1187 box at the top:
</para>
1191 <para><guilabel>Text message
</guilabel> in order to enter an alarm
1192 message text (which may include newlines) in the edit box.
</para>
1196 <para><guilabel>File contents
</guilabel> to enter the path or
&URL; of
1197 a text or image file whose contents are to be displayed in the alarm
1198 message. Use the button beside the edit box to display a file selection
1199 dialog. The
<guilabel>Speak
</guilabel> option is not available for this
1200 type of alarm.
</para>
1204 <para><guilabel>Command output
</guilabel> to specify that the alarm
1205 message text will be generated by a command which is executed when the
1207 <link linkend=
"command-alarm">Command Alarms
</link> below for details
1208 of how to enter the command or command script to execute.
</para>
1212 <para>The controls available for display alarms are:
</para>
1216 <para>The
<guilabel>Sound
</guilabel> option allows you to select
1217 whether an audible alarm should sound when the alarm message is
1218 displayed. Choose:
</para>
1222 <para><guilabel>None
</guilabel> to display the alarm silently.
</para>
1226 <para><guilabel>Beep
</guilabel> to sound a beep.
</para>
1230 <para><guilabel>Speak
</guilabel> to have the alarm message spoken as
1231 well as being displayed. This option is only available if you have
1232 &jovie; (from the kdeaccessibility package) installed and configured,
1233 together with a compatible speech synthesizer,
⪚
1234 <application>Festival
</application>.
</para>
1238 <para><guilabel>Sound file
</guilabel> to play an audio file. Use the
1239 button on the right to display the Sound File dialog which lets you
1240 select a file to play and set volume and repetition options. If you
1241 hover the mouse over the selector, a tooltip will display the audio file
1242 currently selected.
</para>
1244 <para>In the Sound File dialog:
</para>
1248 <para>Enter the sound file path, or use the button beside the
1249 edit box to display a file selection dialog. You can listen to the
1250 selected file by clicking the play button to the left of the edit
1251 field. That button then changes function to allow you to stop playing
1252 when you have heard enough.
</para>
1256 <para>Check
<guilabel>Repeat
</guilabel> to continually repeat the
1257 audio file for as long as the alarm is displayed. (The alarm message
1258 window contains a button to stop playing the sound should you need
1259 silence but still want to display the alarm.)
</para>
1263 <para>Check
<guilabel>Volume
</guilabel> and adjust the slider
1264 control if you want to adjust the volume at which the audio file is
1269 <para>If you wish, you can fade the volume. Fading means to start
1270 playing the audio file at one volume and gradually change to the final
1271 volume, over a specified time interval. The final volume is that
1272 entered in
<guilabel>Volume
</guilabel> above. To enable fade, check
1273 <guilabel>Fade
</guilabel>, and then enter the fade period in seconds
1274 in the
<guilabel>Fade time
</guilabel> field, and adjust the
1275 <guilabel>Initial volume
</guilabel> slider.
</para>
1279 <tip><para>You can use the
<guibutton>Try
</guibutton> button to test out
1280 the selected sound levels.
</para></tip>
1286 <para>Use the
<guibutton>Font
& Color...
</guibutton> button to
1287 select a font, and foreground and background colors, for the alarm
1288 message. In the
<guilabel>Choose Alarm Font
& Color
</guilabel>
1289 dialog, check
<guilabel>Use default font
</guilabel> to display the
1290 message in whatever font is configured as the default at the time
1291 the message is displayed. To choose a specific font for the message,
1292 uncheck
<guilabel>Use default font
</guilabel>. (The default font and
1293 colors can be set in the
1294 <link linkend=
"preferences-edit">Configuration dialog
</link>.)
</para>
1296 <para>The selected colors are shown in the alarm message text entry
1301 <para>Use the
<guibutton>Special Actions...
</guibutton> button to
1302 specify shell commands to execute before or after displaying the
1303 alarm. In the
<guilabel>Special Alarm Actions
</guilabel>
1308 <para>In the
<guilabel>Pre-alarm action
</guilabel> field, enter a
1309 shell command to execute before the alarm is displayed. Note that
1310 &kalarm; will wait for the command to complete before displaying the
1313 <para>A pre-alarm action is only executed once when the alarm message
1314 is initially displayed, including when a reminder message is replaced
1315 by the actual alarm message. It is
<emphasis>not
</emphasis> executed
1316 in any of the following circumstances:
</para>
1319 <listitem><para>When a reminder message is displayed.
</para></listitem>
1320 <listitem><para>When the message is redisplayed after deferring the
1321 alarm.
</para></listitem>
1322 <listitem><para>When the message was displaying at the time you logged
1323 off and is then restored when you log back in.
</para></listitem>
1324 <listitem><para>When a recurring alarm triggers but the alarm message
1325 (or a deferred alarm message) from a previous occurrence of the alarm
1326 is still visible; in other words, when the previous occurrence of the
1327 alarm has not yet been acknowledged.
</para></listitem>
1330 <para>The pre-alarm action can be used to control whether to display
1331 the alarm message:
</para>
1334 <listitem><para>Check
<guilabel>Cancel alarm on error
</guilabel> to
1335 cancel the alarm if the pre-alarm command returns an error status.
1336 This will prevent the alarm message from being displayed, and any
1337 post-alarm action from being executed.
</para></listitem>
1339 <listitem><para>Normally, if the pre-alarm command returns an error,
1340 an error message is displayed and an error indication is shown in the
1341 alarm list. These error notifications can be prevented by checking
1342 <guilabel>Do not notify errors
</guilabel>.
</para></listitem>
1347 <para>In the
<guilabel>Post-alarm action
</guilabel> field, enter a
1348 shell command to execute when the alarm is acknowledged (whether by
1349 clicking
<guibutton>Close
</guibutton> or by using the close button
1350 in the window's titlebar). It is
<emphasis>not
</emphasis>
1351 executed in any of the following circumstances:
</para>
1354 <listitem><para>When a reminder message is closed.
</para></listitem>
1355 <listitem><para>When you defer the alarm, except when the deferred
1356 alarm is finally acknowledged.
</para></listitem>
1357 <listitem><para>When the alarm message is closed due to logging
1358 out.
</para></listitem>
1363 <para>See
<link linkend=
"command-alarm">Command Alarms
</link> below
1364 for details of how shell commands are executed.
</para>
1370 <sect3 id=
"command-alarm">
1371 <title>Command Alarms
</title>
1373 <para>Command alarms execute a command without displaying any alarm
1376 <note><para>This alarm type is not available if
&kde; is running in
1377 kiosk mode.
</para></note>
1379 <para>When the command is executed, the environment variable
1380 <envar>KALARM_UID
</envar> contains the event UID for the alarm. Note
1381 that when the command is executed from the Alarm Edit dialog's
1382 <guibutton>Try
</guibutton> button,
<envar>KALARM_UID
</envar> will be
1383 blank if it is a new alarm, or if the alarm has been modified in the
1384 dialog, because the alarm only acquires a UID when it is saved in the
1385 alarm calendar.
</para>
1387 <para>The controls available for command alarms are:
</para>
1391 <para>The
<guilabel>Enter a script
</guilabel> check box lets you choose
1392 whether to enter a shell command line or a script.
</para>
1394 <para>If this option is unchecked, you can enter a shell command line
1395 to execute. The command is passed straight to the default shell (defined
1396 by the
<envar>SHELL
</envar> environment variable), and may include
1397 whatever options, parameters, piped commands,
&etc; are permitted by
1398 the shell in a single line command.
</para>
1400 <para>If this option is checked, you can enter the text of a script to
1401 execute. Remember to include a first line such as
1402 <literal>#!/bin/bash
</literal> to ensure that the correct command
1403 interpreter is invoked.
</para>
1407 <para>Use the
<guilabel>Command Output
</guilabel> group box to specify
1408 what you want to be done with any terminal output which the command
1409 produces when it executes.
</para>
1413 <para>Check
<guilabel>Execute in terminal window
</guilabel> to cause
1414 the command to be executed in a terminal window. You can choose
1415 which type of terminal window should be used in the
1416 <link linkend=
"preferences-general">Configuration dialog
</link>.
</para>
1420 <para>Check
<guilabel>Log to file
</guilabel> to save the command's
1421 output in a file. The output, prefixed by a heading showing the time
1422 at which the command was scheduled to run, will be appended to any
1423 existing contents of the file. Enter the file name in the edit box, or
1424 use the button beside the edit box to display a file selection
1429 <para>Check
<guilabel>Discard
</guilabel> to throw away the command's
1438 <title>Email Alarms
</title>
1440 <para>Email alarms send an email without displaying any alarm
1443 <para>Fill in the recipients' addresses, the email subject line and the
1444 message body in the three edit fields. Use the button beside the
1445 addressee edit box to display your
&kde; address book from which you
1446 can select email recipients. Attachments may be added using the
1447 <guibutton>Add...
</guibutton> button. Note that attached files must
1448 still exist when the alarm is triggered; no copy is stored at the time
1449 the alarm is configured. To remove an attachment, highlight it in the
1450 drop-down list and click the
<guibutton>Remove
</guibutton>
1453 <para>Set the following options:
</para>
1457 <para>The
<guilabel>From
</guilabel> combo box allows you to select
1458 which
&kmail; identity to use as your email address for sending the
1459 email. This option only appears if your
<guilabel>From
</guilabel>
1460 email address in the
1461 <link linkend=
"preferences-email">Configuration dialog
</link> is set to
1462 <guilabel>Use
&kmail; identities
</guilabel>. Otherwise your email
1463 address is preset in the
1464 <link linkend=
"preferences-email">Configuration dialog
</link>, rendering
1465 this option inapplicable.
</para>
1469 <para>Check
<guilabel>Copy email to self
</guilabel> to send a blind
1470 copy of the email to yourself when the alarm is triggered. The email
1471 address to which the copy will be sent may be set in the
1472 <link linkend=
"preferences-email">Configuration dialog
</link>, the
1473 default being your email address set in the
&kde; System
1481 <title>Audio Alarms
</title>
1483 <para>Audio alarms play an audio file without displaying any alarm
1486 <para>Set the following options:
</para>
1490 <para>Enter the sound file path, or use the button beside the
1491 edit box to display a file selection dialog.
</para>
1495 <para>Check
<guilabel>Repeat
</guilabel> to continually repeat the
1496 audio file until the
<guilabel>Stop Play
</guilabel> option is
1497 selected. To stop playing the file, select the
1498 <menuchoice><guimenu>Actions
</guimenu>
1499 <guimenuitem>Stop Play
</guimenuitem></menuchoice> menu option, or
1500 <mousebutton>Right
</mousebutton> click on the system tray icon
1502 <menuchoice><guimenuitem>Stop Play
</guimenuitem></menuchoice>
1503 from the context menu. If you wish, you can set up a global
1504 shortcut key for this action.
</para>
1508 <para>Check
<guilabel>Volume
</guilabel> and adjust the slider
1509 control if you want to adjust the volume at which the audio file is
1514 <para>If you wish, you can fade the volume. Fading means to start
1515 playing the audio file at one volume and gradually change to the final
1516 volume, over a specified time interval. The final volume is that
1517 entered in
<guilabel>Volume
</guilabel> above. To enable fade, check
1518 <guilabel>Fade
</guilabel>, and then enter the fade period in seconds
1519 in the
<guilabel>Fade time
</guilabel> field, and adjust the
1520 <guilabel>Initial volume
</guilabel> slider.
</para>
1527 <title>Deferral
</title>
1529 <para>If the alarm is a recurring alarm and it was deferred after it
1530 was last displayed, the
<guilabel>Deferred Alarm
</guilabel> group box
1531 shows the time the alarm was deferred to.
1532 <guibutton>Change...
</guibutton> displays a dialog which allows you to
1533 change the deferred time or to cancel the deferral.
</para>
1540 <para>In the
<guilabel>Time
</guilabel> group box, select either
</para>
1544 <para><guilabel>At date/time
</guilabel> to enter the date and time
1545 when the alarm is to be triggered. Check
<guilabel>Any time
</guilabel>
1546 if you want to specify only a date for the alarm: in this case the
1547 alarm will be displayed at the first opportunity on or after the
1548 configured start-of-day time, on the specified date.
1549 (
<link linkend=
"preferences-time">Configuring
&kalarm;</link>
1550 describes how to set the start-of-day time.)
</para>
1552 <para>For a non-recurring alarm, the date/time which you enter must be
1553 in the future, or if you enter only a date it must be today or later.
1554 For a recurring alarm, there are no such restrictions since the start
1555 date/time will be automatically adjusted to the first recurrence due
1556 after the current time.
</para>
1560 <para><guilabel>Time from now
</guilabel> to enter how long after now
1561 (in hours and minutes) the alarm should be triggered.
</para>
1565 <para>If desired, choose a time zone to apply to the alarm. This time
1566 zone is used for all dates and times relating to this alarm, including
1567 recurrence and exception dates and times. Normally, you should leave
1568 the time zone controls unchanged unless you have a good reason to
1571 <para>The time zone controls are displayed only when the selected time
1572 zone is different from the default time zone set in the
1573 <link linkend=
"preferences-time">Configuration dialog
</link>, or if
1574 you click the
<guibutton>Time Zone...
</guibutton> button.
</para>
1578 <para>In the combo box, choose the time zone which this alarm is to
1579 use. When creating a new alarm, this is initially set to the time zone
1581 <link linkend=
"preferences-time">Configuration dialog
</link>, which
1582 will be your computer's time zone unless you have changed it.
</para>
1586 <para>Check
<guilabel>Ignore time zone
</guilabel> if you want to use
1587 the local computer time (on whichever computer
&kalarm; happens to be
1588 running on at the time), ignoring time zones.
</para>
1590 <warning><para>You are recommended not to select this option if the
1591 alarm has a recurrence specified in hours and minutes; if you do, the
1592 alarm may occur at unexpected times after daylight saving time
1593 shifts.
</para></warning>
1600 <title>Reminder
</title>
1602 <para>For a display alarm, check
<guilabel>Reminder
</guilabel> if you
1603 want to display a reminder either before or after the main alarm and
1604 each of its recurrences (if any). Enter how long in advance or
1605 afterwards, using the edit controls beside the check box. Note that
1606 if the alarm recurs, the reminder period is normally limited to
1607 being less than the recurrence or sub-repetition interval.
</para>
1609 <note><para>Reminders are not displayed for sub-repetitions within a
1610 recurrence. Reminders are only shown for each main recurrence of the
1611 alarm.
</para></note>
1613 <para>If the alarm recurs, check
<guilabel>Reminder for first
1614 recurrence only
</guilabel> if you only want a reminder for the alarm's
1615 first recurrence. If this is checked, and it is an advance reminder,
1616 the reminder period is not subject to the normal limit of being less
1617 than the recurrence or sub-repetition interval.
</para>
1623 <title>Cancelation
</title>
1625 <para>The late-cancelation options determine how an alarm is treated
1626 after its scheduled time:
</para>
1630 <para>The
<guilabel>Cancel if late
</guilabel> check box determines what
1631 happens if the alarm cannot be triggered at its scheduled time.
</para>
1633 <para>Check this box to cancel the alarm if it cannot be triggered
1634 within a specified time period after the right time. The time period
1635 is selected using controls which appear when you check the box. For
1636 example, if you enter a time period of
1 hour, the alarm will be
1637 triggered at the first opportunity up to an hour after it is due, but
1638 if it cannot be triggered within an hour its activation will be
1641 <note><para>The lateness of date-only alarms,
&ie; ones for which the
1642 <guilabel>Any time
</guilabel> option is selected, is calculated from
1643 the start-of-day time on the alarm's scheduled date.
</para></note>
1645 <para>Leave the box unchecked to trigger the alarm at the first
1646 opportunity starting at the scheduled time, regardless of how late it
1649 <note><para>An alarm can only be triggered while you are logged in,
1650 and while both X and
&kalarm; are running.
</para></note>
1654 <para>Check
<guilabel>Auto-close window after this time
</guilabel> if
1655 you want the alarm window to be automatically closed if it is still
1656 showing at the expiry of the late-cancelation time.
</para>
1663 <title>Recurrence
</title>
1665 <para>Specify whether or how the alarm should be repeated using the
1666 <guilabel>Recurrence
</guilabel> tab.
</para>
1668 <note><para>The alarm's basic repetition characteristics are displayed
1669 for convenience in the title of the
<guilabel>Recurrence
</guilabel>
1670 tab. The recurrence interval is shown first, followed by any
1671 sub-repetition interval set up using the
1672 <guibutton>Sub-Repetition
</guibutton> button.
</para></note>
1674 <para>In the
<guilabel>Recurrence Rule
</guilabel> group box, set the
1675 recurrence type or time period as follows:
</para>
1678 <listitem><para>To trigger the alarm once only, select
<guilabel>No
1679 recurrence
</guilabel>.
</para></listitem>
1681 <listitem><para>Select
<guilabel>At login
</guilabel> to trigger the
1682 alarm whenever you log in, until its scheduled end time. Then, at its
1683 scheduled end time it will finally be triggered one last time. (Note
1684 that an alarm repeated at login will also be triggered any time you
1685 restart
&kalarm;.)
</para></listitem>
1688 <para>To make the alarm recur at regular intervals, select one of the
1689 time period types and then enter in the
1690 <guilabel>Recur every
</guilabel> box how many time periods should
1691 elapse between recurrences. For example, to repeat
1692 every fortnight, you could select
<guilabel>Daily
</guilabel> and enter
1693 a value of
14, or select
<guilabel>Weekly
</guilabel> and enter a value
1694 of
2. Depending on the time period type selected, you may have further
1699 <para>For a weekly recurrence, check each day in the week on which you
1700 wish to trigger the alarm.
</para>
1704 <para>For a monthly recurrence, you may select either a fixed date, or
1705 a position (
⪚ the second Tuesday).
</para>
1709 <para>For a yearly recurrence, you may select either a fixed day in
1710 the month, or a position in a month (
⪚ the last Saturday in
1711 May). Check each month of the year in which you wish to trigger the
1714 <para>If you set up a yearly recurrence for February
29th, you can
1715 specify how it is to be handled in non-leap years by selecting the
1717 <guilabel>February
29th alarm in non-leap years
</guilabel>
1721 <listitem><para><guilabel>None
</guilabel>: the alarm will occur on
1722 February
29th in leap years, but will be suppressed in non-leap
1726 <listitem><para><guilabel>28 Feb
</guilabel>: the alarm will occur on
1727 February
29th in leap years, and on February
28th in non-leap
1731 <listitem><para><guilabel>1 Mar
</guilabel>: the alarm will occur on
1732 February
29th in leap years, and on March
1st in non-leap
1739 <tip><para>To set a daily alarm to occur only on weekdays, use a
1740 weekly recurrence and check each weekday.
</para></tip>
1745 <para>In the
<guilabel>Recurrence End
</guilabel> group box, set the
1746 overall recurrence time span as follows:
</para>
1749 <listitem><para>Select
<guilabel>No end
</guilabel> to continue the
1750 repetitions indefinitely.
</para></listitem>
1752 <listitem><para>Select
<guilabel>End after
</guilabel> to specify the
1753 total number of occurrences of the alarm.
</para></listitem>
1755 <listitem><para>Select
<guilabel>End by
</guilabel> to specify the
1756 date/time until which the alarm will be repeated. Note that this uses
1757 the same time zone as the alarm's start time.
</para>
1759 <note><para>The end date/time determines when the last main recurrence
1760 will be, but does not limit sub-repetitions. If sub-repetitions are
1761 configured, they will trigger as normal after the last main recurrence,
1762 regardless of the end date/time.
</para></note>
1766 <para>The
<guilabel>Exceptions
</guilabel> group box allows you to
1767 exclude certain date/times from the recurrence which you have set up.
1768 Note that these controls are not shown in the simplified form of the
1769 Alarm Edit dialog: to see them, click
1770 <guibutton>More Options
</guibutton>.
</para>
1774 <para>The list of exceptions (
&ie; excluded date/times) is shown on
1775 the left. To add a new exception, enter a date on the right and press
1776 <guibutton>Add
</guibutton>. To change an exception, highlight it in
1777 the list, enter the new date on the right and press
1778 <guibutton>Change
</guibutton>. To delete an exception, highlight it
1779 in the list and press
<guibutton>Delete
</guibutton>.
</para>
1783 <para>You can restrict an alarm not to occur on holidays by checking
1784 <guilabel>Exclude holidays
</guilabel>. This does not change the way
1785 the alarm is scheduled; it simply suppresses the alarm whenever it
1786 happens to trigger on a holiday. You can select your holiday country
1788 <link linkend=
"preferences-time">Configuration dialog
</link>.
</para>
1792 <para>You can restrict an alarm to occur only during working time by
1793 checking
<guilabel>Only during working hours
</guilabel>. This does not
1794 change the way the alarm is scheduled; it simply suppresses the alarm
1795 whenever it happens to trigger outside working hours. Work days and
1796 working hours are set in the
1797 <link linkend=
"preferences-time">Configuration dialog
</link>.
</para>
1802 <title>Sub-Repetition
</title>
1804 <para>You can use the
<guibutton>Sub-Repetition
</guibutton> button to
1805 set up a repetition within a repetition. In this case, each time the
1806 alarm is due as specified in the main recurrence, instead of being
1807 triggered just once it is triggered repeatedly in accordance with your
1808 sub-repetition specification. For example, to set up an alarm which
1809 repeats every hour from noon to
6 pm each Thursday, you would set up a
1810 weekly recurrence on Thursday at
12:
00, and use the Sub-Repetition
1811 dialog to specify an interval of
1 hour and either a count of
6 or a
1812 duration of
6 hours.
</para>
1814 <para>In the Sub-Repetition dialog which is displayed when you click
1815 the
<guibutton>Sub-Repetition
</guibutton> button, check
1816 <guilabel>Repeat every
</guilabel> to set up a repetition, or uncheck
1817 it to remove the repetition. If
<guilabel>Repeat every
</guilabel> is
1818 checked, set up the repetition as follows:
</para>
1821 <listitem><para>Enter the time interval between repetitions in the
1822 controls beside
<guilabel>Repeat every
</guilabel>. Select the desired
1823 time units (
⪚ <guilabel>days
</guilabel>) and then enter the number
1827 <listitem><para>Specify either the repetition count or its
1831 <listitem><para>Select
<guilabel>Number of times
</guilabel> to enter
1832 how many times the alarm should be triggered after the main
1833 recurrence. So, for example, to make the alarm occur
4 times at each
1834 main recurrence,
&ie; 3 additional times, you should enter
3
1838 <listitem><para>Select
<guilabel>Duration
</guilabel> to enter the
1839 total time period during which the alarm should be repeated. This need
1840 not be an exact multiple of the repetition interval; it will
1841 automatically be rounded down when you click
1842 <guibutton>OK
</guibutton>.
</para>
1848 <note><para>To prevent overlapping sub-repetitions for the same alarm,
1849 a sub-repetition's duration is restricted to be less than the longest
1850 interval between main recurrences. Each time the alarm recurs as
1851 specified in the main recurrence, any still active sub-repetition
1852 which started at the previous recurrence is automatically
1853 cancelled.
</para></note>
1859 <title>Other Controls
</title>
1861 <para>For display alarms, the
1862 <guilabel>Confirm acknowledgment
</guilabel> check box lets you specify
1863 whether you will be prompted for confirmation when you close the alarm
1864 message window. This may be used as a safeguard against accidental
1865 acknowledgment of alarms.
</para>
1867 <para>Select
<guilabel>Show in
&korganizer;</guilabel> to add the
1868 alarm to
&korganizer;'s active calendar, where it will appear as an
1869 event without an alarm. This option allows you to track alarms in
1870 &korganizer; while still making use of
&kalarm;'s functions.
</para>
1872 <note><para>If you later modify or delete the alarm in
&kalarm;, the
1873 &korganizer; event will be modified or deleted correspondingly. But
1874 if you change the event in
&korganizer;, the alarm in
&kalarm; will
1875 not be affected.
</para></note>
1877 <para>Press the
<guibutton>Load Template
</guibutton> button to select
1878 a template to preset the dialog with, as described in
<link
1879 linkend=
"create-edit">Creating and Manipulating Alarms
</link>.
</para>
1881 <para>Press the
<guibutton>Try
</guibutton> button to test the alarm
1882 and check whether it works correctly. The alarm is executed just as
1883 if it had been scheduled in the normal way.
</para>
1885 <para>Press the
<guibutton>OK
</guibutton> button
1886 when all details are correct, to add the alarm to the scheduled
1887 list. Note that when editing an existing alarm, the
1888 <guibutton>OK
</guibutton> button is disabled while no changes have
1894 <sect1 id=
"message-window">
1895 <title>Alarm Message Window
</title>
1897 <para>When an alarm message is due, it is displayed on each
&kde;
1898 desktop and cannot be covered by ordinary windows, to ensure that
1899 you see it. The message window shows the time for which the alarm was
1900 scheduled, so that you can see when it popped up if you were away from
1901 the computer at the time. If the alarm's scheduled time is in a
1902 different time zone from your local computer's setting, its time zone
1903 will also be displayed. (For reminder messages, the date/time shown is
1904 that for the main alarm or its recurrence, not the reminder message
1905 time, and the window title is
<quote>Reminder
</quote>.)
</para>
1907 <para>Alarm message windows remain visible until you acknowledge them,
1908 unless
<guilabel>Auto-close window after late-cancelation
1909 time
</guilabel> was checked in the
<link
1910 linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>. In the case of a
1911 recurring alarm, if an unacknowledged message window remains from a
1912 previous occurrence of the alarm, the existing window is simply popped
1913 up when the alarm recurs. This avoids having to acknowledge multiple
1914 copies of the same message should you not wish, or be unable, to
1915 acknowledge a message at the time it appears.
</para>
1917 <para>The alarm message window provides whichever of the following
1918 options are applicable to the displayed alarm:
</para>
1922 <para>Acknowledge the alarm by clicking the
1923 <guibutton>Close
</guibutton> button. This closes the window (after a
1924 prompt for confirmation, if you selected
1925 <guilabel>Confirm acknowledgment
</guilabel>).
</para>
1929 <para>Edit the alarm by clicking the
<guibutton>Edit...
</guibutton>
1930 button. This displays the
1931 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>.
</para>
1935 <para>Display options to defer the alarm until later by clicking the
1936 <guibutton>Defer...
</guibutton> button. Then select
1937 <guilabel>Defer to date/time
</guilabel> to enter the date and time
1938 when the message is to be redisplayed, or select
<guilabel>Defer for
1939 time interval
</guilabel> to enter how long after now (in hours and
1940 minutes) the message should be redisplayed. Then click
1941 <guibutton>OK
</guibutton> to defer the alarm message and close its
1944 <note><para>The time the alarm is deferred to must be earlier than its
1945 next scheduled occurrence or next advance reminder. For this reason,
1946 the
<guibutton>Defer...
</guibutton> button in the alarm message window
1947 and the
<guibutton>OK
</guibutton> button in the Deferral dialog are
1948 disabled one minute before the next occurrence or advance
1950 <para>Note that if a reminder is configured
<emphasis>after
</emphasis>
1951 the alarm, you
<emphasis>can
</emphasis> defer the alarm past its
1952 reminder time. In this case, the reminder will be
1953 suppressed.
</para></note>
1955 <note><para>The
<guibutton>Defer...
</guibutton> button is not
1956 available for alarms which are displayed at login due to the
1957 <guilabel>Repeat at login
</guilabel> option having been
1958 selected.
</para></note>
1962 <para>Stop playing the alarm's sound file by clicking the button
1963 showing the
<quote>stop playing
</quote> symbol.
</para>
1967 <para>If the alarm message was created by dragging an email from
1968 &kmail;, you can directly access the email in
&kmail; by clicking the
1969 button showing the
&kmail; icon. This will select and highlight the
1970 email in
&kmail;'s folder list.
</para>
1972 <warning><para>If
&kmail;'s indexes are regenerated, the link to the
1973 email in
&kmail; will be lost.
</para></warning>
1977 <para>The button showing the
<guiicon>&kalarm;</guiicon> icon provides
1978 a convenient way to activate
&kalarm;.
</para>
1982 <para>You can choose in the
1983 <link linkend=
"preferences-view">Configuration dialog
</link> which of
1984 two different modes should be used to display alarm message
1989 <para>As a normal window. In this mode, the keyboard focus is taken
1990 by the alarm message window when it appears, so if you are typing at
1991 the time your keystrokes will be diverted to it rather than your
1992 original application.
</para>
1996 <para>As a non-modal window. In this mode, the keyboard focus is
1997 unaffected when the alarm message window appears, so it will not
1998 interfere with your typing. However in this mode the window has no
1999 titlebar or frame, so you cannot move it or resize it.
</para>
2003 <note><para>When an alarm is displayed on top of a full screen
2004 application, it is shown as a non-modal window regardless of this
2005 configuration setting. This is due to a limitation of the window
2006 system.
</para></note>
2009 <title>Positioning of Message Windows
</title>
2011 <para>You can choose in the
2012 <link linkend=
"preferences-view">Configuration dialog
</link> which of
2013 two schemes should be used to position alarm message windows:
</para>
2017 <para>The windows are displayed as far away from the current mouse
2018 cursor as possible. This minimizes disruption to your work flow and
2019 minimizes the possibility of accidentally acknowledging the
2024 <para>The windows are displayed in the center of the screen. To reduce
2025 the chance of accidentally acknowledging the alarm, the buttons on the
2026 window are initially disabled, becoming active only after a
2027 configurable delay.
</para>
2031 <para>If you have several alarm message windows, or error messages,
2032 displayed, you can spread the windows out across the screen to make
2033 them all visible, or group them all together again in the top left
2034 corner of the screen, by means of the
<menuchoice>
2035 <guimenu>View
</guimenu><guimenuitem>Spread Windows
</guimenuitem>
2036 </menuchoice> menu option. If you wish, you can set up a global
2037 shortcut key for this action.
</para>
2042 <sect1 id=
"system-tray">
2043 <title>System Tray Operation
</title>
2045 <para>&kalarm; by default displays an icon in the system tray. The icon
2046 provides both control and an alarm monitoring status indication. A
2047 normal
&kalarm; icon indicates that alarms are being monitored, while
2048 a gray icon indicates that alarms are not being monitored. If some
2049 individual alarms are disabled, a small cross is overlaid on the
2052 <para>If you hover the mouse cursor over the system tray icon, a
2053 summary of the first few message alarms due in the next
24 hours are
2054 displayed as a tooltip. You can switch this feature off, or configure
2055 the number of alarms to display and their format, in the
2056 <link linkend=
"preferences-view">Configuration dialog
</link>.
</para>
2058 <para><mousebutton>Left
</mousebutton> click on the system tray icon to
2059 toggle between displaying and hiding the
&kalarm; main window.
</para>
2061 <para><mousebutton>Right
</mousebutton> click on the system tray icon to
2062 display its context menu:
</para>
2066 <term><menuchoice><guimenuitem>Enable Alarms
</guimenuitem></menuchoice></term>
2067 <listitem><para><action>Enables or disables monitoring of alarms.
</action></para>
2069 <link linkend=
"enable-disable">Enabling and Disabling Alarms
</link>
2075 <term><menuchoice><guimenuitem>New Alarm
</guimenuitem></menuchoice></term>
2076 <listitem><para><action>After you select the alarm type from the list
2077 which appears, opens the Alarm Edit dialog to create a new
2078 alarm.
</action></para>
2083 <term><menuchoice><guimenuitem>New Alarm From Template
</guimenuitem></menuchoice></term>
2084 <listitem><para><action>Displays the list of alarm templates in a
2085 menu. When you select one, the Alarm Edit dialog is opened, preset
2086 with that template's details.
</action></para>
2091 <term><menuchoice><guimenuitem>Stop Play
</guimenuitem></menuchoice></term>
2092 <listitem><para><action>Halts playback of the audio file currently
2093 playing.
</action></para>
2098 <term><menuchoice><guimenuitem>Spread Windows
</guimenuitem></menuchoice></term>
2099 <listitem><para><action>Spreads alarm and error message windows across
2100 the screen, or groups them together again.
</action></para>
2105 <term><menuchoice><guimenuitem>Configure
&kalarm;...
</guimenuitem></menuchoice></term>
2106 <listitem><para><action>Displays the
&kalarm; Configuration dialog.
</action></para>
2107 <para>The Configuration dialog is described in
2108 <link linkend=
"preferences">Configuring
&kalarm;</link>. It
2109 includes options relating to the
&kalarm; system tray icon.
</para>
2114 <term><menuchoice><guimenuitem>Restore / Minimize
</guimenuitem></menuchoice></term>
2115 <listitem><para><action>Restores or minimizes the main
&kalarm; window.
</action></para>
2120 <term><menuchoice><guimenuitem>Quit
</guimenuitem></menuchoice></term>
2121 <listitem><para><action>Closes the
&kalarm; system tray
2122 icon and main windows.
</action></para>
2123 <para>Quits
&kalarm; if no alarm message windows are displayed.
</para>
2129 <title>Displaying
&kalarm; in the System Tray
</title>
2131 <para>You must be running the
&kde; desktop or another suitable window
2132 manager in order to display
&kalarm; in the system tray.
</para>
2134 <para>To display
&kalarm; in the system tray, select
<menuchoice>
2135 <guimenu>View
</guimenu><guimenuitem>Show in System Tray
</guimenuitem>
2136 </menuchoice>.
</para>
2138 <para>To remove
&kalarm; from the system tray, deselect
2139 <menuchoice><guimenu>View
</guimenu>
2140 <guimenuitem>Show in System Tray
</guimenuitem></menuchoice>.
</para>
2142 <para>To choose whether or not
&kalarm; will be shown at startup in
2143 the system tray, use the
<link linkend=
"preferences-view">View
</link>
2144 tab of the Configuration dialog.
</para>
2148 <sect1 id=
"refreshing">
2149 <title>Refreshing Alarms
</title>
2151 <para>If in the unlikely event that any alarm was not triggered when
2152 it should have been, you can refresh the alarm list and trigger any
2153 missed alarms by selecting
2155 <guimenu>Actions
</guimenu><guimenuitem>Refresh Alarms
</guimenuitem>
2156 </menuchoice>. This causes
&kalarm; to reload all alarm
2159 <para>You can reload an individual calendar and refresh its alarms in
2161 <mousebutton>Right
</mousebutton> clicking the calendar in the
2162 calendars list and selecting the
2163 <menuchoice><guimenuitem>Reload
</guimenuitem></menuchoice> menu
2164 option. See
<link linkend=
"calendars">Alarm Calendars
</link> for
2169 <sect1 id=
"enable-disable">
2170 <title>Enabling and Disabling Alarms
</title>
2172 <para>Alarms may be enabled and disabled either as a whole or
2173 individually:
</para>
2177 <para><quote>Alarm monitoring
</quote> applies to alarms as a whole.
2178 While alarm monitoring is disabled, no alarms are triggered at all.
2179 While alarm monitoring is enabled (the normal situation), all alarms
2180 which are not individually disabled will trigger at the appropriate
2183 <para>When alarm monitoring is re-enabled, alarms which would have
2184 triggered while it was disabled are now triggered (unless any
2185 late-cancel option prevents this). In other words, disabling alarm
2186 monitoring has the same effect as stopping
&kalarm; – alarms are
2187 postponed until it is re-enabled.
</para>
2191 <para>Alarms may be individually enabled and disabled, independently
2192 of the alarm monitoring status. So the enabled/disabled status of
2193 individual alarms will be unchanged by disabling and then re-enabling
2194 alarm monitoring. Unlike alarm monitoring which could potentially be
2195 disabled due to
&kalarm; not running, individual alarms can only be
2196 disabled if you use menu commands to do so.
</para>
2198 <para>When an alarm is individually re-enabled, it is not now
2199 triggered if it became due while disabled. In other words, disabling
2200 an individual alarm cancels all its occurrences until it is
2203 <para>An alarm's individual enabled/disabled status is indicated by
2204 its color in the alarm list (the color being configurable in the
2205 <link linkend=
"preferences-view">View
</link> tab of the Configuration
2210 <para>For an alarm to trigger, it must be individually enabled as well
2211 as alarm monitoring being enabled.
</para>
2214 <title>Enabling Alarm Monitoring
</title>
2216 <para>For alarm monitoring to occur,
&kalarm; must be running. Once you
2217 run
&kalarm;, it will from then on start automatically whenever you log
2218 in unless you later disable it in the
2219 <link linkend=
"preferences-general">General
</link> tab of the
2220 Configuration dialog.
</para>
2222 <para>If alarm monitoring is currently disabled, do one of the
2223 following to enable alarms:
</para>
2227 <para>Select
<menuchoice><guimenu>Actions
</guimenu>
2228 <guimenuitem>Enable Alarms
</guimenuitem></menuchoice>.
</para>
2232 <para><mousebutton>Right
</mousebutton> click on the system tray icon
2234 <menuchoice><guimenuitem>Enable Alarms
</guimenuitem></menuchoice>
2235 from the context menu.
</para>
2242 <title>Disabling Alarm Monitoring
</title>
2244 <para>You can temporarily disable alarm monitoring, which prevents
2245 &kalarm; from checking any alarms either until you re-enable alarms, or
2246 – assuming that
&kalarm; is configured to start at login
–
2247 until the next time you log in.
</para>
2251 <para>Unselect
<menuchoice><guimenu>Actions
</guimenu>
2252 <guimenuitem>Enable Alarms
</guimenuitem></menuchoice>.
</para>
2256 <para><mousebutton>Right
</mousebutton> click on the system tray icon
2258 <menuchoice><guimenuitem>Enable Alarms
</guimenuitem></menuchoice>
2259 from the context menu.
</para>
2263 <para>Run
&kalarm; with the command line option
2264 <option>--disable-all
</option>.
</para>
2268 <para>Stop
&kalarm; as described in
2269 <link linkend=
"quitting">Quitting
&kalarm;</link>.
</para>
2273 <para>Alarms may be permanently disabled by preventing
&kalarm; from
2274 being started at login using the
2275 <link linkend=
"preferences-general">General
</link> tab of the
2276 Configuration dialog.
</para>
2281 <title>Enabling and Disabling Individual Alarms
</title>
2283 <para>To enable individual alarms which are currently disabled, do
2284 one of the following:
</para>
2288 <para>Select one or more alarms by clicking on their entries in the
2289 alarm list. Then choose
<menuchoice>
2290 <guimenu>Actions
</guimenu><guimenuitem>Enable
</guimenuitem>
2291 </menuchoice>.
</para>
2295 <para><mousebutton>Right
</mousebutton> click on the desired entries in
2296 the alarm list and choose
2297 <menuchoice><guimenuitem>Enable
</guimenuitem></menuchoice>
2298 from the context menu.
</para>
2302 <para>To disable individual alarms which are currently enabled, do one
2303 of the following:
</para>
2307 <para>Select one or more alarms by clicking on their entries in the
2308 alarm list. Then choose
<menuchoice>
2309 <guimenu>Actions
</guimenu><guimenuitem>Disable
</guimenuitem>
2310 </menuchoice>.
</para>
2314 <para><mousebutton>Right
</mousebutton> click on the desired entries in
2315 the alarm list and choose
2316 <menuchoice><guimenuitem>Disable
</guimenuitem></menuchoice>
2317 from the context menu.
</para>
2324 <sect1 id=
"wake-suspend">
2325 <title>Wake From Suspend
</title>
2327 <para>It is possible to configure a selected alarm to wake your
2328 computer from hibernation or suspension when the alarm triggers, so
2329 that the alarm action can occur even when the system was shut down.
2330 This function is controlled by a dialog which is accessed by selecting
2331 <menuchoice><guimenu>Actions
</guimenu>
2332 <guimenuitem>Wake From Suspend
</guimenuitem></menuchoice>. The dialog
2333 allows the Wake From Suspend alarm to be set, cancelled or
2336 <para>Use of the Wake From Suspend function requires
2337 administrative privileges. You will be prompted for the root password
2338 when you set or cancel a Wake From Suspend alarm.
</para>
2340 <note><para>Wake From Suspend is not supported on some computers,
2341 especially older ones, and some computers only support setting a
2342 wakeup time up to
24 hours ahead. There may also be restrictions on
2343 which suspend mode the function will wake from. You should consider
2344 setting up test alarms to check your system's capability before
2345 relying on this feature.
</para></note>
2347 <warning><para>Your computer can only schedule a single Wake From
2348 Suspend at a time. If you use this function with
&kalarm;, you must
2349 ensure that this does not conflict with any other application which
2350 also uses Wake From Suspend. Whenever an application schedules or
2351 clears Wake From Suspend, this cancels any previously set Wake From
2352 Suspend, no matter whether set by
&kalarm; or any other
2353 application.
</para></warning>
2355 <para>The Wake From Suspend dialog is used in conjunction with the
2356 alarm list in
&kalarm;'s main window.
</para>
2360 <para><guibutton>Use highlighted alarm
</guibutton>: this sets the
2361 alarm currently highlighted in the alarm list as the Wake From Suspend
2362 alarm. Any existing scheduled Wake From Suspend is cancelled, as
2363 explained above. The button is enabled only if exactly one alarm is
2368 <para><guibutton>Cancel wake from suspend
</guibutton>: this cancels
2369 any existing Wake From Suspend (whether set by
&kalarm; or any other
2370 application - see above). Note that this only cancels the wakeup
2371 function associated with the alarm; the alarm itself is not deleted
2372 and will continue to operate as normal.
</para>
2376 <para><guibutton>Show current alarm
</guibutton>: this highlights the
2377 current Wake From Suspend alarm in the alarm list, so that it can be
2378 identified. The button is disabled if no Wake From Suspend is
2379 currently configured.
</para>
2383 <para>The
<guilabel>Number of minutes before alarm to wake from
2384 suspend
</guilabel> control allows you, if you wish, to ensure that the
2385 system has time to fully restore itself before the alarm triggers, so
2386 that the alarm can trigger at the correct time.
</para>
2392 <sect1 id=
"quitting">
2393 <title>Quitting
&kalarm;</title>
2395 <para>Quit
&kalarm; by selecting
<menuchoice>
2396 <guimenu>File
</guimenu><guimenuitem>Quit
</guimenuitem></menuchoice>,
2397 or
<menuchoice><guimenuitem>Quit
</guimenuitem></menuchoice> in the
2398 system tray icon context menu. Alternatively, if the system tray icon
2399 is not visible, close all
&kalarm;'s windows.
</para>
2404 <chapter id=
"preferences">
2405 <title>Configuring
&kalarm;</title>
2407 <para>To configure
&kalarm;'s operation to suit your system and your
2408 personal preferences, select
<menuchoice><guimenu>Settings
</guimenu>
2409 <guimenuitem>Configure
&kalarm;...
</guimenuitem></menuchoice>.
2410 This displays the Configuration dialog.
</para>
2412 <sect1 id=
"preferences-general">
2413 <title>General
</title>
2415 <para>The
<guilabel>General
</guilabel> section lets you control
2416 &kalarm;'s overall behavior:
</para>
2420 <para><guilabel>Start at login
</guilabel>:
&kalarm; will be started
2421 automatically at
&kde; session login, ensuring that
&kalarm; runs at
2422 all times unless you manually quit.
</para>
2424 <warning><para>This option should always be checked unless you intend
2425 to discontinue use of
&kalarm;.
</para></warning>
2427 <note><para>This option is automatically reselected whenever
&kalarm;
2428 is run. So if you have unchecked this option and want to continue to
2429 prevent
&kalarm; from running at login, you need to uncheck this
2430 option again each time you run
&kalarm;.
</para></note>
2434 <para><guilabel>Warn before quitting
</guilabel>: When alarms are
2435 disabled while
&kalarm; is not running, selecting this option prompts
2436 you for confirmation if you attempt to terminate
&kalarm; using the
2437 system tray icon's
<menuchoice><guimenu>Quit
</guimenu></menuchoice>
2438 option. This prevents accidental disabling of alarms. For safety, this
2439 option is automatically re-enabled by default whenever you change run
2443 <listitem><para><guilabel>Confirm alarm deletions
</guilabel>: Specify
2444 whether you should be prompted for confirmation each time you delete
2448 <listitem><para><guilabel>Default defer time interval
</guilabel>:
2449 Enter the default time interval, in hours and minutes, to show
2450 initially when the Defer Alarm dialog is displayed. Note that if an
2451 alarm has been deferred previously, the interval shown initially in the
2452 Defer Alarm dialog will be equal to the deferral interval used the last
2453 time that alarm was deferred.
</para>
2456 <listitem><para><guilabel>Terminal for Command Alarms
</guilabel>:
2457 Here, you can select which type of terminal window should be used for
2458 command alarms which are executed in a terminal window. Some of the
2459 most common terminal window applications are preconfigured,
⪚
2460 <application>xterm
</application>,
&konsole;, although only those
2461 which are installed on your system will be shown here. You can view
2462 the actual command options used for each application by displaying the
2463 context help for its radio button.
</para>
2465 <para>If you want to use another application, or want to use one of
2466 those listed but with different command options, select
2467 <guilabel>Other
</guilabel> and enter the command to invoke the
2468 terminal window. By default, the alarm's command string will be
2469 appended to what you specify. Alternatively, you may specify where the
2470 alarm's command string should be inserted, by use of the following
2477 <para>The alarm's command string will be substituted.
</para>
2483 <para>The alarm's command string will be substituted, with a
<literal>sleep
</literal> appended.
</para>
2489 <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>
2495 <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>
2500 <para>When the command alarm is triggered, its command string will be
2501 quoted before being inserted into the terminal window command.
</para>
2507 <sect1 id=
"preferences-time">
2508 <title>Time and Date
</title>
2510 <para>The
<guilabel>Time and Date
</guilabel> section lets you set
2511 options relating to time and date:
</para>
2514 <listitem><para><guilabel>Time zone
</guilabel>: Select your time zone.
2515 &kalarm; uses this time zone throughout, except when you override it
2516 for individual alarms.
</para>
2519 <listitem><para><guilabel>Holiday region
</guilabel>: Select which
2520 country's or region's holidays to use. This affects recurring alarms
2521 for which the option to exclude holidays is selected.
</para>
2524 <listitem><para><guilabel>Start of day for date-only
2525 alarms
</guilabel>: Set the start-of-day time for the purposes of
2526 triggering date-only alarms,
&ie; ones for which the
<guilabel>Any
2527 time
</guilabel> option was selected. On the date when they are due,
2528 such alarms will be output at the earliest opportunity during the
2529 24 hours starting from the start-of-day time.
</para>
2532 <listitem><para><guilabel>Working Hours
</guilabel> group box: These
2533 options let you define your working hours, needed when the
2534 <guilabel>Only during working hours
</guilabel> option is selected for
2536 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>.
</para>
2539 <listitem><para>Check each day which is a working day.
</para>
2542 <listitem><para><guilabel>Daily start time
</guilabel>: enter the time
2543 at which you start work each day.
</para>
2546 <listitem><para><guilabel>Daily end time
</guilabel>: enter the time
2547 at which you finish work each day.
</para>
2552 <listitem><para><guilabel>KOrganizer event duration
</guilabel>: Enter
2553 the event duration to set in
&korganizer; for alarms which are copied to
2554 &korganizer;. The default duration is zero.
</para>
2560 <sect1 id=
"preferences-storage">
2561 <title>Storage
</title>
2563 <para>The
<guilabel>Storage
</guilabel> section lets you choose options
2564 for saving and archiving alarms:
</para>
2568 <para><guilabel>New Alarms
& Templates
</guilabel>: Specify which
2569 calendar to store new alarms and alarm templates in when using
2570 multiple alarm calendars:
</para>
2574 <para><guilabel>Store in default calendar
</guilabel>: New alarms and
2575 alarm templates are automatically added to the default alarm calendar
2576 without prompting for confirmation.
</para>
2580 <para><guilabel>Prompt for which calendar to store in
</guilabel>:
2581 When you create a new alarm or alarm template and there is more than
2582 one writeable alarm calendar, you will be prompted to choose which
2583 calendar to save it in. Note that when alarms are saved on expiry,
2584 they are always stored in the default archived alarm calendar without
2590 <listitem><para><guilabel>Archived Alarms
</guilabel> group box: These
2591 options control the storage of archived alarms in the default archived
2592 alarm calendar.
</para>
2595 <listitem><para><guilabel>Keep alarms after expiry
</guilabel>:
2596 Select this option to archive expired and deleted alarms. Deselect it
2597 to keep no record of alarms once they cease to be active. Note that
2598 deleted alarms are only archived if they have previously been
2599 triggered. If you delete an alarm before it ever triggers, it is
2603 <listitem><para><guilabel>Discard archived alarms after
</guilabel>:
2604 Set the number of days to store expired and deleted alarms in the
2605 archive, after which they are permanently deleted.
</para>
2608 <listitem><para><guibutton>Clear archived alarms
</guibutton>: This
2609 button discards all currently archived alarms from the default archived
2610 alarm calendar. (Other archived alarm calendars are left unchanged in
2611 case they are shared with other people.) This has no effect on
2612 alarms which subsequently expire or are deleted; they will continue to
2613 be archived according to the selected options.
</para>
2621 <sect1 id=
"preferences-email">
2622 <title>Email
</title>
2624 <para>The
<guilabel>Email
</guilabel> section lets you choose options
2625 for sending and addressing email alarms:
</para>
2629 <para><guilabel>Email client
</guilabel>: Specify the email
2630 client to be used to send email alarms:
</para>
2633 <listitem><para><guilabel>KMail
</guilabel>: When an email alarm is
2634 triggered, the email is sent using
&kmail; (which is started first if
2635 necessary) as follows:
</para>
2638 <listitem><para>If
&kmail; is version
1.7 or later, the email is sent
2639 automatically.
</para>
2642 <listitem><para>If
&kmail; is an older version, the email is added to
2643 &kmail;'s
<filename>outbox
</filename> folder for later
2644 transmission.
</para>
2649 <listitem><para><guilabel>Sendmail
</guilabel>: When an email alarm is
2650 triggered, the email is sent automatically using
2651 &Sendmail;. This option will only work if
2652 your system is configured to use
&Sendmail;,
2653 or a
&Sendmail; compatible mail transport
2654 agent such as
<application>postfix
</application> or
2655 <application>qmail
</application>.
</para>
2661 <para><guilabel>Copy sent emails into
&kmail;'s sent-items folder
</guilabel>:
2662 Select this option if, every time an email alarm is triggered, you
2663 want a copy of the transmitted email to be stored in
&kmail;'s
2664 <filename>sent-items
</filename> folder.
</para>
2666 <note><para>This option is not available when
&kmail; is selected as
2667 the email client, since
&kmail; automatically does this.
</para></note>
2671 <para><guilabel>Notify when remote emails are queued
</guilabel>:
2672 Select this option to display a notification whenever an email alarm
2673 queues an email for sending to a remote system. This may be useful
2674 if, for example, you have a dial-up connection, or email is queued in
2675 &kmail;'s
<filename>outbox
</filename> folder, so that you can
2676 ensure that you do whatever is needed to actually transmit
2681 <para>Select your email address to be used as the sender's address in
2682 email alarms:
</para>
2685 <listitem><para>Select
<guilabel>From
</guilabel> to enter an email
2689 <listitem><para>Select
<guilabel>Use address from System
2690 Settings
</guilabel> to use the email address which is configured in the
2691 &kde; System Settings.
</para>
2694 <listitem><para>Select
<guilabel>Use
&kmail; identities
</guilabel> to
2695 be able to choose at the time you configure an email alarm which of
2696 &kmail;'s email identities to use.
&kmail;'s default identity will be
2697 used for alarms which were already configured before you selected this
2704 <para>Select your email address to be used for sending blind copies of
2705 email alarms to yourself when the
2706 <guilabel>Copy email to self
</guilabel> option is selected:
</para>
2709 <listitem><para>Select
<guilabel>Bcc
</guilabel> to enter an email
2710 address. If blind copies are to be sent to your account on the
2711 computer which
&kalarm; runs on, you could simply enter your user
2712 login name here.
</para>
2715 <listitem><para>Select
<guilabel>Use address from System
2716 Settings
</guilabel> to use the email address which is configured in the
2717 &kde; System Settings.
</para>
2724 <sect1 id=
"preferences-view">
2727 <para>The
<guilabel>View
</guilabel> section lets you control some
2728 aspects of
&kalarm;'s appearance. In the
<guilabel>General
</guilabel>
2733 <para><guilabel>Show in system tray
</guilabel>: When selected, the
2734 system tray icon is displayed while
&kalarm; is running. In this mode,
2735 closing the system tray icon closes all
&kalarm; main windows, and if
2736 no message windows are visible, quits the application.
</para>
2740 <para><guilabel>System Tray Tooltip
</guilabel> group box: These options
2741 control what information is shown in the tooltip which appears when the
2742 mouse cursor hovers over
&kalarm;'s system tray icon.
</para>
2746 <para><guilabel>Show next
24 hours' alarms
</guilabel>: When selected,
2747 a summary of the first few alarms due in the next
24 hours is
2752 <para><guilabel>Maximum number of alarms to show
</guilabel>: Deselect
2753 this option to display all of the next
24 hours' alarms. Select it to
2754 set the maximum number of alarms which will be displayed.
</para>
2758 <para><guilabel>Show alarm time
</guilabel>: Select this option to show
2759 the time at which each alarm is scheduled.
</para>
2763 <para><guilabel>Show time until alarm
</guilabel>: Select this option to
2764 show the length of time remaining before each alarm's next scheduled
2765 occurrence. The length of time is shown in hours and minutes.
</para>
2769 <para><guilabel>Prefix
</guilabel>: Specify a symbol or text to show in
2770 front of the length of time until the alarm, to distinguish it from the
2771 time at which the alarm is scheduled.
</para>
2779 <para>The
<guilabel>Alarm List
</guilabel> group box allows the
2780 selection of the colors used in the alarm list in
&kalarm;'s main
2781 window, to show disabled and archived alarms.
</para>
2785 <para>The
<guilabel>Alarm Windows
</guilabel> tab contains options to control
2786 the appearance of alarm message windows.
</para>
2790 <para><guilabel>Position windows far from mouse cursor
</guilabel>:
2791 Select this option to display alarm message windows as far away from
2792 the current mouse cursor position as possible. This minimizes the
2793 chance of accidentally acknowledging an alarm by unintentionally
2794 clicking on a button just as the message window appears.
</para>
2798 <para><guilabel>Center windows, delay activating window buttons
</guilabel>:
2799 Select this option to display alarm message windows in the center of
2800 the screen. To reduce the chance of accidentally acknowledging the
2801 alarm, the window's buttons are initially disabled. The delay in
2802 seconds before they become active is set in
2803 <guilabel>Button activation delay (seconds)
</guilabel>.
</para>
2807 <para><guilabel>Message windows have a titlebar and take keyboard focus
</guilabel>: This
2808 option controls whether alarm message windows are modal or not,
&ie;
2809 whether they grab the keyboard focus when they appear. See the
2810 <link linkend=
"message-window">Alarm Message Window
</link> section for
2816 <sect1 id=
"preferences-edit">
2819 <para>The
<guilabel>Edit
</guilabel> section lets you choose
2820 default values for the options in the
2821 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>:
</para>
2824 <listitem><para>The
<guilabel>General
</guilabel> tab contains options
2825 which apply to all alarm types.
</para>
2828 <listitem><para>Set the default states for the
<guilabel>Show in
2829 KOrganizer
</guilabel> and
<guilabel>Cancel if late
</guilabel> check
2833 <listitem><para>Set the default recurrence type.
</para>
2836 <listitem><para>Select the default handling in non-leap years of
2837 yearly recurrences scheduled for February
29th.
</para>
2842 <listitem><para>The
<guilabel>Alarm Types
</guilabel> tab contains
2843 options which apply to specific types of alarm.
</para>
2847 <para>For display alarms:
</para>
2850 <listitem><para>Set the default states for the
2851 <guilabel>Auto-close window after this time
</guilabel> and
2852 <guilabel>Confirm acknowledgment
</guilabel> check boxes.
</para>
2855 <listitem><para>Set the default reminder period units.
</para>
2858 <listitem><para>Set the default special display alarm actions.
</para>
2861 <listitem><para>Set the default sound options. Note that a default
2862 sound file may be specified even if the sound type is not set to
2863 <guilabel>Sound file
</guilabel>.
</para>
2869 <para>For command alarms:
</para>
2872 <listitem><para>Set the default states for the
<guilabel>Enter a
2873 script
</guilabel> and
<guilabel>Execute in terminal window
</guilabel>
2880 <para>For email alarms:
</para>
2883 <listitem><para>Set the default state for the
<guilabel>Copy email to
2884 self
</guilabel> check box.
</para>
2891 <listitem><para>The
<guilabel>Font
& Color
</guilabel> tab lets you
2892 set the default appearance of alarm messages. Select their default
2893 font, and foreground and background colors.
</para>
2900 <chapter id=
"cmdline-operation">
2901 <title>Command Line Operation
</title>
2903 <para>When command line parameters are supplied,
&kalarm; does not
2904 display the list of scheduled alarms as described in
<link
2905 linkend=
"using-kalarm">Using
&kalarm;</link> above. Command line
2906 options specific to
&kalarm; may be used to perform the following
2910 <listitem><para>schedule a new alarm
</para>
2912 <listitem><para>control
&kalarm;'s display mode
</para>
2914 <listitem><para>obtain help
</para>
2918 <para>Additional command line options are provided primarily to enable
2919 other programs to interface to
&kalarm;. They are described in the
2920 chapter
<link linkend=
"cmdline-interface">Developer's Guide to
2921 &kalarm;</link>.
</para>
2923 <para>The command line must only contain options applicable to one
2924 &kalarm; operation. If you want to perform multiple operations, you
2925 must invoke
&kalarm; multiple times with a single set of options each
2928 <sect1 id=
"cmdline-schedule">
2929 <title>Schedule a New Alarm
</title>
2931 <para>The following options are used to schedule a new alarm:
</para>
2937 <entry>Option
</entry>
2938 <entry>Description
</entry>
2943 <entry><option>-a
</option>,
<option>--ack-confirm
</option></entry>
2944 <entry>Prompt for confirmation when the alarm message is
2945 acknowledged.
</entry>
2948 <entry><option>-A
</option>,
<option>--attach
<replaceable>URL
</replaceable></option></entry>
2949 <entry>Specify the path or
&URL; of a file which is to be attached
2950 to the email. This option may be repeated as necessary.
2951 <option>--mail
</option> must be specified with this option.
</entry>
2954 <entry><option>--auto-close
</option></entry>
2955 <entry>Automatically close the alarm window after the expiry of the
2956 <option>--late-cancel
</option> period.
2957 <option>--late-cancel
</option> must be specified with this
2961 <entry><option>-b
</option>,
<option>--beep
</option></entry>
2962 <entry>Make an audible beep when the message is displayed.
2963 <option>--speak
</option>,
<option>--play
</option> and
2964 <option>--play-repeat
</option> cannot be specified with this
2968 <entry><option>--bcc
</option></entry>
2969 <entry>Blind copy the email to yourself.
2970 <option>--mail
</option> must be specified with this option.
</entry>
2973 <entry><option>-c
</option>,
<option>--color
</option>,
<option>--colour
2974 <replaceable>color
</replaceable></option></entry>
2975 <entry>Set the message background color to the specified
&Qt;
2976 color name or hex code
0xRRGGBB.
</entry>
2979 <entry><option>-C
</option>,
<option>--colorfg
</option>,
<option>--colourfg
2980 <replaceable>color
</replaceable></option></entry>
2981 <entry>Set the message foreground color to the specified
&Qt;
2982 color name or hex code
0xRRGGBB.
</entry>
2985 <entry><option>-d
</option>,
<option>--disable
</option></entry>
2986 <entry>Disable the alarm. It will not trigger until it has been
2987 manually enabled.
</entry>
2990 <entry><option>--disable-all
</option></entry>
2991 <entry>Disable alarm monitoring. This prevents any alarms from
2992 being triggered until you re-enable alarms or restart
&kalarm;,
⪚
2994 <option>--triggerEvent
</option> cannot be specified with this
2998 <entry><option>-e
</option>,
<option>--exec
<replaceable>commandline
</replaceable></option></entry>
2999 <entry>Specify a shell command to execute. If specified, this option
3000 must be the last
&kalarm; option in
&kalarm;'s command line. All
3001 subsequent command parameters and options are interpreted as
3002 forming the command line to execute.
<option>--file
</option> and
3003 <option>--exec-display
</option> and
<option>--mail
</option> cannot
3004 be specified with this option.
3005 <option>--ack-confirm
</option>,
<option>--beep
</option>,
3006 <option>--color
</option> and
<option>--colorfg
</option> are ignored
3007 with this option.
</entry>
3010 <entry><option>-E
</option>,
<option>--exec-display
<replaceable>commandline
</replaceable></option></entry>
3011 <entry>Specify a shell command to execute to generate the alarm
3012 message text. If specified, this option must be the last
&kalarm;
3013 option in
&kalarm;'s command line. All subsequent command parameters
3014 and options are interpreted as forming the command line to execute.
3015 <option>--exec
</option>,
<option>--file
</option> and
3016 <option>--mail
</option> cannot be specified with this option.
</entry>
3019 <entry><option>-f
</option>,
<option>--file
<replaceable>URL
</replaceable></option></entry>
3020 <entry>Specify the path or
&URL; of a text or image file whose
3021 contents are to form the alarm message.
<option>--exec
</option>,
3022 <option>--exec-display
</option> and
<option>--mail
</option> cannot
3023 be specified, and
<replaceable>message
</replaceable> must not be
3024 present with this option.
</entry>
3027 <entry><option>-F
</option>,
<option>--from-id
3028 <replaceable>ID
</replaceable></option></entry>
3029 <entry>Use the specified
&kmail; identity as the sender of the
3030 email.
<option>--mail
</option> must be specified with this
3034 <entry><option>-i
</option>,
<option>--interval
3035 <replaceable>period
</replaceable></option></entry>
3036 <entry>Set the interval between repetitions of the alarm.
3037 Hours/minutes are specified in the format
3038 <replaceable>nHnM
</replaceable>, where
<replaceable>n
</replaceable>
3039 is a number,
⪚ 3H30M. Other time periods are specified in the
3040 format
<replaceable>nX
</replaceable>, where
3041 <replaceable>n
</replaceable> is a number and
3042 <replaceable>X
</replaceable> is one of the following letters: Y
3043 (years), M (months), W (weeks), D (days). If
3044 <option>--recurrence
</option> is also specified, Y (years) and M
3045 (months) are not allowed.
3046 Mandatory if
<option>--repeat
</option> or
<option>--until
</option>
3047 is specified.
</entry>
3050 <entry><option>-k
</option>,
<option>--korganizer
</option></entry>
3051 <entry>Show the alarm as an event in
&korganizer;'s active
3055 <entry><option>-l
</option>,
<option>--late-cancel
3056 <replaceable>period
</replaceable></option></entry>
3057 <entry>Cancel the alarm if it cannot be triggered within the
3058 specified
<replaceable>period
</replaceable> after the correct time.
3059 Hours/minutes are specified in the format
3060 <replaceable>nHnM
</replaceable>, where
<replaceable>n
</replaceable>
3061 is a number,
⪚ 3H30M. Other time periods are specified in the
3062 format
<replaceable>nX
</replaceable>, where
3063 <replaceable>n
</replaceable> is a number and
3064 <replaceable>X
</replaceable> is one of the following letters: W
3066 The default value of
<replaceable>period
</replaceable> is
1
3070 <entry><option>-L
</option>,
<option>--login
</option></entry>
3071 <entry>Trigger the alarm every time you log in.
3072 <option>--interval
</option>,
<option>--repeat
</option> and
3073 <option>--until
</option> cannot be specified with this
3077 <entry><option>-m
</option>,
<option>--mail
3078 <replaceable>address
</replaceable></option></entry>
3079 <entry>Send an email to the specified address. This option may be
3080 repeated as necessary.
<option>--exec
</option>,
3081 <option>--exec-display
</option> and
<option>--file
</option> cannot
3082 be specified with this option.
3083 <option>--ack-confirm
</option>,
<option>--beep
</option>,
3084 <option>--color
</option> and
<option>--colorfg
</option> are ignored
3085 with this option.
</entry>
3088 <entry><option>-p
</option>,
<option>--play
<replaceable>URL
</replaceable></option></entry>
3089 <entry>Specify the path or
&URL; of an audio file to be played once,
3090 either as an audio alarm or when the alarm message is displayed.
3091 <option>--play-repeat
</option>,
<option>--beep
</option> and
3092 <option>--speak
</option> cannot be specified with this
3096 <entry><option>-P
</option>,
<option>--play-repeat
<replaceable>URL
</replaceable></option></entry>
3097 <entry>Specify the path or
&URL; of an audio file to be played
3098 repeatedly, either until
<guilabel>Stop Play
</guilabel> is used, or
3099 for as long as the alarm message is displayed.
3100 <option>--play
</option>,
<option>--beep
</option> and
3101 <option>--speak
</option> cannot be specified with this
3105 <entry><option>--recurrence
3106 <replaceable>spec
</replaceable></option></entry>
3107 <entry>Set the alarm to recur. Specify the recurrence using iCalendar
3109 <ulink url=
"http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445
</ulink>),
3110 ⪚ <quote>FREQ=MONTHLY;COUNT=
4;INTERVAL=
3;BYDAY=-
1MO
</quote>.
3111 <option>--until
</option> cannot be specified with this
3115 <entry><option>-r
</option>,
<option>--repeat
3116 <replaceable>count
</replaceable></option></entry>
3117 <entry>Set the number of times the alarm should be triggered, or if
3118 a recurrence is specified with
<option>--recurrence
</option>, the
3119 number of times the alarm should be triggered each time
3120 <option>--recurrence
</option> activates it (
&ie; a repetition within
3121 a recurrence). If
<option>--recurrence
</option> is not present,
3122 specify -
1 to repeat the alarm indefinitely.
3123 <option>--interval
</option> must be, and
<option>--until
</option>
3124 cannot be, specified with this option.
</entry>
3127 <entry><option>-R
</option>,
<option>--reminder
3128 <replaceable>period
</replaceable></option></entry>
3129 <entry>Output a reminder alarm the specified length of time before
3130 or after the main alarm and each of its recurrences (if any).
3131 The
<replaceable>period
</replaceable> is specified in
3132 the same format as described for
<option>--late-cancel
</option>.
3133 By default, the reminder will occur before the alarm. To specify a
3134 reminder after the alarm, prefix
<replaceable>period
</replaceable>
3135 with
<replaceable>+
</replaceable>,
⪚ +
3D. This option cannot be
3136 specified with
<option>--exec
</option>,
<option>--mail
</option> or
3137 <option>--reminder-once
</option>.
</entry>
3140 <entry><option>--reminder-once
3141 <replaceable>period
</replaceable></option></entry>
3142 <entry>Output a reminder alarm once, the specified length of time
3143 before or after the first recurrence of the alarm. No reminder will
3144 be displayed before or after subsequent recurrences (if any). The
3145 <replaceable>period
</replaceable> is specified in the same format as
3146 described for
<option>--reminder
</option>. This option cannot
3147 be specified with
<option>--exec
</option>,
<option>--mail
</option>
3148 or
<option>--reminder
</option>.
</entry>
3151 <entry><option>-s
</option>,
<option>--speak
</option></entry>
3152 <entry>Speak the message when it is displayed. This option requires
3153 &jovie; to be installed and configured, together with a compatible
3154 speech synthesizer.
<option>--beep
</option>,
<option>--play
</option>
3155 and
<option>--play-repeat
</option> cannot be specified with this
3159 <entry><option>-S
</option>,
<option>--subject
3160 <replaceable>subject
</replaceable></option></entry>
3161 <entry>The subject line of the email.
<option>--mail
</option> must
3162 be specified with this option.
</entry>
3165 <entry><option>-t
</option>,
<option>--time
3166 <replaceable>date/time
</replaceable></option></entry>
3167 <entry>Trigger alarm on the date or at the date/time specified.
3168 Specify a date without a time in the format
3169 <replaceable>yyyy-mm-dd [TZ]
</replaceable>; specify a date and time
3170 by
<replaceable>[[[yyyy-]mm-]dd-]hh:mm [TZ]
</replaceable> (where
3171 omitted, date fields default to the values for today).
3172 If no time zone is specified, the local system time zone is
3173 assumed. If a time zone specifier
<replaceable>TZ
</replaceable> is
3174 present, it may be the name of a system time zone (
⪚
3175 <userinput>Europe/London
</userinput>),
<userinput>UTC
</userinput>
3176 representing the UTC time zone, or
<userinput>Clock
</userinput> to
3177 use the local computer clock and ignore time zones.
</entry>
3180 <entry><option>-v
</option>,
<option>--volume
3181 <replaceable>percentage
</replaceable></option></entry>
3182 <entry>Set the audio volume for playing the audio file. This option
3183 can only be used when
<option>--play
</option> or
3184 <option>--play-repeat
</option> is specified.
</entry>
3187 <entry><option>-u
</option>,
<option>--until
3188 <replaceable>date/time
</replaceable></option></entry>
3189 <entry>Repeat the alarm until the date or date/time specified.
3190 Specify the date or date/time using the same syntax as for
3191 <option>--time
</option>. Note that if
<option>--time
</option> is
3192 specified, the time zone will be taken from its value and no time
3193 zone may be included in the
<option>--until
</option> value.
3194 <option>--interval
</option> must be, and
3195 <option>--repeat
</option> and
<option>--recurrence
</option> cannot
3196 be, specified with this option.
</entry>
3199 <entry><replaceable>message
</replaceable></entry>
3200 <entry>Message text to display or, if
<option>--mail
</option> is
3201 specified, the body of the email message.
</entry>
3207 <para>Either a message text,
<option>--file
</option>,
3208 <option>--exec
</option>,
<option>--exec-display
</option>,
3209 <option>--play
</option> or
<option>--play-repeat
</option> must be
3210 specified; except as noted above, all the options are optional.
</para>
3212 <para>Two alternative examples which display a multi-line message with
3213 a red background at
10 p.m. on the
27th of this month are:
</para>
3215 <informalexample><screen>
3216 <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>
3217 <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>
3223 <sect1 id=
"cmdline-other">
3224 <title>Other Options
</title>
3226 <para>The following options are used to display the
3227 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link>, or to control
3228 &kalarm;'s display mode.
</para>
3234 <entry>Option
</entry>
3235 <entry>Description
</entry>
3240 <entry><option>--edit
<replaceable>eventID
</replaceable></option></entry>
3241 <entry>Display the Alarm Edit dialog to edit the alarm with the
3242 specified event ID.
</entry>
3245 <entry><option>--edit-new-audio
</option></entry>
3246 <entry>Display the Alarm Edit dialog, in order to edit a new audio
3250 <entry><option>--edit-new-command
</option></entry>
3251 <entry>Display the Alarm Edit dialog, in order to edit a new command
3255 <entry><option>--edit-new-display
</option></entry>
3256 <entry>Display the Alarm Edit dialog, in order to edit a new display
3260 <entry><option>--edit-new-email
</option></entry>
3261 <entry>Display the Alarm Edit dialog, in order to edit a new email
3265 <entry><option>--edit-new-preset
<replaceable>templateName
</replaceable></option></entry>
3266 <entry>Display the Alarm Edit dialog, preset with the alarm template
3267 of the specified name, in order to edit a new alarm.
</entry>
3270 <entry><option>--tray
</option></entry>
3271 <entry>Display
&kalarm; as an icon in the system tray.
</entry>
3279 <sect1 id=
"cmdline-help">
3280 <title>Help Options
</title>
3282 <para>The following help options are common to all
3283 &kde; programs:
</para>
3289 <entry>Option
</entry>
3290 <entry>Description
</entry>
3295 <entry><option>--help
</option></entry>
3296 <entry>Shows a brief options help text.
</entry>
3299 <entry><option>--help-qt
</option></entry>
3300 <entry>Shows numerous generic
&Qt;-specific options.
</entry>
3303 <entry><option>--help-kde
</option></entry>
3304 <entry>Shows numerous generic
&kde;-specific options.
</entry>
3307 <entry><option>--help-all
</option></entry>
3308 <entry>Shows all options.
</entry>
3311 <entry><option>--author
</option></entry>
3312 <entry>Shows the names and email addresses of
&kalarm; authors.
</entry>
3315 <entry><option>-v
</option>,
<option>--version
</option></entry>
3316 <entry>Shows the running versions of the
&Qt; library ,
&kde; and
3320 <entry><option>--license
</option></entry>
3321 <entry>Show license information.
</entry>
3330 <chapter id=
"developers">
3331 <title>Developer's Guide to
&kalarm;</title>
3333 <para>&kalarm; provides an interface to allow other applications to
3334 request the following functions:
</para>
3337 <listitem><para>schedule a new alarm
</para></listitem>
3338 <listitem><para>cancel an already scheduled alarm
</para></listitem>
3339 <listitem><para>trigger an already scheduled alarm
</para></listitem>
3340 <listitem><para>display the Alarm Edit dialog
</para></listitem>
3343 <para>Each of the above functions is implemented both by a
&DBus; call
3344 and by the command line.
&DBus; calls should be used in preference if
3345 &kalarm; is already running.
</para>
3347 <sect1 id=
"dbus-interface">
3348 <title>&DBus; Interface
</title>
3350 <para>The
&DBus; calls described in this document are all implemented
3351 in
&kalarm;'s
<constant>/kalarm
</constant> &DBus; object path. The
3352 interface is defined in the files
3353 <filename>org.kde.kalarm.kalarm.xml
</filename> and
3354 <filename>kalarmiface.h
</filename>.
</para>
3356 <refentry id=
"cancelEvent">
3358 <refentrytitle>cancelEvent
</refentrytitle>
3361 <refname>cancelEvent
</refname>
3362 <refpurpose>cancel an already scheduled alarm.
</refpurpose>
3366 void cancelEvent(const QString
& <replaceable>eventID
</replaceable>)
3370 <title>Parameters
</title>
3373 <term><parameter>eventID
</parameter></term>
3375 <para>Specifies the unique ID of the event to be canceled.
</para>
3383 <title>Description
</title>
3385 <para><function>cancelEvent()
</function> is a
&DBus; call to cancel
3386 the specified alarm.
&kalarm; deletes the alarm from the calendar
3387 without displaying or executing it.
</para>
3392 <refentry id=
"triggerEvent">
3394 <refentrytitle>triggerEvent
</refentrytitle>
3397 <refname>triggerEvent
</refname>
3398 <refpurpose>trigger an already scheduled alarm.
</refpurpose>
3402 void triggerEvent(const QString
& <replaceable>eventID
</replaceable>)
3406 <title>Parameters
</title>
3409 <term><parameter>eventID
</parameter></term>
3411 <para>Specifies the unique ID of the event to be triggered.
</para>
3419 <title>Description
</title>
3421 <para><function>triggerEvent()
</function> is a
&DBus; call to trigger
3422 the immediate display or execution of the specified alarm (regardless
3423 of what time it is scheduled for).
&kalarm; retrieves the alarm from
3424 the calendar and then displays or executes it.
</para>
3426 <para>If the alarm is already due,
&kalarm; then deletes all scheduled
3427 occurrences of the alarm up to the current time, and if no repetitions
3428 of the alarm still remain, the alarm is deleted from the calendar. If
3429 the alarm is not due yet, its scheduled occurrences are left
3435 <refentry id=
"scheduleMessage">
3437 <refentrytitle>scheduleMessage
</refentrytitle>
3440 <refname>scheduleMessage
</refname>
3441 <refpurpose>schedule a new alarm message.
</refpurpose>
3445 bool scheduleMessage(const QString
& <replaceable>message
</replaceable>,
3446 const QString
& <replaceable>startDateTime
</replaceable>,
3447 int
<replaceable>lateCancel
</replaceable>,
3448 unsigned
<replaceable>flags
</replaceable>,
3449 const QString
& <replaceable>bgColor
</replaceable>,
3450 const QString
& <replaceable>fgColor
</replaceable>,
3451 const QString
& <replaceable>font
</replaceable>,
3452 const QString
& <replaceable>audioURL
</replaceable>,
3453 int
<replaceable>reminderMins
</replaceable>,
3454 const QString
& <replaceable>recurrence
</replaceable>,
3455 int
<replaceable>subRepeatInterval
</replaceable>,
3456 int
<replaceable>subRepeatCount
</replaceable>)
3459 bool scheduleMessage(const QString
& <replaceable>message
</replaceable>,
3460 const QString
& <replaceable>startDateTime
</replaceable>,
3461 int
<replaceable>lateCancel
</replaceable>,
3462 unsigned
<replaceable>flags
</replaceable>,
3463 const QString
& <replaceable>bgColor
</replaceable>,
3464 const QString
& <replaceable>fgColor
</replaceable>,
3465 const QString
& <replaceable>font
</replaceable>,
3466 const QString
& <replaceable>audioURL
</replaceable>,
3467 int
<replaceable>reminderMins
</replaceable>,
3468 int
<replaceable>recurType
</replaceable>,
3469 int
<replaceable>recurInterval
</replaceable>,
3470 int
<replaceable>recurCount
</replaceable>)
3473 bool scheduleMessage(const QString
& <replaceable>message
</replaceable>,
3474 const QString
& <replaceable>startDateTime
</replaceable>,
3475 int
<replaceable>lateCancel
</replaceable>,
3476 unsigned
<replaceable>flags
</replaceable>,
3477 const QString
& <replaceable>bgColor
</replaceable>,
3478 const QString
& <replaceable>fgColor
</replaceable>,
3479 const QString
& <replaceable>font
</replaceable>,
3480 const QString
& <replaceable>audioURL
</replaceable>,
3481 int
<replaceable>reminderMins
</replaceable>,
3482 int
<replaceable>recurType
</replaceable>,
3483 int
<replaceable>recurInterval
</replaceable>,
3484 const QString
& <replaceable>endDateTime
</replaceable>)
3488 <title>Parameters
</title>
3491 <term><parameter>message
</parameter></term>
3493 <para>Specifies the text of the message to be scheduled, or if
3494 <parameter>flags
</parameter> has the
3495 <userinput>DISPLAY_COMMAND
</userinput> bit set, specifies the command
3496 line to execute to generate the message text.
</para>
3501 <term><parameter>startDateTime
</parameter></term>
3503 <para>Specifies the scheduled date, or date and time, at which the
3504 message should be displayed. For a date-only alarm, the string should
3505 be in the format
<replaceable>YYYY-MM-DD [TZ]
</replaceable> (as
3506 returned by
<methodname>QDate::toString(Qt::ISODate)
</methodname>). For
3507 an alarm with a date and time, the string should be in the format
3508 <replaceable>YYYY-MM-DDTHH:MM[:SS] [TZ]
</replaceable> (as returned by
3509 <methodname>QDateTime::toString(Qt::ISODate)
</methodname>) or
3510 <replaceable>HH:MM[:SS] [Clock]
</replaceable> (as returned by
3511 <methodname>QTime::toString(Qt::ISODate)
</methodname>). If no date is
3512 specified, today's date is used. Note that any seconds value is
3515 <para>If no time zone is specified, the local system time zone is
3516 assumed. If a time zone specifier
<replaceable>TZ
</replaceable> is
3517 present, it may be the name of a system time zone (
⪚
3518 <userinput>Europe/London
</userinput>),
<userinput>UTC
</userinput>
3519 representing the UTC time zone, or
<userinput>Clock
</userinput> to use
3520 the local computer clock and ignore time zones.
</para>
3525 <term><parameter>lateCancel
</parameter></term>
3527 <para>Causes the alarm to be canceled if it cannot be triggered within
3528 the specified number of minutes after the alarm's scheduled time. If
3529 the value is
0, the alarm will not be canceled no matter how late it
3530 is triggered.
</para>
3535 <term><parameter>flags
</parameter></term>
3537 <para>Specifies the logical OR of the desired alarm flags. The flag
3538 bits are those defined in class
<classname>KAlarmIface
</classname> in
3539 <filename>kalarmiface.h
</filename>. Note that not all flag bits are
3540 applicable to message alarms.
</para>
3545 <term><parameter>bgColor
</parameter></term>
3547 <para>Specifies the background color for displaying the message. The
3548 string may be in the format
<quote>#RRGGBB
</quote> (as returned by
3549 <methodname>QColor::name()
</methodname>) where RR, GG and BB are
3550 two-digit hexadecimal values for red, green and blue. Alternatively
3551 the string may be in any of the other formats accepted by
3552 <methodname>QColor::setNamedColor()
</methodname>, such as a name from
3553 the X color database (
⪚ <quote>red
</quote> or
3554 <quote>steelblue
</quote>). Set the string to null to specify the
3555 current default background color.
</para>
3560 <term><parameter>fgColor
</parameter></term>
3562 <para>Specifies the foreground color for displaying the message. The
3563 format of the string is the same as for
3564 <parameter>bgColor
</parameter>, or alternatively set the string to
3565 null to specify the current default foreground color.
</para>
3570 <term><parameter>font
</parameter></term>
3572 <para>Specifies the font for displaying the message. The format of the
3573 string is that output by
<methodname>QFont::toString()
</methodname>.
3574 Set the string to null to use the default message font current at the
3575 time the message is displayed.
</para>
3580 <term><parameter>audioURL
</parameter></term>
3582 <para>Specifies the audio file which is to be played when the message
3583 is displayed. Set the value to null if no audio file is to be
3589 <term><parameter>reminderMins
</parameter></term>
3591 <para>Specifies the number of minutes in advance of the main alarm and
3592 of each of its recurrences (if any) at which a reminder alarm should
3593 be displayed. Specify a negative value for a reminder to be displayed
3594 after the main alarm. Specify
0 if no reminder is required.
</para>
3599 <term><parameter>recurrence
</parameter></term>
3601 <para>Specifies a regular recurrence for the alarm, using iCalendar
3602 syntax as defined in
3603 <ulink url=
"http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445
</ulink>.
3604 For example,
<quote>FREQ=MONTHLY;COUNT=
4;INTERVAL=
3;BYDAY=-
1MO
</quote>
3605 would specify
4 repetitions at
3-monthly intervals on the last Monday
3606 of the month. For a non-recurring alarm, specify an empty
3612 <term><parameter>recurType
</parameter></term>
3614 <para>Specifies the recurrence type for the alarm. The permissible
3615 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
3616 are defined in class
<classname>KAlarmIface
</classname> in
3617 <filename>kalarmiface.h
</filename>. Monthly recurrences are of the
3618 day of the month type, and yearly recurrences are of the date in
3619 the year type, with the date in both cases taken from the
3620 <parameter>startDateTime
</parameter> parameter.
</para>
3625 <term><parameter>recurInterval
</parameter></term>
3627 <para>Specifies the number of periods
3628 (minutes/days/weeks/months/years as specified by
3629 <parameter>recurType
</parameter>) between recurrences of the
3635 <term><parameter>recurCount
</parameter></term>
3637 <para>Specifies the number of times that the alarm should be
3638 repeated. Specify -
1 to repeat the alarm indefinitely.
</para>
3643 <term><parameter>endDateTime
</parameter></term>
3645 <para>Specifies the end date, or date and time, for recurrences of the
3646 alarm. If
<parameter>startDateTime
</parameter> includes a time, this
3647 parameter must also include a time; if
<parameter>startDateTime
</parameter>
3648 contains only a date, this parameter must also contain only a
3649 date. It must not contain a time zone specifier; the same time zone as
3650 for
<parameter>startDateTime
</parameter> is used to interpret this
3651 parameter's value.
</para>
3656 <term><parameter>subRepeatInterval
</parameter></term>
3658 <para>Specifies the number of minutes between sub-repetitions of
3659 the alarm. Specify
0 for no sub-repetition. Ignored if no recurrence
3660 is specified.
</para>
3665 <term><parameter>subRepeatCount
</parameter></term>
3667 <para>Specifies the number of sub-repetitions of the alarm,
3668 including the initial occurrence.
</para>
3675 <refsect1 id=
"scheduleMessage-descrip">
3676 <title>Description
</title>
3677 <para><function>scheduleMessage()
</function> is a
&DBus; call to
3678 schedule the specified alarm message for display at the specified date
3679 and time. It has three forms. The most general form allows an
3680 arbitrary recurrence to be specified
– use this also for
3681 non-repeating alarms. The other forms provide convenient access to a
3682 restricted set of alarm recurrence types, one specifying a repetition
3683 count and the other an end time.
</para>
3685 <para>If the scheduled time (including any repetitions) has already
3686 passed,
&kalarm; immediately displays the message (unless the
3687 <parameter>lateCancel
</parameter> value indicates that it is now too
3688 late to display the alarm, in which case
&kalarm; ignores the
3689 request). If the scheduled time (or a repetition) is in the future,
3690 &kalarm; adds the alarm message to the default active alarm calendar
3691 for later display.
</para>
3695 <refentry id=
"scheduleFile">
3697 <refentrytitle>scheduleFile
</refentrytitle>
3700 <refname>scheduleFile
</refname>
3701 <refpurpose>schedule a new alarm which displays the contents of a
3702 text or image file.
</refpurpose>
3706 bool scheduleFile(const QString
& <replaceable>URL
</replaceable>,
3707 const QString
& <replaceable>startDateTime
</replaceable>,
3708 int
<replaceable>lateCancel
</replaceable>,
3709 unsigned
<replaceable>flags
</replaceable>,
3710 const QString
& <replaceable>bgColor
</replaceable>,
3711 const QString
& <replaceable>audioURL
</replaceable>,
3712 int
<replaceable>reminderMins
</replaceable>,
3713 const QString
& <replaceable>recurrence
</replaceable>,
3714 int
<replaceable>subRepeatInterval
</replaceable>,
3715 int
<replaceable>subRepeatCount
</replaceable>)
3718 bool scheduleFile(const QString
& <replaceable>URL
</replaceable>,
3719 const QString
& <replaceable>startDateTime
</replaceable>,
3720 int
<replaceable>lateCancel
</replaceable>,
3721 unsigned
<replaceable>flags
</replaceable>,
3722 const QString
& <replaceable>bgColor
</replaceable>,
3723 const QString
& <replaceable>audioURL
</replaceable>,
3724 int
<replaceable>reminderMins
</replaceable>,
3725 int
<replaceable>recurType
</replaceable>,
3726 int
<replaceable>recurInterval
</replaceable>,
3727 int
<replaceable>recurCount
</replaceable>)
3730 bool scheduleFile(const QString
& <replaceable>URL
</replaceable>,
3731 const QString
& <replaceable>startDateTime
</replaceable>,
3732 int
<replaceable>lateCancel
</replaceable>,
3733 unsigned
<replaceable>flags
</replaceable>,
3734 const QString
& <replaceable>bgColor
</replaceable>,
3735 const QString
& <replaceable>audioURL
</replaceable>,
3736 int
<replaceable>reminderMins
</replaceable>,
3737 int
<replaceable>recurType
</replaceable>,
3738 int
<replaceable>recurInterval
</replaceable>,
3739 const QString
& <replaceable>endDateTime
</replaceable>)
3743 <title>Parameters
</title>
3746 <term><parameter>URL
</parameter></term>
3748 <para>Specifies the text or image file whose contents are to be
3749 displayed in the message to be scheduled.
</para>
3754 <term><parameter>startDateTime
</parameter></term>
3756 <para>Specifies the scheduled date, or date and time, at which the
3757 message should be displayed. For a date-only alarm, the string should
3758 be in the format
<replaceable>YYYY-MM-DD [TZ]
</replaceable> (as
3759 returned by
<methodname>QDate::toString(Qt::ISODate)
</methodname>). For
3760 an alarm with a date and time, the string should be in the format
3761 <replaceable>YYYY-MM-DDTHH:MM[:SS] [TZ]
</replaceable> (as returned by
3762 <methodname>QDateTime::toString(Qt::ISODate)
</methodname>) or
3763 <replaceable>HH:MM[:SS] [Clock]
</replaceable> (as returned by
3764 <methodname>QTime::toString(Qt::ISODate)
</methodname>). If no date is
3765 specified, today's date is used. Note that any seconds value is
3768 <para>If no time zone is specified, the local system time zone is
3769 assumed. If a time zone specifier
<replaceable>TZ
</replaceable> is
3770 present, it may be the name of a system time zone (
⪚
3771 <userinput>Europe/London
</userinput>),
<userinput>UTC
</userinput>
3772 representing the UTC time zone, or
<userinput>Clock
</userinput> to use
3773 the local computer clock and ignore time zones.
</para>
3778 <term><parameter>lateCancel
</parameter></term>
3780 <para>Causes the alarm to be canceled if it cannot be triggered within
3781 the specified number of minutes after the alarm's scheduled time. If
3782 the value is
0, the alarm will not be canceled no matter how late it
3783 is triggered.
</para>
3788 <term><parameter>flags
</parameter></term>
3790 <para>Specifies the logical OR of the desired alarm flags. The flag
3791 bits are those defined in class
<classname>KAlarmIface
</classname> in
3792 <filename>kalarmiface.h
</filename>. Note that not all flag bits are
3793 applicable to file alarms.
</para>
3798 <term><parameter>bgColor
</parameter></term>
3800 <para>Specifies the background color for displaying the file. The
3801 string may be in the format
<quote>#RRGGBB
</quote> (as returned by
3802 <methodname>QColor::name()
</methodname>) where RR, GG and BB are
3803 two-digit hexadecimal values for red, green and blue. Alternatively
3804 the string may be in any of the other formats accepted by
3805 <methodname>QColor::setNamedColor()
</methodname>, such as a name from
3806 the X color database (
⪚ <quote>red
</quote> or
3807 <quote>steelblue
</quote>). Set the string to null to specify the
3808 current default background color.
</para>
3813 <term><parameter>audioURL
</parameter></term>
3815 <para>Specifies the audio file which is to be played when the message
3816 is displayed. Set the value to null if no audio file is to be
3822 <term><parameter>reminderMins
</parameter></term>
3824 <para>Specifies the number of minutes in advance of the main alarm and
3825 of each of its recurrences (if any) at which a reminder alarm should
3826 be displayed. Specify a negative value for a reminder to be displayed
3827 after the main alarm. Specify
0 if no reminder is required.
</para>
3832 <term><parameter>recurrence
</parameter></term>
3834 <para>Specifies a regular recurrence for the alarm, using iCalendar
3835 syntax as defined in
3836 <ulink url=
"http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445
</ulink>.
3837 For example,
<quote>FREQ=MONTHLY;COUNT=
4;INTERVAL=
3;BYDAY=-
1MO
</quote>
3838 would specify
4 repetitions at
3-monthly intervals on the last Monday
3839 of the month. For a non-recurring alarm, specify an empty
3845 <term><parameter>recurType
</parameter></term>
3847 <para>Specifies the recurrence type for the alarm. The permissible
3848 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
3849 are defined in class
<classname>KAlarmIface
</classname> in
3850 <filename>kalarmiface.h
</filename>. Monthly recurrences are of the
3851 day of the month type, and yearly recurrences are of the date in
3852 the year type, with the date in both cases taken from the
3853 <parameter>startDateTime
</parameter> parameter.
</para>
3858 <term><parameter>recurInterval
</parameter></term>
3860 <para>Specifies the number of periods
3861 (minutes/days/weeks/months/years as specified by
3862 <parameter>recurType
</parameter>) between recurrences of the
3868 <term><parameter>recurCount
</parameter></term>
3870 <para>Specifies the number of times that the alarm should be
3871 repeated. Specify -
1 to repeat the alarm indefinitely.
</para>
3876 <term><parameter>endDateTime
</parameter></term>
3878 <para>Specifies the end date, or date and time, for recurrences of the
3879 alarm. If
<parameter>startDateTime
</parameter> includes a time, this
3880 parameter must also include a time; if
<parameter>startDateTime
</parameter>
3881 contains only a date, this parameter must also contain only a
3882 date. It must not contain a time zone specifier; the same time zone as
3883 for
<parameter>startDateTime
</parameter> is used to interpret this
3884 parameter's value.
</para>
3889 <term><parameter>subRepeatInterval
</parameter></term>
3891 <para>Specifies the number of minutes between sub-repetitions of
3892 the alarm. Specify
0 for no sub-repetition. Ignored if no recurrence
3893 is specified.
</para>
3898 <term><parameter>subRepeatCount
</parameter></term>
3900 <para>Specifies the number of sub-repetitions of the alarm,
3901 including the initial occurrence.
</para>
3909 <title>Description
</title>
3910 <para><function>scheduleFile()
</function> is a
&DBus; call to schedule
3911 the specified text or image file for display at the specified date and
3912 time. Apart from specifying a file path or
&URL; and omitting the
3913 foreground color and font, its usage is identical to
3914 <link linkend=
"scheduleMessage-descrip"><function>scheduleMessage
</function></link>
3915 - see the description of that function for further details.
</para>
3920 <refentry id=
"scheduleCommand">
3922 <refentrytitle>scheduleCommand
</refentrytitle>
3925 <refname>scheduleCommand
</refname>
3926 <refpurpose>schedule a new alarm which executes a shell
3927 command.
</refpurpose>
3931 bool scheduleCommand(const QString
& <replaceable>commandLine
</replaceable>,
3932 const QString
& <replaceable>startDateTime
</replaceable>,
3933 int
<replaceable>lateCancel
</replaceable>,
3934 unsigned
<replaceable>flags
</replaceable>,
3935 const QString
& <replaceable>recurrence
</replaceable>,
3936 int
<replaceable>subRepeatInterval
</replaceable>,
3937 int
<replaceable>subRepeatCount
</replaceable>)
3940 bool scheduleCommand(const QString
& <replaceable>commandLine
</replaceable>,
3941 const QString
& <replaceable>startDateTime
</replaceable>,
3942 int
<replaceable>lateCancel
</replaceable>,
3943 unsigned
<replaceable>flags
</replaceable>,
3944 int
<replaceable>recurType
</replaceable>,
3945 int
<replaceable>recurInterval
</replaceable>,
3946 int
<replaceable>recurCount
</replaceable>)
3949 bool scheduleCommand(const QString
& <replaceable>commandLine
</replaceable>,
3950 const QString
& <replaceable>startDateTime
</replaceable>,
3951 int
<replaceable>lateCancel
</replaceable>,
3952 unsigned
<replaceable>flags
</replaceable>,
3953 int
<replaceable>recurType
</replaceable>,
3954 int
<replaceable>recurInterval
</replaceable>,
3955 const QString
& <replaceable>endDateTime
</replaceable>)
3959 <title>Parameters
</title>
3962 <term><parameter>commandLine
</parameter></term>
3964 <para>Specifies the command whose execution is to be scheduled. The
3965 <parameter>flags
</parameter> parameter indicates whether this
3966 parameter contains a shell command line or a command script.
</para>
3971 <term><parameter>startDateTime
</parameter></term>
3973 <para>Specifies the scheduled date, or date and time, at which the
3974 message should be displayed. For a date-only alarm, the string should
3975 be in the format
<replaceable>YYYY-MM-DD [TZ]
</replaceable> (as
3976 returned by
<methodname>QDate::toString(Qt::ISODate)
</methodname>). For
3977 an alarm with a date and time, the string should be in the format
3978 <replaceable>YYYY-MM-DDTHH:MM[:SS] [TZ]
</replaceable> (as returned by
3979 <methodname>QDateTime::toString(Qt::ISODate)
</methodname>) or
3980 <replaceable>HH:MM[:SS] [Clock]
</replaceable> (as returned by
3981 <methodname>QTime::toString(Qt::ISODate)
</methodname>). If no date is
3982 specified, today's date is used. Note that any seconds value is
3985 <para>If no time zone is specified, the local system time zone is
3986 assumed. If a time zone specifier
<replaceable>TZ
</replaceable> is
3987 present, it may be the name of a system time zone (
⪚
3988 <userinput>Europe/London
</userinput>),
<userinput>UTC
</userinput>
3989 representing the UTC time zone, or
<userinput>Clock
</userinput> to use
3990 the local computer clock and ignore time zones.
</para>
3995 <term><parameter>lateCancel
</parameter></term>
3997 <para>Causes the alarm to be canceled if it cannot be triggered within
3998 the specified number of minutes after the alarm's scheduled time. If
3999 the value is
0, the alarm will not be canceled no matter how late it
4000 is triggered.
</para>
4005 <term><parameter>flags
</parameter></term>
4007 <para>Specifies the logical OR of the desired alarm flags. The flag
4008 bits are those defined in class
<classname>KAlarmIface
</classname> in
4009 <filename>kalarmiface.h
</filename>. Note that not all flag bits are
4010 applicable to command alarms.
</para>
4015 <term><parameter>recurrence
</parameter></term>
4017 <para>Specifies a regular recurrence for the alarm, using iCalendar
4018 syntax as defined in
4019 <ulink url=
"http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445
</ulink>.
4020 For example,
<quote>FREQ=MONTHLY;COUNT=
4;INTERVAL=
3;BYDAY=-
1MO
</quote>
4021 would specify
4 repetitions at
3-monthly intervals on the last Monday
4022 of the month. For a non-recurring alarm, specify an empty
4028 <term><parameter>recurType
</parameter></term>
4030 <para>Specifies the recurrence type for the alarm. The permissible
4031 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
4032 are defined in class
<classname>KAlarmIface
</classname> in
4033 <filename>kalarmiface.h
</filename>. Monthly recurrences are of the
4034 day of the month type, and yearly recurrences are of the date in
4035 the year type, with the date in both cases taken from the
4036 <parameter>startDateTime
</parameter> parameter.
</para>
4041 <term><parameter>recurInterval
</parameter></term>
4043 <para>Specifies the number of periods
4044 (minutes/days/weeks/months/years as specified by
4045 <parameter>recurType
</parameter>) between recurrences of the
4051 <term><parameter>recurCount
</parameter></term>
4053 <para>Specifies the number of times that the alarm should be
4054 repeated. Specify -
1 to repeat the alarm indefinitely.
</para>
4059 <term><parameter>endDateTime
</parameter></term>
4061 <para>Specifies the end date, or date and time, for recurrences of the
4062 alarm. If
<parameter>startDateTime
</parameter> includes a time, this
4063 parameter must also include a time; if
<parameter>startDateTime
</parameter>
4064 contains only a date, this parameter must also contain only a
4065 date. It must not contain a time zone specifier; the same time zone as
4066 for
<parameter>startDateTime
</parameter> is used to interpret this
4067 parameter's value.
</para>
4072 <term><parameter>subRepeatInterval
</parameter></term>
4074 <para>Specifies the number of minutes between sub-repetitions of
4075 the alarm. Specify
0 for no sub-repetition. Ignored if no recurrence
4076 is specified.
</para>
4081 <term><parameter>subRepeatCount
</parameter></term>
4083 <para>Specifies the number of sub-repetitions of the alarm,
4084 including the initial occurrence.
</para>
4092 <title>Description
</title>
4093 <para><function>scheduleCommand()
</function> is a
&DBus; call to
4094 schedule the specified shell command line, or command script, for
4095 execution at the specified date and time. Apart from specifying a
4096 command and omitting the message color, font and audio file
4097 parameters, its usage is identical to
4098 <link linkend=
"scheduleMessage-descrip"><function>scheduleMessage
</function></link>
4099 - see the description of that function for further details.
</para>
4104 <refentry id=
"scheduleEmail">
4106 <refentrytitle>scheduleEmail
</refentrytitle>
4109 <refname>scheduleEmail
</refname>
4110 <refpurpose>schedule a new alarm which sends an email.
</refpurpose>
4114 bool scheduleEmail(const QString
& <replaceable>fromID
</replaceable>,
4115 const QString
& <replaceable>addresses
</replaceable>,
4116 const QString
& <replaceable>subject
</replaceable>,
4117 const QString
& <replaceable>message
</replaceable>,
4118 const QString
& <replaceable>attachments
</replaceable>,
4119 const QString
& <replaceable>startDateTime
</replaceable>,
4120 int
<replaceable>lateCancel
</replaceable>,
4121 unsigned
<replaceable>flags
</replaceable>,
4122 const QString
& <replaceable>recurrence
</replaceable>,
4123 int
<replaceable>subRepeatInterval
</replaceable>,
4124 int
<replaceable>subRepeatCount
</replaceable>)
4127 bool scheduleEmail(const QString
& <replaceable>fromID
</replaceable>,
4128 const QString
& <replaceable>addresses
</replaceable>,
4129 const QString
& <replaceable>subject
</replaceable>,
4130 const QString
& <replaceable>message
</replaceable>,
4131 const QString
& <replaceable>attachments
</replaceable>,
4132 const QString
& <replaceable>startDateTime
</replaceable>,
4133 int
<replaceable>lateCancel
</replaceable>,
4134 unsigned
<replaceable>flags
</replaceable>,
4135 int
<replaceable>recurType
</replaceable>,
4136 int
<replaceable>recurInterval
</replaceable>,
4137 int
<replaceable>recurCount
</replaceable>)
4140 bool scheduleEmail(const QString
& <replaceable>fromID
</replaceable>,
4141 const QString
& <replaceable>addresses
</replaceable>,
4142 const QString
& <replaceable>subject
</replaceable>,
4143 const QString
& <replaceable>message
</replaceable>,
4144 const QString
& <replaceable>attachments
</replaceable>,
4145 const QString
& <replaceable>startDateTime
</replaceable>,
4146 int
<replaceable>lateCancel
</replaceable>,
4147 unsigned
<replaceable>flags
</replaceable>,
4148 int
<replaceable>recurType
</replaceable>,
4149 int
<replaceable>recurInterval
</replaceable>,
4150 const QString
& <replaceable>endTime
</replaceable>)
4154 <title>Parameters
</title>
4157 <term><parameter>fromID
</parameter></term>
4159 <para>The
&kmail; identity to use as the sender of the email. If
4160 empty, the sender's email address will be that configured in
4162 <link linkend=
"preferences-email">Email preferences
</link>.
</para>
4167 <term><parameter>addresses
</parameter></term>
4169 <para>A comma separated list of recipients' email addresses.
</para>
4174 <term><parameter>subject
</parameter></term>
4176 <para>Specifies the subject line of the email.
</para>
4181 <term><parameter>message
</parameter></term>
4183 <para>Specifies the email message body.
</para>
4188 <term><parameter>attachments
</parameter></term>
4190 <para>A comma-separated list of paths or
&URL;s of files to send as
4191 email attachments.
</para>
4196 <term><parameter>startDateTime
</parameter></term>
4198 <para>Specifies the scheduled date, or date and time, at which the
4199 message should be displayed. For a date-only alarm, the string should
4200 be in the format
<replaceable>YYYY-MM-DD [TZ]
</replaceable> (as
4201 returned by
<methodname>QDate::toString(Qt::ISODate)
</methodname>). For
4202 an alarm with a date and time, the string should be in the format
4203 <replaceable>YYYY-MM-DDTHH:MM[:SS] [TZ]
</replaceable> (as returned by
4204 <methodname>QDateTime::toString(Qt::ISODate)
</methodname>) or
4205 <replaceable>HH:MM[:SS] [Clock]
</replaceable> (as returned by
4206 <methodname>QTime::toString(Qt::ISODate)
</methodname>). If no date is
4207 specified, today's date is used. Note that any seconds value is
4210 <para>If no time zone is specified, the local system time zone is
4211 assumed. If a time zone specifier
<replaceable>TZ
</replaceable> is
4212 present, it may be the name of a system time zone (
⪚
4213 <userinput>Europe/London
</userinput>),
<userinput>UTC
</userinput>
4214 representing the UTC time zone, or
<userinput>Clock
</userinput> to use
4215 the local computer clock and ignore time zones.
</para>
4220 <term><parameter>lateCancel
</parameter></term>
4222 <para>Causes the alarm to be canceled if it cannot be triggered within
4223 the specified number of minutes after the alarm's scheduled time. If
4224 the value is
0, the alarm will not be canceled no matter how late it
4225 is triggered.
</para>
4230 <term><parameter>flags
</parameter></term>
4232 <para>Specifies the logical OR of the desired alarm flags. The flag
4233 bits are those defined in class
<classname>KAlarmIface
</classname> in
4234 <filename>kalarmiface.h
</filename>. Note that not all flag bits are
4235 applicable to email alarms.
</para>
4240 <term><parameter>recurrence
</parameter></term>
4242 <para>Specifies a regular recurrence for the alarm, using iCalendar
4243 syntax as defined in
4244 <ulink url=
"http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445
</ulink>.
4245 For example,
<quote>FREQ=MONTHLY;COUNT=
4;INTERVAL=
3;BYDAY=-
1MO
</quote>
4246 would specify
4 repetitions at
3-monthly intervals on the last Monday
4247 of the month. For a non-recurring alarm, specify an empty
4253 <term><parameter>recurType
</parameter></term>
4255 <para>Specifies the recurrence type for the alarm. The permissible
4256 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
4257 are defined in class
<classname>KAlarmIface
</classname> in
4258 <filename>kalarmiface.h
</filename>. Monthly recurrences are of the
4259 day of the month type, and yearly recurrences are of the date in
4260 the year type, with the date in both cases taken from the
4261 <parameter>startDateTime
</parameter> parameter.
</para>
4266 <term><parameter>recurInterval
</parameter></term>
4268 <para>Specifies the number of periods
4269 (minutes/days/weeks/months/years as specified by
4270 <parameter>recurType
</parameter>) between recurrences of the
4276 <term><parameter>recurCount
</parameter></term>
4278 <para>Specifies the number of times that the alarm should be
4279 repeated. Specify -
1 to repeat the alarm indefinitely.
</para>
4284 <term><parameter>endDateTime
</parameter></term>
4286 <para>Specifies the end date, or date and time, for recurrences of the
4287 alarm. If
<parameter>startDateTime
</parameter> includes a time, this
4288 parameter must also include a time; if
<parameter>startDateTime
</parameter>
4289 contains only a date, this parameter must also contain only a
4290 date. It must not contain a time zone specifier; the same time zone as
4291 for
<parameter>startDateTime
</parameter> is used to interpret this
4292 parameter's value.
</para>
4297 <term><parameter>subRepeatInterval
</parameter></term>
4299 <para>Specifies the number of minutes between sub-repetitions of
4300 the alarm. Specify
0 for no sub-repetition. Ignored if no recurrence
4301 is specified.
</para>
4306 <term><parameter>subRepeatCount
</parameter></term>
4308 <para>Specifies the number of sub-repetitions of the alarm,
4309 including the initial occurrence.
</para>
4317 <title>Description
</title>
4318 <para><function>scheduleEmail()
</function> is a
&DBus; call to
4319 schedule the specified email for sending at the specified date and
4320 time. Apart from specifying the email header and contents and omitting
4321 the message color, font and audio file parameters, its usage is
4323 <link linkend=
"scheduleMessage-descrip"><function>scheduleMessage
</function></link>
4324 - see the description of that function for further details.
</para>
4329 <refentry id=
"scheduleAudio">
4331 <refentrytitle>scheduleAudio
</refentrytitle>
4334 <refname>scheduleAudio
</refname>
4335 <refpurpose>schedule a new alarm which executes a shell
4336 command.
</refpurpose>
4340 bool scheduleAudio(const QString
& <replaceable>audioURL
</replaceable>,
4341 int
<replaceable>volumePercent
</replaceable>,
4342 const QString
& <replaceable>startDateTime
</replaceable>,
4343 int
<replaceable>lateCancel
</replaceable>,
4344 unsigned
<replaceable>flags
</replaceable>,
4345 const QString
& <replaceable>recurrence
</replaceable>,
4346 int
<replaceable>subRepeatInterval
</replaceable>,
4347 int
<replaceable>subRepeatCount
</replaceable>)
4350 bool scheduleAudio(const QString
& <replaceable>audioURL
</replaceable>,
4351 int
<replaceable>volumePercent
</replaceable>,
4352 const QString
& <replaceable>startDateTime
</replaceable>,
4353 int
<replaceable>lateCancel
</replaceable>,
4354 unsigned
<replaceable>flags
</replaceable>,
4355 int
<replaceable>recurType
</replaceable>,
4356 int
<replaceable>recurInterval
</replaceable>,
4357 int
<replaceable>recurCount
</replaceable>)
4360 bool scheduleAudio(const QString
& <replaceable>audioURL
</replaceable>,
4361 int
<replaceable>volumePercent
</replaceable>,
4362 const QString
& <replaceable>startDateTime
</replaceable>,
4363 int
<replaceable>lateCancel
</replaceable>,
4364 unsigned
<replaceable>flags
</replaceable>,
4365 int
<replaceable>recurType
</replaceable>,
4366 int
<replaceable>recurInterval
</replaceable>,
4367 const QString
& <replaceable>endDateTime
</replaceable>)
4371 <title>Parameters
</title>
4374 <term><parameter>audioURL
</parameter></term>
4376 <para>Specifies the audio file which is to be played.
</para>
4381 <term><parameter>volumePercent
</parameter></term>
4383 <para>Specifies the volume level to use, as a percentage of full
4384 volume. Specify -
1 to use the default volume.
</para>
4389 <term><parameter>startDateTime
</parameter></term>
4391 <para>Specifies the scheduled date, or date and time, at which the
4392 message should be displayed. For a date-only alarm, the string should
4393 be in the format
<replaceable>YYYY-MM-DD [TZ]
</replaceable> (as
4394 returned by
<methodname>QDate::toString(Qt::ISODate)
</methodname>). For
4395 an alarm with a date and time, the string should be in the format
4396 <replaceable>YYYY-MM-DDTHH:MM[:SS] [TZ]
</replaceable> (as returned by
4397 <methodname>QDateTime::toString(Qt::ISODate)
</methodname>) or
4398 <replaceable>HH:MM[:SS] [Clock]
</replaceable> (as returned by
4399 <methodname>QTime::toString(Qt::ISODate)
</methodname>). If no date is
4400 specified, today's date is used. Note that any seconds value is
4403 <para>If no time zone is specified, the local system time zone is
4404 assumed. If a time zone specifier
<replaceable>TZ
</replaceable> is
4405 present, it may be the name of a system time zone (
⪚
4406 <userinput>Europe/London
</userinput>),
<userinput>UTC
</userinput>
4407 representing the UTC time zone, or
<userinput>Clock
</userinput> to use
4408 the local computer clock and ignore time zones.
</para>
4413 <term><parameter>lateCancel
</parameter></term>
4415 <para>Causes the alarm to be canceled if it cannot be triggered within
4416 the specified number of minutes after the alarm's scheduled time. If
4417 the value is
0, the alarm will not be canceled no matter how late it
4418 is triggered.
</para>
4423 <term><parameter>flags
</parameter></term>
4425 <para>Specifies the logical OR of the desired alarm flags. The flag
4426 bits are those defined in class
<classname>KAlarmIface
</classname> in
4427 <filename>kalarmiface.h
</filename>. Note that not all flag bits are
4428 applicable to command alarms.
</para>
4433 <term><parameter>recurrence
</parameter></term>
4435 <para>Specifies a regular recurrence for the alarm, using iCalendar
4436 syntax as defined in
4437 <ulink url=
"http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445
</ulink>.
4438 For example,
<quote>FREQ=MONTHLY;COUNT=
4;INTERVAL=
3;BYDAY=-
1MO
</quote>
4439 would specify
4 repetitions at
3-monthly intervals on the last Monday
4440 of the month. For a non-recurring alarm, specify an empty
4446 <term><parameter>recurType
</parameter></term>
4448 <para>Specifies the recurrence type for the alarm. The permissible
4449 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These
4450 are defined in class
<classname>KAlarmIface
</classname> in
4451 <filename>kalarmiface.h
</filename>. Monthly recurrences are of the
4452 day of the month type, and yearly recurrences are of the date in
4453 the year type, with the date in both cases taken from the
4454 <parameter>startDateTime
</parameter> parameter.
</para>
4459 <term><parameter>recurInterval
</parameter></term>
4461 <para>Specifies the number of periods
4462 (minutes/days/weeks/months/years as specified by
4463 <parameter>recurType
</parameter>) between recurrences of the
4469 <term><parameter>recurCount
</parameter></term>
4471 <para>Specifies the number of times that the alarm should be
4472 repeated. Specify -
1 to repeat the alarm indefinitely.
</para>
4477 <term><parameter>endDateTime
</parameter></term>
4479 <para>Specifies the end date, or date and time, for recurrences of the
4480 alarm. If
<parameter>startDateTime
</parameter> includes a time, this
4481 parameter must also include a time; if
<parameter>startDateTime
</parameter>
4482 contains only a date, this parameter must also contain only a
4483 date. It must not contain a time zone specifier; the same time zone as
4484 for
<parameter>startDateTime
</parameter> is used to interpret this
4485 parameter's value.
</para>
4490 <term><parameter>subRepeatInterval
</parameter></term>
4492 <para>Specifies the number of minutes between sub-repetitions of
4493 the alarm. Specify
0 for no sub-repetition. Ignored if no recurrence
4494 is specified.
</para>
4499 <term><parameter>subRepeatCount
</parameter></term>
4501 <para>Specifies the number of sub-repetitions of the alarm,
4502 including the initial occurrence.
</para>
4510 <title>Description
</title>
4511 <para><function>scheduleAudio()
</function> is a
&DBus; call to
4512 schedule the specified audio file to be played at the specified date
4513 and time. Apart from specifying a volume and omitting the message
4514 color and font parameters, its usage is identical to
4515 <link linkend=
"scheduleMessage-descrip"><function>scheduleMessage
</function></link>
4516 - see the description of that function for further details.
</para>
4520 <refentry id=
"dbus_edit">
4522 <refentrytitle>edit
</refentrytitle>
4525 <refname>edit
</refname>
4526 <refpurpose>Display the
<link linkend=
"alarm-edit-dlg">Alarm Edit
4527 dialog
</link> to edit an alarm.
</refpurpose>
4531 bool edit(const QString
& <replaceable>eventID
</replaceable>)
4535 <title>Parameters
</title>
4538 <term><parameter>eventID
</parameter></term>
4540 <para>Specifies the unique ID of the event to be edited.
</para>
4547 <title>Return value
</title>
4548 <para><returnvalue>false
</returnvalue> if the specified
4549 alarm could not be found or is read-only,
4550 <returnvalue>true
</returnvalue> otherwise.
</para>
4555 <title>Description
</title>
4557 <para><function>edit()
</function> is a
&DBus; call to display the
4558 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> to edit the
4559 specified alarm.
</para>
4564 <refentry id=
"dbus_editnew">
4566 <refentrytitle>editNew
</refentrytitle>
4569 <refname>editNew
</refname>
4570 <refpurpose>Display the
<link linkend=
"alarm-edit-dlg">Alarm Edit
4571 dialog
</link> to edit a new alarm.
</refpurpose>
4575 bool editNew(int
<replaceable>type
</replaceable>)
4578 bool editNew(const QString
& <replaceable>templateName
</replaceable>)
4582 <title>Parameters
</title>
4585 <term><parameter>type
</parameter></term>
4587 <para>Specifies the alarm type. The permissible values are DISPLAY,
4588 COMMAND, EMAIL, AUDIO. These are defined in class
4589 <classname>KAlarmIface
</classname> in
4590 <filename>kalarmiface.h
</filename>.
</para>
4595 <term><parameter>templateName
</parameter></term>
4597 <para>Specifies the name of an alarm template to base the new alarm
4605 <title>Return value
</title>
4606 <para><returnvalue>false
</returnvalue> if
<parameter>type
</parameter>
4607 has an invalid value, or if no template with the name
4608 <parameter>templateName
</parameter> can be found;
4609 <returnvalue>true
</returnvalue> otherwise.
</para>
4614 <title>Description
</title>
4616 <para><function>editNew()
</function> is a
&DBus; call to display the
4617 <link linkend=
"alarm-edit-dlg">Alarm Edit dialog
</link> to edit a new
4618 alarm. If an alarm type is specified as a parameter, a blank dialog is
4619 displayed. Alternatively, if an alarm template name is specified as a
4620 parameter, the dialog is preset with details from the template.
</para>
4627 <sect1 id=
"cmdline-interface">
4628 <title>Command Line Interface
</title>
4630 <para>Command line options are provided to enable other programs to
4631 start up
&kalarm; if it is not already running, in order to trigger or
4632 cancel scheduled alarms, or schedule new alarms. The reason for using
4633 command line options for this purpose is that if
&kalarm; were started
4634 without any command line parameters and then sent
&DBus; requests, it
4635 would start in its default graphical mode, which is clearly undesirable
4636 for an inter-program request.
</para>
4638 <note><para>Programs should first check whether
&kalarm; is already
4639 running; if it is, they should instead use
&DBus; calls to request these
4640 operations.
</para></note>
4642 <para>The command line options for scheduling a new alarm are as
4643 described in the chapter
<link linkend=
"cmdline-operation">Command Line
4644 Operation
</link>. The options for triggering and canceling scheduled
4645 alarms are as follows:
</para>
4647 <note><para>Normal users may also if they wish use these command line
4648 options (assuming that they can supply the necessary parameter
4649 information).
</para></note>
4655 <entry>Option
</entry>
4656 <entry>Description
</entry>
4661 <entry><option>--cancelEvent
<replaceable>eventID
</replaceable></option></entry>
4662 <entry>Cancel the alarm with the specified event ID.
4663 <option>--triggerEvent
</option> cannot be specified with this
4667 <entry><option>--triggerEvent
<replaceable>eventID
</replaceable></option></entry>
4668 <entry>Trigger the alarm with the specified event ID. The action
4669 taken is the same as for the
4670 <link linkend=
"triggerEvent">triggerEvent()
</link> &DBus; call.
4671 <option>--cancelEvent
</option> cannot be specified with this
4678 <para>Examples are:
</para>
4680 <informalexample><screen>
4681 <prompt>%
</prompt> <userinput><command>kalarm
</command> <option>--triggerEvent
<replaceable>&kalarm;-
387486299.702</replaceable></option></userinput>
4682 <prompt>%
</prompt> <userinput><command>kalarm
</command> <option>--cancelEvent
<replaceable>&kalarm;-
388886299.793</replaceable></option></userinput>
4691 <title>Questions and Answers
</title>
4694 &updating.documentation;
4696 <qandaset id=
"faqlist">
4699 <para>What configuration files does
&kalarm; use?
</para>
4702 <para><filename>$KDEHOME/share/config/kalarmrc
</filename>
4703 holds your
&kalarm; preferences.
</para>
4705 <filename>$KDEHOME/share/config/kresources/alarms/stdrc
</filename>
4706 holds your alarm calendar configuration.
</para>
4708 <para>($
<envar>KDEHOME
</envar> is usually
4709 <filename class=
"directory">˜/.kde
</filename> or similar.)
</para>
4715 <para>Where does
&kalarm; store its alarms?
</para>
4719 <para>The names of the calendar files which
&kalarm; creates the first
4720 time it is run are as follows (but these may be overridden by entries
4721 in the
<parameter>General
</parameter> section of
&kalarm;'s preferences
4726 <para><filename>$KDEHOME/share/apps/kalarm/calendar.ics
</filename>
4727 holds active alarms (overridable by the
4728 <parameter>Calendar
</parameter> entry).
</para>
4732 <para><filename>$KDEHOME/share/apps/kalarm/expired.ics
</filename>
4733 holds archived alarms (overridable by the
4734 <parameter>ExpiredCalendar
</parameter> entry).
</para>
4738 <para><filename>$KDEHOME/share/apps/kalarm/template.ics
</filename>
4739 holds alarm templates (overridable by the
4740 <parameter>TemplateCalendar
</parameter> entry).
</para>
4744 <para>You can find out which calendar files are currently in use by
4745 viewing each calendar's details in the alarm calendars list. The file
4746 names are stored in the alarm calendar configuration file.
</para>
4748 <para>Details of alarms currently being displayed are stored in the
4750 <filename>$KDEHOME/share/apps/kalarm/displaying.ics
</filename>.
</para>
4756 <para>What format are alarms stored in?
</para>
4759 <para>The calendar files in which
&kalarm; stores its alarms are text
4760 files whose format is defined by the document
4761 <ulink url=
"http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445 -
4762 Internet Calendaring and Scheduling Core Object Specification
4763 (iCalendar)
</ulink>. This is the standard format used by all kdepim
4764 applications.
&kalarm; uses certain non-standard properties, in
4765 conformance with RFC2445. These are documented in the
4766 <filename>DESIGN.html
</filename> file which is distributed with
4773 <para>What is the program
<application>kalarmautostart
</application>?
</para>
4776 <para><application>kalarmautostart
</application> is a little helper
4777 program whose function is to autostart
&kalarm; at login.
</para>
4779 <para>&kalarm; is usually restored by the session manager at login
4780 (to redisplay its windows in the same state as they were when you
4781 logged off). But if it was not running when you logged off, it would
4782 not be started by the session manager and therefore needs to be
4783 autostarted. The problem is that when an application is both session
4784 managed and autostarted, there is no guarantee as to which will occur
4785 first. If autostart gets in first, it will prevent the session manager
4786 from restoring the application's state.
</para>
4788 <para>To avoid this problem,
4789 <application>kalarmautostart
</application> is autostarted at login
4790 instead of
&kalarm;. All it does is wait for a short time (to ensure
4791 that the session manager has time to do its job) before starting
4792 &kalarm;, at which point it terminates.
</para>
4800 <chapter id=
"credits">
4802 <title>Credits and License
</title>
4808 Program copyright
2001,
2002,
2003,
2004,
2005,
2006,
2007,
2008,
2009,
2010,
2011 &David.Jarvie; &David.Jarvie.mail;
4812 Documentation copyright
2001,
2002,
2003,
2004,
2005,
2006,
2007,
2008,
2009,
2010,
2011 &David.Jarvie; &David.Jarvie.mail;
4815 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
4817 &underFDL; <!-- FDL: do not remove -->
4819 &underGPL; <!-- GPL License -->
4821 <para>Thanks go to the author of the
&kde; 1 KAlarm application,
4822 Stefan Nikolaus
<email>stefan.nikolaus@stuco.uni-oldenburg.de
</email>,
4823 who kindly agreed to allow the name
&kalarm; to be used by this
4824 application, which has been available for
&kde; 2 onwards.
4829 <appendix id=
"installation">
4830 <title>Installation
</title>
4832 <sect1 id=
"getting-kalarm">
4833 <title>How to Obtain
&kalarm;</title>
4835 &install.intro.documentation;
4837 <para>&kalarm; is also available as a standalone package for
&kde; 4,
4838 as well as older versions for
&kde; 3 and
&kde; 2, from
4839 <ulink url=
"http://www.astrojar.org.uk/kalarm">http://www.astrojar.org.uk/kalarm
</ulink>
4844 <sect1 id=
"requirements">
4845 <title>Requirements
</title>
4847 <para>&kalarm; requires the standard
&kde; libraries to be installed
4848 (the
<filename>kdelibs
</filename> and
<filename>kdepimlibs
</filename>
4849 packages), plus the
<filename>kdebase/runtime
</filename> package. To
4850 compile from source, you also need the relevant library development
4851 packages, and the
&Qt; development package.
</para>
4853 <para>The following optional packages enhance
&kalarm; at runtime if
4854 they are installed:
</para>
4857 <listitem><para>&jovie; (from kdeaccessibility package): if installed
4858 and configured, together with a compatible speech synthesizer package,
4859 it allows
&kalarm; to speak alarm messages when they are
4864 <para>You can find a list of changes in the
4865 <filename>Changelog
</filename> file, or at
<ulink
4866 url=
"http://www.astrojar.org.uk/kalarm">http://www.astrojar.org.uk/kalarm
</ulink>.
</para>
4869 <sect1 id=
"compilation">
4870 <title>Compilation and Installation
</title>
4872 <para>If you cannot obtain a suitable precompiled binary package, you
4873 need to compile
&kalarm; yourself from source files. Get the source
4874 package file
<filename>kdepim-x.x.tar.bz2
</filename> or
4875 <filename>kalarm-x.x.tar.bz2
</filename> (or similar), depending on
4876 whether you want to install
&package; or just
&kalarm;. Unpack it in a
4877 new folder using a command similar to
4878 <userinput><command>tar
</command> <option>xvfj
4879 <replaceable>package.tar.bz2
</replaceable></option></userinput>, and
4880 change to the folder which has been created.
</para>
4882 &install.compile.documentation;
4884 <warning><para>If you install
&kalarm; into a folder different from
4885 where
&kde; is installed, it will not run correctly unless you make
4886 its location known to
&kde;. To do this, you must prefix the
4887 <envar>KDEDIRS
</envar> environment variable with
&kalarm;'s location,
4888 each time before you start
&kde;.
</para>
4890 <para>For example, if
&kde; is installed in
4891 <literal>/opt/kde
</literal>,
<envar>KDEDIRS
</envar> might normally
4892 be set to
<literal>/etc/opt/kde:/opt/kde
</literal>. If you install
4893 &kalarm; into
<literal>/usr/local
</literal>, you would need to set
4894 <envar>KDEDIRS
</envar> to
4895 <literal>/usr/local:/etc/opt/kde:/opt/kde
</literal> before starting
4896 &kde;.
</para></warning>
4898 <para>The standalone version of
&kalarm; has a special configuration
4899 option which allows you to select which languages documentation is to
4900 be installed for by specifying a language code, or a list of language
4901 codes, as a parameter to
<command>./configure
</command>. By default,
4902 documentation in all available languages is installed. A list of
4903 documentation languages included in the package, together with their
4904 codes, is in the
<filename>DOC-LANGUAGES
</filename> file. For example,
4905 to install only French and British English documentation:
</para>
4907 <para><userinput><command>./configure
</command> --enable-doc-language=
<replaceable>"fr en_GB"</replaceable></userinput></para>
4909 <para>Note that this option has no effect on which user interface
4910 translations are installed.
</para>
4914 <sect1 id=
"configuration">
4915 <title>Configuration
</title>
4917 <para>No special configuration is required to set up
&kalarm; to run
4918 on the
&kde; desktop. Once you have run
&kalarm; for the first time,
4919 it will start every time you log in, in order to monitor scheduled
4922 <para>To run
&kalarm; on a non-
&kde; desktop, the main requirement is
4923 to ensure that
&kalarm; is run automatically whenever you log in. More
4924 detailed instructions are contained in the
4925 <filename>INSTALL
</filename> file which is distributed with
4932 &documentation.index;
4937 sgml-minimize-attributes:nil
4938 sgml-general-insert-case:lower
4940 sgml-indent-data:nil