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