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