Warning, /pim/kalarm/doc/index.docbook is written in an unsupported language. File is not indexed.
0001 <?xml version="1.0" ?> 0002 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ 0003 <!ENTITY % addindex "IGNORE"> 0004 <!ENTITY % English "INCLUDE"><!-- change language only here --> 0005 ]> 0006 0007 <!-- The language must NOT be changed here. --> 0008 0009 <book id="kalarm" lang="&language;"> 0010 0011 <bookinfo id="kalarminfo"> 0012 <title>The &kalarm; Handbook</title> 0013 0014 <authorgroup> 0015 <author> 0016 <firstname>David</firstname> 0017 <surname>Jarvie</surname> 0018 <affiliation> 0019 <address>&David.Jarvie.mail;</address> 0020 </affiliation> 0021 </author> 0022 0023 <othercredit role="developer"> 0024 <firstname>David</firstname> 0025 <surname>Jarvie</surname> 0026 <affiliation><address>&David.Jarvie.mail;</address></affiliation> 0027 <contrib>Developer</contrib> 0028 </othercredit> 0029 0030 <!-- TRANS:ROLES_OF_TRANSLATORS --> 0031 </authorgroup> 0032 0033 <copyright> 0034 <year>2001</year><year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year><year>2007</year><year>2008</year><year>2009</year><year>2010</year><year>2011</year><year>2012</year><year>2013</year><year>2016</year><year>2018</year><year>2019</year><year>2020</year><year>2021</year><year>2022</year><year>2023</year> 0035 <holder>&David.Jarvie;</holder> 0036 </copyright> 0037 0038 <legalnotice>&FDLNotice;</legalnotice> 0039 0040 <!-- Don't change format of date and version of the documentation --> 0041 0042 <date>2023-9-20</date> 0043 <releaseinfo>3.7.0 (KDE Gear 24.02)</releaseinfo> 0044 0045 <abstract> 0046 <para>&kalarm; is a personal alarm message, command and email scheduler by &kde;.</para> 0047 </abstract> 0048 0049 0050 <keywordset> 0051 <keyword>KDE</keyword> 0052 <keyword>kdepim</keyword> 0053 <keyword>kalarm</keyword> 0054 <keyword>alarm</keyword> 0055 <keyword>reminder</keyword> 0056 <keyword>scheduler</keyword> 0057 </keywordset> 0058 0059 </bookinfo> 0060 0061 0062 <chapter id="introduction"> 0063 <title>Introduction</title> 0064 0065 <para>&kalarm; lets you schedule the display of personal alarm 0066 messages, the playing of sound files, the execution of commands and 0067 the sending of emails.</para> 0068 0069 <para>&kalarm; displays the list of pending alarms, showing their 0070 times and details. You can create new alarms, or you can select 0071 existing alarms for modification or deletion. You can also optionally 0072 view expired alarms.</para> 0073 0074 <para>When configuring an alarm, you can choose whether it should 0075 repeat, and whether the alarm should be canceled if it cannot be 0076 triggered at its scheduled time. For display alarms, you can type in 0077 a message text, specify a text or image file to display, or specify a 0078 command whose output should be displayed. You can also choose the 0079 color of the alarm message, and whether to play a sound or speak the 0080 message.</para> 0081 0082 <para>Alarms may also be scheduled from the command line, or via &DBus; 0083 calls from programs.</para> 0084 0085 <para>When an alarm message is due, it is displayed on each 0086 desktop to ensure that you don't miss it. The message window shows the 0087 time for which the alarm was scheduled. It usually has a defer option 0088 to ask for the alarm to be displayed again later. An example of an 0089 alarm message:</para> 0090 0091 <screenshot> 0092 <screeninfo>Screenshot of the &kalarm; message window</screeninfo> 0093 <mediaobject> 0094 <imageobject> 0095 <imagedata fileref="alarmmessage.png" format="PNG"/> 0096 </imageobject> 0097 <textobject> 0098 <phrase>Alarm message</phrase> 0099 </textobject> 0100 </mediaobject> 0101 </screenshot> 0102 0103 <para>Optionally, an alarm message may be displayed as a notification 0104 instead of in a window.</para> 0105 0106 <para>When the alarm specifies a command to execute or an email to 0107 send, &kalarm; displays nothing.</para> 0108 0109 <para>&kalarm; usually shows an icon in the system tray, although this 0110 can be hidden if desired.</para> 0111 0112 </chapter> 0113 0114 <chapter id="using-kalarm"> 0115 <title>Using &kalarm;</title> 0116 0117 <para>When it is run with no command line parameters, &kalarm; starts 0118 in graphical mode, and displays the current list of outstanding 0119 alarms.</para> 0120 0121 <tip><para>All spin boxes in &kalarm; have an acceleration facility. 0122 To make the value change by larger steps, hold down the 0123 &Shift; key while you click on the spin arrow 0124 buttons.</para> 0125 0126 <mediaobject> 0127 <imageobject> 0128 <imagedata fileref="spinbox.png" format="PNG"/> 0129 </imageobject> 0130 </mediaobject> 0131 </tip> 0132 0133 <sect1 id="alarm-types"> 0134 <title>Alarm Types</title> 0135 0136 <para>The basic functions available from the different alarm types 0137 which &kalarm; provides are:</para> 0138 0139 <itemizedlist> 0140 <listitem> 0141 <para>Display alarms display either a text message which you type in, 0142 or the contents of a text or image file, or the textual output from a 0143 command which is run when the alarm triggers. In addition to 0144 displaying one of these items, they can also play audio files, have 0145 their text spoken, or emit a simple beep. You can also specify 0146 commands to be executed before and after the alarm message is 0147 displayed.</para> 0148 </listitem> 0149 0150 <listitem> 0151 <para>Command alarms execute either a command or a shell script which 0152 you can type in. Nothing is displayed unless an error occurs.</para> 0153 </listitem> 0154 0155 <listitem> 0156 <para>Email alarms send a email. Nothing is displayed unless an error 0157 occurs.</para> 0158 </listitem> 0159 0160 <listitem> 0161 <para>Audio alarms play an audio file. Nothing is displayed unless an 0162 error occurs.</para> 0163 </listitem> 0164 </itemizedlist> 0165 0166 <sect2 id="errors"> 0167 <title>Error Handling</title> 0168 0169 <para>If an error occurs when an alarm triggers, an error message will 0170 be displayed (unless you have previously specified not to show that 0171 type of message again).</para> 0172 0173 <para>If an execution error occurred the last time a command alarm 0174 triggered, a white on red exclamation mark is shown in the message 0175 color column. Details of the error are displayed in a tooltip if you 0176 position the cursor over that line in the alarm list. The same error 0177 indications are shown for display alarms if an execution error 0178 occurred for a pre- or post-alarm command specified in the Special 0179 Actions dialog, except that the color column is not changed to a red 0180 background.</para> 0181 0182 </sect2> 0183 </sect1> 0184 0185 <sect1 id="alarm-list"> 0186 <title>Alarm List</title> 0187 0188 <para>The main &kalarm; window displays the current list of pending 0189 alarms, showing their times, repetition intervals, colors, names, and 0190 message texts, names of files to play or display, commands to execute 0191 or email subjects. (For a recurring alarm, the time shown is its next 0192 scheduled trigger time. For an alarm with a reminder, the time shown 0193 is the time of the alarm proper, not the reminder time.) An icon at 0194 the left of each alarm text/file/command/email subject indicates the 0195 type of alarm.</para> 0196 0197 <para>Note that the <guilabel>Name</guilabel> column only exists if 0198 the use of alarm names is enabled in the 0199 <link linkend="preferences-general">General</link> tab of the 0200 Configuration dialog.</para> 0201 0202 <screenshot> 0203 <screeninfo>Screenshot of the &kalarm; main window</screeninfo> 0204 <mediaobject> 0205 <imageobject> 0206 <imagedata fileref="mainwindow.png" format="PNG"/> 0207 </imageobject> 0208 <textobject> 0209 <phrase>Main window</phrase> 0210 </textobject> 0211 </mediaobject> 0212 </screenshot> 0213 0214 <para>For a repeated alarm, the list shows its next scheduled trigger 0215 time and its basic repetition interval (⪚ <quote>1 Day</quote> for 0216 a daily recurrence, <quote>3 Weeks</quote> for a recurrence which 0217 triggers on Monday and Wednesday every third week, 0218 <quote>Login</quote> for a repeat-at-login alarm).</para> 0219 0220 <para>If an execution error occurred the last time a command alarm 0221 triggered, or the last time a display alarm's pre- or post-alarm 0222 command was executed, an error indication is shown in the color 0223 column, as described in <link linkend="errors">Error Handling</link> 0224 above.</para> 0225 0226 <sect2 id="listappear"> 0227 <title>Changing the Alarm List Appearance</title> 0228 0229 <para>The alarms may be ordered by date/time, repeat interval, color, 0230 type, name or text by clicking on the titlebar for the appropriate 0231 column. To reverse the sort order, click the column titlebar 0232 again.</para> 0233 0234 <para>You can optionally show the remaining time until each alarm is 0235 due, together with, or instead of, the alarm's scheduled time.</para> 0236 0237 <para>You can select which columns to display or hide by 0238 <mousebutton>Right</mousebutton> clicking on the column headings and 0239 using the context menu to set the columns to show. But note that at 0240 least one of the <guilabel>Name</guilabel> or 0241 <guilabel>Message, File or Command</guilabel> columns, and at least 0242 one of the <guilabel>Time</guilabel> or <guilabel>Time To</guilabel> 0243 columns, are always shown.</para> 0244 0245 <para>If you use multiple alarm calendars, you can color code alarms 0246 according to which calendar they belong to, by selecting a different 0247 background color for each calendar (see 0248 <link linkend="using-calendars">Using Calendars</link>).</para> 0249 0250 </sect2> 0251 0252 <sect2 id="expired"> 0253 <title>Archived Alarms</title> 0254 0255 <para>By default, &kalarm; archives alarms for a limited period once 0256 they have expired or been deleted. (But note that alarms which you 0257 delete are stored only if they have already triggered at least once.) 0258 You can control whether &kalarm; archives expired alarms, and for how 0259 long, in the 0260 <link linkend="preferences-storage">Configuration dialog</link>.</para> 0261 0262 <para>Archived alarms may be shown in the alarm list by selecting 0263 <menuchoice><guimenu>View</guimenu><guimenuitem>Show Archived 0264 Alarms</guimenuitem></menuchoice>. To hide them again, deselect 0265 <menuchoice><guimenu>View</guimenu><guimenuitem>Show Archived 0266 Alarms</guimenuitem></menuchoice>.</para> 0267 0268 </sect2> 0269 0270 <sect2 id="datepicker"> 0271 <title>Filtering the Alarm List by Date</title> 0272 0273 <para>You can restrict the alarm list to show only alarms which are 0274 scheduled to occur on a selected date. This is achieved by means of 0275 the alarm date selector, which can be displayed or hidden by 0276 <menuchoice><guimenu>View</guimenu> 0277 <guimenuitem>Show Date Selector</guimenuitem> 0278 </menuchoice>. Select a date by clicking on it in the date selector, 0279 or deselect it by clicking on it again. The date selector displays a 0280 single month. To display a different month, use the arrow controls in 0281 the date selector, or the mouse wheel.</para> 0282 0283 </sect2> 0284 0285 <sect2 id="search"> 0286 <title>Searching the Alarm List</title> 0287 0288 <para>You can search through the alarm list to find alarms containing 0289 a search text. To invoke this, select <menuchoice> 0290 <guimenu>Edit</guimenu><guimenuitem>Find...</guimenuitem></menuchoice>. 0291 In the search dialog, select the alarm types which you wish to search. 0292 To continue searching for more alarms which match, use <menuchoice> 0293 <guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice> 0294 or <menuchoice> 0295 <guimenu>Edit</guimenu><guimenuitem>Find Previous</guimenuitem> 0296 </menuchoice>.</para> 0297 0298 <para>Searching is performed as follows:</para> 0299 0300 <itemizedlist> 0301 <listitem> 0302 <para>Text message alarms: the message text is searched.</para> 0303 </listitem> 0304 0305 <listitem> 0306 <para>File display alarms: the file path/&URL; is searched.</para> 0307 </listitem> 0308 0309 <listitem> 0310 <para>Command alarms: the command line or command script is 0311 searched.</para> 0312 </listitem> 0313 0314 <listitem> 0315 <para>Email alarms: in addition to the subject and body of the email, 0316 the recipients and the URLs of attachments are searched.</para> 0317 </listitem> 0318 0319 <listitem> 0320 <para>Audio alarms: the file path/&URL; is searched.</para> 0321 </listitem> 0322 </itemizedlist> 0323 0324 <note><para>Only alarms currently shown in the alarm list can be 0325 selected for searching. So if you want to search archived alarms, you 0326 must first display them as described in the section above.</para></note> 0327 </sect2> 0328 </sect1> 0329 0330 <sect1 id="create-edit"> 0331 <title>Creating and Manipulating Alarms</title> 0332 0333 <sect2> 0334 <title>Creating a New Alarm</title> 0335 0336 <para>To create a new alarm, do one of the following, and then select 0337 the type of alarm from the list which appears. This displays the 0338 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> through which 0339 you configure the alarm.</para> 0340 0341 <itemizedlist> 0342 <listitem> 0343 <para>Select <menuchoice><guimenu>File</guimenu> 0344 <guimenuitem>New</guimenuitem></menuchoice>.</para> 0345 </listitem> 0346 0347 <listitem> 0348 <para><mousebutton>Right</mousebutton> click on the system tray icon 0349 and choose 0350 <menuchoice><guimenuitem>New Alarm</guimenuitem></menuchoice> 0351 from the context menu.</para> 0352 </listitem> 0353 0354 <listitem> 0355 <para><mousebutton>Right</mousebutton> click in the alarm list and 0356 choose <menuchoice><guimenuitem>New</guimenuitem></menuchoice> from 0357 the context menu.</para> 0358 </listitem> 0359 </itemizedlist> 0360 0361 <para>Alternatively, you can create new alarms preconfigured from 0362 various sources:</para> 0363 0364 <itemizedlist> 0365 <listitem> 0366 <para>To preset the alarm's date in the 0367 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>, 0368 <mousebutton>right</mousebutton> click on the desired date in the alarm 0369 date selector (see <link linkend="datepicker">Filtering the Alarm List 0370 by Date</link>) and select the appropriate alarm type from the context 0371 menu.</para> 0372 </listitem> 0373 0374 <listitem> 0375 <para>To base your new alarm on an alarm template, follow the 0376 instructions in the <link linkend="templates">Alarm Templates</link> 0377 section.</para> 0378 </listitem> 0379 0380 <listitem> 0381 <para>To base your new alarm on an existing one, highlight the existing 0382 alarm in the list and select <menuchoice> 0383 <guimenu>File</guimenu><guimenuitem>Copy</guimenuitem></menuchoice>. 0384 This opens the <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> 0385 already filled in with a copy of the selected alarm's details.</para> 0386 </listitem> 0387 0388 <listitem> 0389 <para>To create a new alarm which displays an existing email message, 0390 drag the email from &kmail; onto &kalarm;'s main window. Then select 0391 the <guilabel>Display Alarm</guilabel> option. This opens the 0392 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> with the 0393 entire email message (including sender, recipient, &etc;) as the alarm 0394 text.</para> 0395 </listitem> 0396 0397 <listitem> 0398 <para>To create a new email alarm to send a copy of an existing email 0399 message, drag the email from &kmail; onto &kalarm;'s main window. Then 0400 select the <guilabel>Email Alarm</guilabel> option. The 0401 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> is preset with 0402 the entire email message except sender.</para> 0403 </listitem> 0404 0405 <listitem> 0406 <para>To create a new alarm which displays a summary of an existing 0407 to-do, drag the to-do from &korganizer; or other application onto 0408 &kalarm;'s main window. This opens the 0409 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> with the 0410 to-do contents as the alarm text.</para> 0411 </listitem> 0412 0413 <listitem> 0414 <para>To create a new command alarm, drag the text of a script 0415 starting with <quote>#!</quote> onto &kalarm;'s main window. Then 0416 select the <guilabel>Command Alarm</guilabel> option. This opens the 0417 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> preset with 0418 the script text.</para> 0419 </listitem> 0420 0421 <listitem> 0422 <para>To create a file display alarm, drag a text or image file &URL; 0423 onto &kalarm;'s main window. This opens the 0424 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> and sets the 0425 file name.</para> 0426 </listitem> 0427 0428 <listitem> 0429 <para>To create an audio alarm, drag an audio file &URL; onto 0430 &kalarm;'s main window. This opens the 0431 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> and sets the 0432 file name.</para> 0433 </listitem> 0434 0435 <listitem> 0436 <para>To create a text message alarm, drag any piece of text onto 0437 &kalarm;'s main window. If prompted, select the 0438 <guilabel>Display Alarm</guilabel> option. This opens the 0439 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> preset with 0440 the alarm text.</para> 0441 </listitem> 0442 0443 <listitem> 0444 <para>You can automatically create birthday alarms for people in 0445 &kaddressbook; as described in <link linkend="birthdays">Importing 0446 Birthdays from &kaddressbook;</link>.</para> 0447 </listitem> 0448 0449 </itemizedlist> 0450 0451 </sect2> 0452 0453 <sect2 id="edit-alarm"> 0454 <title>Modifying an Existing Alarm</title> 0455 0456 <para>To modify an existing pending alarm (expired alarms cannot be 0457 amended), do one of the following:</para> 0458 0459 <itemizedlist> 0460 <listitem> 0461 <para>Double click on its entry in the alarm list.</para> 0462 </listitem> 0463 0464 <listitem> 0465 <para>Select it by clicking on its entry in the alarm list. Then 0466 choose <menuchoice><guimenu>Edit</guimenu> 0467 <guimenuitem>Edit</guimenuitem></menuchoice>.</para> 0468 </listitem> 0469 0470 <listitem> 0471 <para><mousebutton>Right</mousebutton> click on its entry in the alarm 0472 list and choose 0473 <menuchoice><guimenuitem>Edit</guimenuitem></menuchoice> from the 0474 context menu.</para> 0475 </listitem> 0476 </itemizedlist> 0477 0478 <para>This displays the <link linkend="alarm-edit-dlg">Alarm Edit 0479 dialog</link>.</para> 0480 0481 </sect2> 0482 0483 <sect2> 0484 <title>Deleting/Reactivating an Alarm</title> 0485 0486 <para>To delete existing alarms, select one or more by clicking on 0487 their entries in the alarm list. Then do one of the following:</para> 0488 0489 <itemizedlist> 0490 <listitem> 0491 <para>Choose <menuchoice> 0492 <guimenu>Edit</guimenu><guimenuitem>Delete</guimenuitem> 0493 </menuchoice>.</para> 0494 </listitem> 0495 <listitem> 0496 <para><mousebutton>Right</mousebutton> click on the selected entries 0497 and choose 0498 <menuchoice><guimenuitem>Delete</guimenuitem></menuchoice> 0499 from the context menu.</para> 0500 </listitem> 0501 <listitem> 0502 <para>To delete them without a confirmation prompt, type 0503 &Shift;-<keycap>Delete</keycap>.</para> 0504 </listitem> 0505 </itemizedlist> 0506 0507 <para>When you delete an active alarm, it is archived, provided that 0508 it has triggered at least once before being deleted, and provided that 0509 expired alarms are archived at all. (Use the 0510 <link linkend="preferences-storage">Configuration dialog</link> to 0511 control whether and for how long archived alarms are stored.) When you 0512 delete an archived alarm, or an active alarm which has not yet 0513 triggered, it is removed permanently.</para> 0514 0515 <para>You can reactivate a deleted alarm from the archived alarms list, 0516 provided that it has not yet expired. To do this, first display 0517 archived alarms, as described in 0518 <link linkend="expired">Archived Alarms</link>. Then:</para> 0519 0520 <itemizedlist> 0521 <listitem> 0522 <para>Select one or more appropriate archived alarms by clicking on 0523 their entries in the alarm list. Then choose <menuchoice> 0524 <guimenu>Actions</guimenu><guimenuitem>Reactivate</guimenuitem> 0525 </menuchoice>.</para> 0526 </listitem> 0527 <listitem> 0528 <para><mousebutton>Right</mousebutton> click on the desired entries in 0529 the archived alarm list and choose 0530 <menuchoice><guimenuitem>Reactivate</guimenuitem></menuchoice> 0531 from the context menu.</para> 0532 </listitem> 0533 </itemizedlist> 0534 0535 </sect2> 0536 0537 <sect2> 0538 <title>Enabling/Disabling an Alarm</title> 0539 0540 <para>See <link linkend="enable-disable">Enabling and Disabling Alarms</link> 0541 for how to enable and disable alarms, either individually or as a whole.</para> 0542 0543 </sect2> 0544 0545 <sect2> 0546 <title>Setting an Alarm to Wake from Suspend</title> 0547 0548 <para>See <link linkend="wake-suspend">Wake From Suspend</link> for 0549 how to configure an alarm to wake up your system from suspension or 0550 hibernation.</para> 0551 0552 </sect2> 0553 0554 <sect2> 0555 <title>Acknowledging an Alarm</title> 0556 0557 <para>See <link linkend="message-display">Alarm Message Display</link> 0558 for how to acknowledge alarms.</para> 0559 0560 </sect2> 0561 0562 <sect2 id="templates"> 0563 <title>Alarm Templates</title> 0564 0565 <para>If you frequently want to set up similar alarms, you can create 0566 an alarm template to avoid having to enter all the details from 0567 scratch each time. A template can contain all the details which an 0568 alarm can contain, apart from the start date.</para> 0569 0570 <para>As an example, you may regularly want to set an 0571 alarm to remind you about a television program whose time varies 0572 from week to week. The template would contain all the alarm details 0573 (message text, whether to play a sound, &etc;) except for the time and 0574 date. Now, to create the alarm, all you need to do is open the 0575 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> with that 0576 template and then enter the time and date.</para> 0577 0578 <para>To create an alarm based on a template, open the 0579 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> preset with 0580 the template details:</para> 0581 0582 <itemizedlist> 0583 <listitem> 0584 <para>Select the <menuchoice> 0585 <guimenu>File</guimenu><guimenuitem>New</guimenuitem> 0586 <guimenuitem>New Alarm From Template</guimenuitem> 0587 </menuchoice> menu item, and then select the desired template.</para> 0588 </listitem> 0589 0590 <listitem> 0591 <para><mousebutton>Right</mousebutton> click on the system tray icon 0592 and choose 0593 <menuchoice><guimenuitem>New Alarm</guimenuitem> 0594 <guimenuitem>New Alarm From Template</guimenuitem></menuchoice> 0595 from the context menu. Then select the desired template.</para> 0596 </listitem> 0597 0598 <listitem> 0599 <para>Open the <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> 0600 in the usual way, and click the 0601 <guibutton>Load Template...</guibutton> button to select a template to 0602 preset the dialog with.</para> 0603 </listitem> 0604 </itemizedlist> 0605 0606 <sect3> 0607 <title>Configuring Templates</title> 0608 0609 <para>You can create, modify or delete templates using the Alarm 0610 Templates dialog, or you can create a new alarm template based on an 0611 existing alarm.</para> 0612 0613 <para>To create a new alarm template, do one of the following:</para> 0614 0615 <itemizedlist> 0616 <listitem> 0617 <para>Display the Alarm Templates dialog by selecting the <menuchoice> 0618 <guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem> 0619 </menuchoice> menu item, clicking <guibutton>New</guibutton>, and 0620 choosing the alarm type from the list which appears. This displays a 0621 blank Template Edit dialog.</para> 0622 </listitem> 0623 0624 <listitem> 0625 <para>Display the Alarm Templates dialog by selecting the <menuchoice> 0626 <guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem> 0627 </menuchoice> menu item, select an existing template from the list and 0628 click <guibutton>Copy</guibutton>. This opens the Template Edit dialog 0629 already filled in with a copy of the existing template's 0630 details.</para> 0631 </listitem> 0632 0633 <listitem> 0634 <para>Highlight an alarm in the alarm list and select <menuchoice> 0635 <guimenu>File</guimenu><guimenuitem>Create Template...</guimenuitem> 0636 </menuchoice>. This opens the Template Edit dialog already filled in 0637 with a copy of the selected alarm's details.</para> 0638 </listitem> 0639 </itemizedlist> 0640 0641 <para>To modify an existing template, display the Alarm Templates 0642 dialog by selecting the <menuchoice> 0643 <guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem> 0644 </menuchoice> menu item and click <guibutton>Edit</guibutton>. This 0645 displays the Template Edit dialog which is described below.</para> 0646 0647 <para>To delete existing templates, display the Alarm Templates 0648 dialog by selecting the <menuchoice> 0649 <guimenu>File</guimenu><guimenuitem>Templates...</guimenuitem> 0650 </menuchoice> menu item, select one or more templates and click 0651 <guibutton>Delete</guibutton>. A confirmation prompt is issued to 0652 prevent accidental deletions.</para> 0653 0654 </sect3> 0655 0656 <sect3> 0657 <title>Template Edit Dialog</title> 0658 0659 <para>The Template Edit dialog is similar to the 0660 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>. The 0661 following controls are different:</para> 0662 0663 <itemizedlist> 0664 <listitem> 0665 <para>Enter the template's name in <guilabel>Template name</guilabel>. 0666 It is the template's name which is displayed in template selection 0667 lists, so it is best to choose a name which will remind you of its 0668 function. Each template's name must be unique.</para> 0669 </listitem> 0670 0671 <listitem> 0672 <para>In the <guilabel>Time</guilabel> group box, select one of:</para> 0673 0674 <itemizedlist> 0675 <listitem> 0676 <para><guilabel>Default time</guilabel> if you do not wish to specify 0677 any trigger time. Alarms based on this template will initially 0678 use the normal default trigger time for new alarms.</para> 0679 </listitem> 0680 0681 <listitem> 0682 <para>Check <guilabel>Time</guilabel> to enter a time when the alarm 0683 is to be triggered.</para> 0684 </listitem> 0685 0686 <listitem> 0687 <para>Check <guilabel>Date only</guilabel> to specify that the alarm 0688 should only have a date, not a time.</para> 0689 </listitem> 0690 0691 <listitem> 0692 <para>Check <guilabel>Time from now</guilabel> to enter how long (in 0693 hours and minutes) after the alarm is created, that it should be 0694 triggered.</para> 0695 </listitem> 0696 </itemizedlist> 0697 </listitem> 0698 0699 <listitem> 0700 <para>In the <guilabel>Recurrence Rule</guilabel> group box in the 0701 <guilabel>Recurrence</guilabel> tab, no day or month need be selected 0702 for weekly or yearly recurrences, respectively.</para> 0703 </listitem> 0704 </itemizedlist> 0705 0706 </sect3> 0707 0708 </sect2> 0709 0710 <sect2 id="calendars"> 0711 <title>Alarm Calendars</title> 0712 0713 <para>If you only use one computer and work independently, it may not 0714 matter to you where &kalarm; stores its alarms. But if you need to 0715 access alarms on more than one computer, or in more than one location 0716 on your local computer, you can define <quote>alarm calendars</quote> 0717 to tell &kalarm; to use other alarm calendars additional to, or in 0718 place of, its default ones.</para> 0719 0720 <para>You can view and manipulate calendars via the calendar list, 0721 which can be displayed alongside the alarm list in &kalarm;'s main 0722 window. Alarms from all alarm calendars are shown merged together in 0723 the alarm list. When you save a new alarm, you can set a configuration 0724 option to determine whether it is automatically saved into the default 0725 calendar, or whether you will be prompted to choose a calendar. When 0726 you edit an existing alarm, it is automatically saved back into its 0727 original alarm calendar.</para> 0728 0729 <screenshot> 0730 <screeninfo>Screenshot of the &kalarm; main window, showing the 0731 calendar list</screeninfo> 0732 <mediaobject> 0733 <imageobject> 0734 <imagedata fileref="mainwindow-calendars.png" format="PNG"/> 0735 </imageobject> 0736 <textobject> 0737 <phrase>Main window showing the calendar list</phrase> 0738 </textobject> 0739 </mediaobject> 0740 </screenshot> 0741 0742 <sect3> 0743 <title>Calendar Types and Options</title> 0744 0745 <para>Alarm calendars are categorized by alarm type and storage type. 0746 They can be disabled, set read-only, or made the default calendar for 0747 their alarm type.</para> 0748 0749 <variablelist> 0750 <varlistentry> 0751 <term>Alarm type</term> 0752 <listitem> 0753 <para>The three alarm entity types – active alarms, archived 0754 alarms and alarm templates – 0755 are stored in separate alarm calendars. &kalarm; therefore has three 0756 standard default calendars, one for each type (see 0757 <link linkend="faq">Questions and Answers</link> for details), which 0758 you can change if you wish.</para> 0759 </listitem> 0760 </varlistentry> 0761 0762 <varlistentry> 0763 <term>Storage type</term> 0764 <listitem> 0765 <!--FIXME not in kf5? 0766 <para>&kalarm; handles two alarm calendar storage 0767 types:</para> 0768 --> 0769 0770 <itemizedlist> 0771 <listitem><para>Local file: Alarms are stored in a single local file 0772 in iCalendar format. &kalarm; uses local file calendars by default 0773 (see <link linkend="faq">Questions and Answers</link> for details). 0774 <quote>Local files</quote>, in addition to files on the local 0775 computer, can include alarm calendars on the local network as long as 0776 their location can be represented by a path name starting with 0777 <literal>/</literal>.</para> 0778 </listitem> 0779 <!--FIXME not in kf5? 0780 <listitem><para>Remote file: Alarms are stored in a single remote 0781 file in iCalendar format. This storage method allows you to access 0782 your alarm data remotely no matter where you are, or enables alarm 0783 calendars to be viewed by other people. When using remote files, 0784 &kalarm; works with a local cache of the data.</para> 0785 0786 <warning><para>If a remote alarm calendar is shared between users, 0787 changes made by one person may not be automatically made available to 0788 another user, or there could be a time delay before the other user 0789 sees it. So one user could make a change which is then overwritten by 0790 another user without either person noticing what has happened. The 0791 technical reason for this is that a change made by person A will only 0792 be available to person B after person A's cached copy has first been 0793 saved to the remote file, and then person B's cached copy 0794 of the remote file has been reloaded. When and if the calendar is 0795 saved and reloaded depends on the calendar configuration parameters 0796 which each user has set for that alarm calendar.</para> 0797 0798 <para>Ways to avoid this problem include adjusting the calendar save 0799 and reload configuration parameters, or adopting a policy that users 0800 other than the alarm calendar's owner should open it in read-only 0801 mode.</para></warning> 0802 </listitem> 0803 --> 0804 </itemizedlist> 0805 </listitem> 0806 </varlistentry> 0807 0808 <varlistentry> 0809 <term>Enabled/disabled status</term> 0810 <listitem> 0811 <para>Disabling a calendar has the same 0812 effect as removing it, except that it still appears in the calendar 0813 list for easy re-enabling. When disabled, its alarms are ignored and 0814 do not appear in the alarm list or list of templates. When it is 0815 re-enabled, its alarms are once again shown and, if it is an active 0816 alarm calendar, made active.</para> 0817 </listitem> 0818 </varlistentry> 0819 0820 <varlistentry> 0821 <term>Read-only status</term> 0822 <listitem> 0823 <para>A read-only calendar's alarms cannot be 0824 changed or added to. So you cannot edit its alarms, or save new alarms 0825 to it. Also, it is not possible to defer its alarms, since to do so 0826 would need the deferral time to be saved into the alarm. After its 0827 alarms trigger, they are not removed from the calendar and archived 0828 until you or another user accesses the calendar in read-write 0829 mode.</para> 0830 0831 <para>You can set the read-only status of a calendar in the calendar 0832 configuration dialog. However, some calendars cannot be made 0833 writeable, for various reasons:</para> 0834 0835 <itemizedlist> 0836 <listitem><para>If a calendar was created by another application, it 0837 would be unsafe to allow &kalarm; to update it, since differences in 0838 data format might make it unusable by the creating application.</para> 0839 </listitem> 0840 0841 <listitem><para>If the calendar was created by a later version of 0842 &kalarm;, data might be lost if your version of &kalarm; updated 0843 it.</para> 0844 </listitem> 0845 0846 <listitem><para>If the calendar was created by a previous version of 0847 &kalarm;, data could be lost or it could be made unusable for the 0848 previous &kalarm; version if your version of &kalarm; updated it. You 0849 will be prompted whether to convert its format so as to make it 0850 writeable, bearing in mind the potential compatibility problems if the 0851 previous &kalarm; version needs to access it again.</para> 0852 </listitem> 0853 0854 <listitem><para>If you do not have permission to write to the 0855 calendar file or folder.</para> 0856 </listitem> 0857 </itemizedlist> 0858 0859 <para>If you need write access to alarms in a calendar which cannot be 0860 made writeable, you can copy its alarms by importing them into a 0861 writeable calendar using the latter calendar's 0862 <menuchoice><guimenuitem>Import...</guimenuitem></menuchoice> context 0863 menu option (see <link linkend="import">Importing Alarms from External 0864 Calendars</link>).</para> 0865 </listitem> 0866 </varlistentry> 0867 0868 <varlistentry> 0869 <term>Default calendar status</term> 0870 <listitem> 0871 <para>One calendar of each alarm type can optionally be made the 0872 default calendar for that alarm type. New alarms are automatically 0873 saved to the default calendar for the appropriate alarm type, unless 0874 you have selected the prompt option for new alarms and templates in the 0875 <link linkend="preferences-storage">Configuration dialog</link>.</para> 0876 </listitem> 0877 </varlistentry> 0878 </variablelist> 0879 0880 </sect3> 0881 0882 <sect3 id="using-calendars"> 0883 <title>Using Calendars</title> 0884 0885 <para>You can view and manipulate calendars via the calendar list, 0886 which can be displayed or hidden by <menuchoice> 0887 <guimenu>View</guimenu><guimenuitem>Show Calendars</guimenuitem> 0888 </menuchoice>. When using the calendar list, first select the alarm 0889 type using the combo box above the list. Then either click on one of 0890 the buttons below the list, or <mousebutton>Right</mousebutton> click 0891 on the appropriate calendar in the list and choose an item from the 0892 context menu. The actions available are:</para> 0893 0894 <variablelist> 0895 <varlistentry> 0896 <term><menuchoice><guimenuitem>Add...</guimenuitem></menuchoice></term> 0897 <listitem> 0898 <para>Add a calendar of the selected type to the list. You are asked 0899 to choose a storage type, following which the calendar configuration 0900 dialog is displayed, where you can enter the location of the calendar 0901 and its characteristics. If there is no existing alarm calendar in 0902 the specified location, a new one will be created.</para> 0903 </listitem> 0904 </varlistentry> 0905 0906 <varlistentry> 0907 <term><menuchoice><guimenuitem>Remove</guimenuitem></menuchoice></term> 0908 <listitem> 0909 <para>Remove the selected calendar from the list. The calendar itself 0910 is left intact; it is simply removed from the list, and may 0911 subsequently be reinstated in the list if desired.</para> 0912 </listitem> 0913 </varlistentry> 0914 0915 <varlistentry> 0916 <term><menuchoice><guimenuitem>Edit...</guimenuitem></menuchoice></term> 0917 <listitem> 0918 <para>Edit the selected calendar. This displays the configuration 0919 dialog for the selected calendar.</para> 0920 </listitem> 0921 </varlistentry> 0922 0923 <varlistentry> 0924 <term><menuchoice><guimenuitem>Reload</guimenuitem></menuchoice></term> 0925 <listitem> 0926 <para>Reload the selected calendar. The calendar is re-read from its 0927 storage location, ensuring that there is no discrepancy between what 0928 &kalarm; displays and the current state of the calendar. If the 0929 calendar is shared with other users, any changes which they have made 0930 will now be seen by &kalarm;.</para> 0931 0932 <warning><para>If you reload a remote calendar, any changes to alarms 0933 which you have made since the calendar was last saved will be lost. 0934 Also, any alarms which have expired since the last save may be 0935 retriggered.</para></warning> 0936 </listitem> 0937 </varlistentry> 0938 0939 <varlistentry> 0940 <term><menuchoice><guimenuitem>Import...</guimenuitem></menuchoice></term> 0941 <listitem> 0942 <para>Import alarms from external calendar files into the selected 0943 calendar. This is described in 0944 <link linkend="import">Importing Alarms from External Calendars</link>. 0945 This option is not available for disabled or read-only 0946 calendars.</para> 0947 </listitem> 0948 </varlistentry> 0949 0950 <varlistentry> 0951 <term><menuchoice><guimenuitem>Export...</guimenuitem></menuchoice></term> 0952 <listitem> 0953 <para>Export all the alarms in the selected calendar to an external calendar 0954 file. This is described in 0955 <link linkend="export">Exporting Alarms to External Calendars</link>. 0956 This option is not available for disabled calendars.</para> 0957 </listitem> 0958 </varlistentry> 0959 0960 <varlistentry> 0961 <term><menuchoice><guimenuitem>Show Details</guimenuitem></menuchoice></term> 0962 <listitem> 0963 <para>Display details about the selected calendar. This shows the 0964 calendar's location, storage type and status information. 0965 </para> 0966 </listitem> 0967 </varlistentry> 0968 0969 <varlistentry> 0970 <term><menuchoice><guimenuitem>Use as Default</guimenuitem></menuchoice></term> 0971 <listitem> 0972 <para>Make the selected calendar the default calendar for the selected 0973 calendar type. This option is not available for disabled or read-only 0974 calendars.</para> 0975 </listitem> 0976 </varlistentry> 0977 0978 <varlistentry> 0979 <term><menuchoice><guimenuitem>Set Color...</guimenuitem></menuchoice></term> 0980 <listitem> 0981 <para>Select a background color for highlighting this calendar's alarms 0982 in the alarm list. This enables you to see at a glance which alarms 0983 belong to a particular calendar.</para> 0984 </listitem> 0985 </varlistentry> 0986 0987 <varlistentry> 0988 <term><menuchoice><guimenuitem>Clear Color</guimenuitem></menuchoice></term> 0989 <listitem> 0990 <para>Clear color highlighting for this calendar's alarms in the alarm 0991 list. The option only appears after <guimenuitem>Set Color</guimenuitem> has 0992 been used on this calendar.</para> 0993 </listitem> 0994 </varlistentry> 0995 0996 </variablelist> 0997 0998 </sect3> 0999 1000 </sect2> 1001 1002 <sect2 id="import"> 1003 <title>Importing Alarms from External Calendars</title> 1004 1005 <para>You can import alarms from other calendar files into &kalarm;. 1006 The import function scans the selected calendar 1007 files for events containing alarms, and copies them (with new unique 1008 IDs) into &kalarm;'s calendar. Events without alarms, and calendar 1009 entries other than events, are ignored. There are two ways to import 1010 alarms:</para> 1011 1012 <itemizedlist> 1013 <listitem> 1014 <para>Use <menuchoice><guimenu>File</guimenu> 1015 <guimenuitem>Import Alarms...</guimenuitem></menuchoice> to import 1016 alarms of all types (active alarms, archived alarms and alarm 1017 templates) from the calendar files.</para> 1018 1019 <para>If you have configured 1020 <link linkend="calendars">alarm calendars</link>, alarms of each type 1021 will be added to the appropriate default calendar, or if you have 1022 selected the prompt option for new alarms and templates in the 1023 <link linkend="preferences-storage">Configuration dialog</link>, you will 1024 be prompted for the calendar to use.</para> 1025 </listitem> 1026 1027 <listitem> 1028 <para><mousebutton>Right</mousebutton> click on a calendar in the 1029 calendar list, and choose 1030 <menuchoice><guimenuitem>Import...</guimenuitem></menuchoice> from the 1031 context menu. This imports alarms of the currently selected type into 1032 that calendar. For example, if the selected calendar type is alarm 1033 templates, alarm templates (and not active alarms or archived alarms) 1034 will be imported.</para> 1035 </listitem> 1036 </itemizedlist> 1037 1038 <warning><para>If you import alarms from calendar files which were 1039 created by applications other than &kalarm;, the alarms may be changed 1040 by the import process – even alarm times may change. This depends 1041 on the data storage conventions used by the other application, and is 1042 unavoidable if those conventions differ from what &kalarm; expects. 1043 Always check imported alarms for unexpected changes, and adjust them 1044 as necessary.</para></warning> 1045 1046 </sect2> 1047 1048 <sect2 id="export"> 1049 <title>Exporting Alarms to External Calendars</title> 1050 1051 <para>You can export alarms from &kalarm; to other calendar files, 1052 either the alarms currently selected in the alarm list, or all the 1053 alarms from an alarm calendar. The methods to do this are given below. 1054 Whichever method is used, you can either create a new calendar file 1055 or append the exported alarms to an existing calendar file. To append 1056 the alarms, check <guilabel>Append to existing file</guilabel> in the 1057 file selection dialog; otherwise, any existing file is 1058 overwritten.</para> 1059 1060 <itemizedlist> 1061 <listitem> 1062 <para>To export the alarms currently selected in the alarm list, 1063 <mousebutton>Right</mousebutton> click on the selection and choose 1064 <menuchoice><guimenuitem>Export...</guimenuitem></menuchoice> from the 1065 context menu, or use <menuchoice><guimenu>File</guimenu> 1066 <guimenuitem>Export Selected Alarms...</guimenuitem></menuchoice> in 1067 the main menu.</para> 1068 </listitem> 1069 1070 <listitem> 1071 <para>To export all the alarms from a calendar, 1072 <mousebutton>Right</mousebutton> click on a calendar in the calendar 1073 list, and choose 1074 <menuchoice><guimenuitem>Export...</guimenuitem></menuchoice> from the 1075 context menu.</para> 1076 </listitem> 1077 </itemizedlist> 1078 1079 </sect2> 1080 1081 <sect2 id="birthdays"> 1082 <title>Importing Birthdays from &kaddressbook;</title> 1083 1084 <note><para>This function is only available if &kalarm;'s 1085 <link linkend="akonadi-plugin">Akonadi plugin</link> is 1086 installed and enabled.</para> 1087 </note> 1088 1089 <para>You can set up display alarms for birthdays stored in 1090 &kaddressbook;, by <menuchoice><guimenu>File</guimenu> 1091 <guimenuitem>Import Birthdays...</guimenuitem></menuchoice>. This 1092 displays a dialog which allows you to select which birthdays to create 1093 alarms for.</para> 1094 1095 <itemizedlist> 1096 <listitem> 1097 <para>In the <guilabel>Alarm Text</guilabel> group box, you can set up 1098 the text to be displayed in the birthday alarm messages. The message 1099 text is created by combining the <guilabel>Prefix</guilabel> text 1100 followed by the person's name followed by the 1101 <guilabel>Suffix</guilabel> text. No spaces are added, so remember to 1102 include any necessary trailing space in <guilabel>Prefix</guilabel> 1103 and leading space in <guilabel>Suffix</guilabel>.</para> 1104 1105 <note><para>If you change the alarm text, the birthday selection list 1106 will be re-evaluated.</para></note> 1107 </listitem> 1108 1109 <listitem> 1110 <para>In the <guilabel>Select Birthdays</guilabel> list, select the 1111 birthdays which you want to create alarms for. Note that the list 1112 shows only those entries in &kaddressbook; which contain a birthday 1113 and which do not already have a birthday alarm in the format currently 1114 defined in the <guilabel>Alarm Text</guilabel> group box.</para> 1115 </listitem> 1116 1117 <listitem> 1118 <para>The remaining controls are the same as for 1119 <guilabel>Text</guilabel> alarms in the 1120 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>.</para> 1121 </listitem> 1122 </itemizedlist> 1123 1124 <para>If you have configured 1125 <link linkend="calendars">alarm calendars</link>, the alarms will be 1126 added to the default active alarm calendar, or if you have selected the 1127 prompt option for new alarms and templates in the 1128 <link linkend="preferences-storage">Configuration dialog</link>, you will 1129 be prompted for the calendar to use.</para> 1130 </sect2> 1131 1132 <sect2 id="undo"> 1133 <title>Undo / Redo</title> 1134 1135 <para>You can undo and redo the most recent changes which you have 1136 made during the current session of &kalarm;. Most actions can be 1137 undone, including creation, edit and deletion of alarms and alarm 1138 templates, and reactivation of alarms. To prevent excessive resources 1139 being used by the undo history, the number of changes stored is 1140 limited to the last 12.</para> 1141 1142 <para>To undo the last change, select <menuchoice> 1143 <guimenu>Edit</guimenu><guimenuitem>Undo</guimenuitem></menuchoice>. 1144 To redo the last change which was undone, select <menuchoice> 1145 <guimenu>Edit</guimenu><guimenuitem>Redo</guimenuitem> 1146 </menuchoice>.</para> 1147 1148 <para>To undo a change other than the last one, click on the 1149 <guibutton>Undo</guibutton> button in the toolbar and hold the mouse 1150 button down. A list of actions will be displayed from which you can 1151 choose the one to undo. If you don't see the action which you are 1152 looking for, remember that you may need to undo more recent changes 1153 first, which the desired change depends on. For example, if you edited 1154 an alarm and then deleted it, you cannot undo the edit until you have 1155 first undone the deletion.</para> 1156 1157 <para>Redoing a change other than the last one can be done in a 1158 similar manner, using the <guibutton>Redo</guibutton> toolbar 1159 button.</para> 1160 1161 </sect2> 1162 </sect1> 1163 1164 <sect1 id="alarm-edit-dlg"> 1165 <title>The Alarm Edit Dialog</title> 1166 1167 <para>The Alarm Edit dialog enables you to view and edit an alarm. 1168 When you first use &kalarm;, a simplified form of the dialog is 1169 displayed, with only a small number of options visible. To see all 1170 options, click the <guibutton>More Options</guibutton> button; to 1171 revert to the simplified dialog, click the 1172 <guibutton>Less Options</guibutton> button. &kalarm; always remembers 1173 your last display choice whenever the Alarm Edit dialog is 1174 redisplayed.</para> 1175 1176 <para>You can configure the default values of many of the settings in 1177 the Alarm Edit dialog using the 1178 <link linkend="preferences-edit">Configuration dialog's Edit tab</link>.</para> 1179 1180 <screenshot> 1181 <screeninfo>Screenshot of the simplified Alarm Edit dialog</screeninfo> 1182 <mediaobject> 1183 <imageobject> 1184 <imagedata fileref="editwindow-simple.png" format="PNG"/> 1185 </imageobject> 1186 <textobject> 1187 <phrase>Simplified Alarm Edit dialog for a display alarm</phrase> 1188 </textobject> 1189 <caption><para>Simplified Alarm Edit dialog for a display alarm</para></caption> 1190 </mediaobject> 1191 </screenshot> 1192 1193 <screenshot> 1194 <screeninfo>Screenshot of the Alarm Edit dialog showing all options</screeninfo> 1195 <mediaobject> 1196 <imageobject> 1197 <imagedata fileref="editwindow.png" format="PNG"/> 1198 </imageobject> 1199 <textobject> 1200 <phrase>Alarm Edit dialog for a display alarm, showing all options</phrase> 1201 </textobject> 1202 <caption><para>Alarm Edit dialog for a display alarm, showing all options</para></caption> 1203 </mediaobject> 1204 </screenshot> 1205 1206 <sect2> 1207 <title>Alarm Name</title> 1208 1209 <para>You can give a name to the alarm in the 1210 <guilabel>Alarm name</guilabel> field. This is a convenience to help 1211 you identify the alarm more easily. You do not have to enter a name, 1212 and it need not be unique.</para> 1213 1214 <para>Note that this field is only displayed if the use of alarm 1215 names is enabled in the 1216 <link linkend="preferences-general">General</link> tab of the 1217 Configuration dialog.</para> 1218 1219 </sect2> 1220 1221 <sect2> 1222 <title>Alarm Action</title> 1223 1224 <para>The controls in the <guilabel>Action</guilabel> group box vary 1225 depending on the type of alarm being edited.</para> 1226 1227 <sect3> 1228 <title>Display Alarms</title> 1229 1230 <para>Display alarms display a window when the alarm triggers. Select 1231 the method used to generate the alarm window contents, using the combo 1232 box at the top:</para> 1233 1234 <itemizedlist> 1235 <listitem> 1236 <para><guilabel>Text message</guilabel> in order to enter an alarm 1237 message text (which may include newlines) in the edit box.</para> 1238 </listitem> 1239 1240 <listitem> 1241 <para><guilabel>File contents</guilabel> to enter the path or &URL; of 1242 a text or image file whose contents are to be displayed in the alarm 1243 message. Use the button beside the edit box to display a file selection 1244 dialog. The <guilabel>Speak</guilabel> option is not available for this 1245 type of alarm.</para> 1246 </listitem> 1247 1248 <listitem> 1249 <para><guilabel>Command output</guilabel> to specify that the alarm 1250 message text will be generated by a command which is executed when the 1251 alarm triggers. See 1252 <link linkend="command-alarm">Command Alarms</link> below for details 1253 of how to enter the command or command script to execute.</para> 1254 </listitem> 1255 </itemizedlist> 1256 1257 <para>The controls available for display alarms are:</para> 1258 1259 <itemizedlist> 1260 <listitem> 1261 <para>The <guilabel>Sound</guilabel> option allows you to select 1262 whether an audible alarm should sound when the alarm message is 1263 displayed. Choose:</para> 1264 1265 <itemizedlist> 1266 <listitem> 1267 <para><guilabel>None</guilabel> to display the alarm silently.</para> 1268 </listitem> 1269 1270 <listitem> 1271 <para><guilabel>Beep</guilabel> to sound a beep.</para> 1272 </listitem> 1273 1274 <listitem> 1275 <para><guilabel>Speak</guilabel> to have the alarm message spoken as 1276 well as being displayed. This option is only available if &kalarm; was 1277 built with speech enabled and you have the &Qt; Speech module installed 1278 and working.</para> 1279 </listitem> 1280 1281 <listitem> 1282 <para><guilabel>Sound file</guilabel> to play an audio file. Use the 1283 button on the right to display the Sound File dialog which lets you 1284 select a file to play and set volume and repetition options. If you 1285 hover the mouse over the selector, a tooltip will display the audio file 1286 currently selected.</para> 1287 1288 <para>In the Sound File dialog:</para> 1289 1290 <itemizedlist> 1291 <listitem> 1292 <para>Enter the sound file path, or use the button beside the 1293 edit box to display a file selection dialog. You can listen to the 1294 selected file by clicking the play button to the left of the edit 1295 field. That button then changes function to allow you to stop playing 1296 when you have heard enough.</para> 1297 </listitem> 1298 1299 <listitem> 1300 <para>Check <guilabel>Repeat</guilabel> to continually repeat the 1301 audio file for as long as the alarm is displayed. (The alarm message 1302 window contains a button to stop playing the sound should you need 1303 silence but still want to display the alarm.)</para> 1304 </listitem> 1305 1306 <listitem> 1307 <para>Check <guilabel>Volume</guilabel> and adjust the slider 1308 control if you want to adjust the volume at which the audio file is 1309 played.</para> 1310 </listitem> 1311 1312 <listitem> 1313 <para>If the &phonon; audio backend currently in use supports it, you 1314 can fade the volume. Fading means to start 1315 playing the audio file at one volume and gradually change to the final 1316 volume, over a specified time interval. The final volume is that 1317 entered in <guilabel>Volume</guilabel> above. To enable fade, check 1318 <guilabel>Fade</guilabel>, and then enter the fade period in seconds 1319 in the <guilabel>Fade time</guilabel> field, and adjust the 1320 <guilabel>Initial volume</guilabel> slider.</para> 1321 </listitem> 1322 </itemizedlist> 1323 1324 <tip><para>You can use the <guibutton>Try</guibutton> button to test out 1325 the selected sound levels.</para></tip> 1326 </listitem> 1327 </itemizedlist> 1328 </listitem> 1329 1330 <listitem> 1331 <para>Use the <guibutton>Font & Color...</guibutton> button to 1332 select a font, and foreground and background colors, for the alarm 1333 message. In the <guilabel>Choose Alarm Font & Color</guilabel> 1334 dialog, check <guilabel>Use default font</guilabel> to display the 1335 message in whatever font is configured as the default at the time 1336 the message is displayed. To choose a specific font for the message, 1337 uncheck <guilabel>Use default font</guilabel>. (The default font and 1338 colors can be set in the 1339 <link linkend="preferences-edit">Configuration dialog</link>.)</para> 1340 1341 <para>The selected colors are shown in the alarm message text entry 1342 field.</para> 1343 </listitem> 1344 1345 <listitem> 1346 <para>The <guilabel>Display method</guilabel> option lets you select 1347 how to display the alarm. Choose:</para> 1348 1349 <itemizedlist> 1350 <listitem> 1351 <para><guilabel>Window</guilabel> to display the alarm in a window. 1352 This option allows the full range of options to be used when 1353 configuring the alarm.</para> 1354 </listitem> 1355 1356 <listitem> 1357 <para><guilabel>Notification</guilabel> to use the standard 1358 notification system to display the alarm message. Due to the 1359 limitations of the notification system, the following alarm 1360 configuration options cannot be used with notifications: setting font 1361 and color; setting an audio file to play when the alarm is displayed; 1362 confirmation of alarm acknowledgement; automatic closing of the 1363 display on expiry of the late-cancellation time.</para> 1364 </listitem> 1365 </itemizedlist> 1366 1367 <para>See the 1368 <link linkend="message-display">Alarm Message Display</link> section 1369 for further details about how alarm messages are displayed.</para> 1370 </listitem> 1371 1372 <listitem> 1373 <para>Use the <guibutton>Special Actions...</guibutton> button to 1374 specify shell commands to execute before or after displaying the 1375 alarm. In the <guilabel>Special Alarm Actions</guilabel> 1376 dialog:</para> 1377 1378 <itemizedlist> 1379 <listitem> 1380 <para>In the <guilabel>Pre-alarm action</guilabel> field, enter a 1381 shell command to execute before the alarm is displayed. Note that 1382 &kalarm; will wait for the command to complete before displaying the 1383 alarm.</para> 1384 1385 <para>A pre-alarm action is only executed once when the alarm message 1386 is initially displayed, including when a reminder message is replaced 1387 by the actual alarm message. It is <emphasis>not</emphasis> executed 1388 in any of the following circumstances:</para> 1389 1390 <itemizedlist> 1391 <listitem><para>When a reminder message is displayed.</para></listitem> 1392 <listitem><para>When the message is redisplayed after deferring the 1393 alarm, unless <guilabel>Execute for deferred alarms</guilabel> is 1394 checked.</para></listitem> 1395 <listitem><para>When the message was displaying at the time you logged 1396 off and is then restored when you log back in.</para></listitem> 1397 <listitem><para>When a recurring alarm triggers but the alarm message 1398 (or a deferred alarm message) from a previous occurrence of the alarm 1399 is still visible; in other words, when the previous occurrence of the 1400 alarm has not yet been acknowledged.</para></listitem> 1401 </itemizedlist> 1402 1403 <para>The pre-alarm action can be used to control whether to display 1404 the alarm message:</para> 1405 1406 <itemizedlist> 1407 <listitem><para>Check <guilabel>Cancel alarm on error</guilabel> to 1408 cancel the alarm if the pre-alarm command returns an error status. 1409 This will prevent the alarm message from being displayed, and any 1410 post-alarm action from being executed.</para></listitem> 1411 1412 <listitem><para>Normally, if the pre-alarm command returns an error, 1413 an error message is displayed and an error indication is shown in the 1414 alarm list. These error notifications can be prevented by checking 1415 <guilabel>Do not notify errors</guilabel>.</para></listitem> 1416 </itemizedlist> 1417 </listitem> 1418 1419 <listitem> 1420 <para>In the <guilabel>Post-alarm action</guilabel> field, enter a 1421 shell command to execute when the alarm is acknowledged (whether by 1422 clicking <guibutton>Close</guibutton> or by using the close button 1423 in the window's titlebar). It is <emphasis>not</emphasis> 1424 executed in any of the following circumstances:</para> 1425 1426 <itemizedlist> 1427 <listitem><para>When a reminder message is closed.</para></listitem> 1428 <listitem><para>When you defer the alarm, except when the deferred 1429 alarm is finally acknowledged.</para></listitem> 1430 <listitem><para>When the alarm message is closed due to logging 1431 out.</para></listitem> 1432 </itemizedlist> 1433 </listitem> 1434 </itemizedlist> 1435 1436 <para>See <link linkend="command-alarm">Command Alarms</link> below 1437 for details of how shell commands are executed.</para> 1438 1439 </listitem> 1440 </itemizedlist> 1441 </sect3> 1442 1443 <sect3 id="command-alarm"> 1444 <title>Command Alarms</title> 1445 1446 <para>Command alarms execute a command without displaying any alarm 1447 message.</para> 1448 1449 <note><para>This alarm type is not available if &kde; is running in 1450 kiosk mode.</para></note> 1451 1452 <para>When the command is executed, the environment variable 1453 <envar>KALARM_UID</envar> contains the event UID for the alarm. Note 1454 that when the command is executed from the Alarm Edit dialog's 1455 <guibutton>Try</guibutton> button, <envar>KALARM_UID</envar> will be 1456 blank if it is a new alarm, or if the alarm has been modified in the 1457 dialog, because the alarm only acquires a UID when it is saved in the 1458 alarm calendar.</para> 1459 1460 <para>The controls available for command alarms are:</para> 1461 1462 <itemizedlist> 1463 <listitem> 1464 <para>The <guilabel>Enter a script</guilabel> check box lets you choose 1465 whether to enter a shell command line or a script.</para> 1466 1467 <para>If this option is unchecked, you can enter a shell command line 1468 to execute. The command is passed straight to the default shell (defined 1469 by the <envar>SHELL</envar> environment variable), and may include 1470 whatever options, parameters, piped commands, &etc; are permitted by 1471 the shell in a single line command.</para> 1472 1473 <para>If this option is checked, you can enter the text of a script to 1474 execute. Remember to include a first line such as 1475 <literal>#!/bin/bash</literal> to ensure that the correct command 1476 interpreter is invoked.</para> 1477 </listitem> 1478 1479 <listitem><para>If the command returns an error, an error message is 1480 normally displayed, and an error indication is shown in the alarm 1481 list. The error notification message can be prevented by checking 1482 <guilabel>Do not notify errors</guilabel>.</para></listitem> 1483 1484 <listitem> 1485 <para>Use the <guilabel>Command Output</guilabel> group box to specify 1486 what you want to be done with any terminal output which the command 1487 produces when it executes.</para> 1488 1489 <itemizedlist> 1490 <listitem> 1491 <para>Check <guilabel>Execute in terminal window</guilabel> to cause 1492 the command to be executed in a terminal window. You can choose 1493 which type of terminal window should be used in the 1494 <link linkend="preferences-general">Configuration dialog</link>.</para> 1495 </listitem> 1496 1497 <listitem> 1498 <para>Check <guilabel>Log to file</guilabel> to save the command's 1499 output in a file. The output, prefixed by a heading showing the time 1500 at which the command was scheduled to run, will be appended to any 1501 existing contents of the file. Enter the file name in the edit box, or 1502 use the button beside the edit box to display a file selection 1503 dialog.</para> 1504 </listitem> 1505 1506 <listitem> 1507 <para>Check <guilabel>Discard</guilabel> to throw away the command's 1508 output.</para> 1509 </listitem> 1510 </itemizedlist> 1511 </listitem> 1512 </itemizedlist> 1513 </sect3> 1514 1515 <sect3> 1516 <title>Email Alarms</title> 1517 1518 <para>Email alarms send an email without displaying any alarm 1519 message.</para> 1520 1521 <para>Fill in the recipients' addresses, the email subject line and the 1522 message body in the three edit fields. Use the button beside the 1523 addressee edit box to display your &kde; address book from which you 1524 can select email recipients. (Note that the button is only shown if 1525 &kalarm;'s 1526 <link linkend="akonadi-plugin">Akonadi plugin</link> is installed and 1527 enabled.) 1528 Attachments may be added using the <guibutton>Add...</guibutton> 1529 button. Note that attached files must still exist when the alarm is 1530 triggered; no copy is stored at the time the alarm is configured. To 1531 remove an attachment, highlight it in the drop-down list and click the 1532 <guibutton>Remove</guibutton> button.</para> 1533 1534 <para>Set the following options:</para> 1535 1536 <itemizedlist> 1537 <listitem> 1538 <para>The <guilabel>From</guilabel> combo box allows you to select 1539 which &kmail; identity to use as your email address for sending the 1540 email. This option only appears if your <guilabel>From</guilabel> 1541 email address in the 1542 <link linkend="preferences-email">Configuration dialog</link> is set to 1543 <guilabel>Use &kmail; identities</guilabel>. Otherwise your email 1544 address is preset in the 1545 <link linkend="preferences-email">Configuration dialog</link>, rendering 1546 this option inapplicable.</para> 1547 </listitem> 1548 1549 <listitem> 1550 <para>Check <guilabel>Copy email to self</guilabel> to send a blind 1551 copy of the email to yourself when the alarm is triggered. The email 1552 address to which the copy will be sent may be set in the 1553 <link linkend="preferences-email">Configuration dialog</link>, the 1554 default being your email address set in &kmail;.</para> 1555 </listitem> 1556 </itemizedlist> 1557 1558 </sect3> 1559 1560 <sect3> 1561 <title>Audio Alarms</title> 1562 1563 <para>Audio alarms play an audio file without displaying any alarm 1564 message.</para> 1565 1566 <para>Set the following options:</para> 1567 1568 <itemizedlist> 1569 <listitem> 1570 <para>Enter the sound file path, or use the button beside the 1571 edit box to display a file selection dialog.</para> 1572 </listitem> 1573 1574 <listitem> 1575 <para>Check <guilabel>Repeat</guilabel> to continually repeat the 1576 audio file until the <guilabel>Stop Play</guilabel> option is 1577 selected. To stop playing the file, select the 1578 <menuchoice><guimenu>Actions</guimenu> 1579 <guimenuitem>Stop Play</guimenuitem></menuchoice> menu option, or 1580 <mousebutton>Right</mousebutton> click on the system tray icon 1581 and choose 1582 <menuchoice><guimenuitem>Stop Play</guimenuitem></menuchoice> 1583 from the context menu. If you wish, you can set up a global 1584 shortcut key for this action.</para> 1585 </listitem> 1586 1587 <listitem> 1588 <para>Check <guilabel>Volume</guilabel> and adjust the slider 1589 control if you want to adjust the volume at which the audio file is 1590 played.</para> 1591 </listitem> 1592 1593 <listitem> 1594 <para>If the &phonon; audio backend currently in use supports it, you 1595 can fade the volume. Fading means to start 1596 playing the audio file at one volume and gradually change to the final 1597 volume, over a specified time interval. The final volume is that 1598 entered in <guilabel>Volume</guilabel> above. To enable fade, check 1599 <guilabel>Fade</guilabel>, and then enter the fade period in seconds 1600 in the <guilabel>Fade time</guilabel> field, and adjust the 1601 <guilabel>Initial volume</guilabel> slider.</para> 1602 </listitem> 1603 </itemizedlist> 1604 </sect3> 1605 </sect2> 1606 1607 <sect2> 1608 <title>Deferral</title> 1609 1610 <para>If the alarm is a recurring alarm and it was deferred after it 1611 was last displayed, the <guilabel>Deferred Alarm</guilabel> group box 1612 shows the time the alarm was deferred to. 1613 <guibutton>Change...</guibutton> displays a dialog which allows you to 1614 change the deferred time or to cancel the deferral.</para> 1615 1616 </sect2> 1617 1618 <sect2> 1619 <title>Time</title> 1620 1621 <para>In the <guilabel>Time</guilabel> group box, select either</para> 1622 1623 <itemizedlist> 1624 <listitem> 1625 <para><guilabel>At date/time</guilabel> to enter the date and time 1626 when the alarm is to be triggered. Check <guilabel>Any time</guilabel> 1627 if you want to specify only a date for the alarm: in this case the 1628 alarm will be displayed at the first opportunity on or after the 1629 configured start-of-day time, on the specified date. 1630 (<link linkend="preferences-time">Configuring &kalarm;</link> 1631 describes how to set the start-of-day time.)</para> 1632 1633 <para>For a non-recurring alarm, the date/time which you enter must be 1634 in the future, or if you enter only a date it must be today or later. 1635 For a recurring alarm, there are no such restrictions since the start 1636 date/time will be automatically adjusted to the first recurrence due 1637 after the current time.</para> 1638 </listitem> 1639 1640 <listitem> 1641 <para><guilabel>Time from now</guilabel> to enter how long after now 1642 (in hours and minutes) the alarm should be triggered.</para> 1643 </listitem> 1644 </itemizedlist> 1645 1646 <para>If desired, choose a time zone to apply to the alarm. This time 1647 zone is used for all dates and times relating to this alarm, including 1648 recurrence and exception dates and times. Normally, you should leave 1649 the time zone controls unchanged unless you have a good reason to 1650 change them.</para> 1651 1652 <para>The time zone controls are displayed only when the selected time 1653 zone is different from the default time zone set in the 1654 <link linkend="preferences-time">Configuration dialog</link>, or if 1655 you click the <guibutton>Time Zone...</guibutton> button.</para> 1656 1657 <itemizedlist> 1658 <listitem> 1659 <para>In the combo box, choose the time zone which this alarm is to 1660 use. When creating a new alarm, this is initially set to the time zone 1661 selected in the 1662 <link linkend="preferences-time">Configuration dialog</link>, which 1663 will be your computer's time zone unless you have changed it.</para> 1664 </listitem> 1665 1666 <listitem> 1667 <para>Select <guilabel>System time zone</guilabel> if you want to use 1668 the local computer time zone (on whichever computer &kalarm; happens to 1669 be running on at the time).</para> 1670 </listitem> 1671 </itemizedlist> 1672 1673 </sect2> 1674 1675 <sect2> 1676 <title>Reminder</title> 1677 1678 <para>For a display alarm, check <guilabel>Reminder</guilabel> if you 1679 want to display a reminder either before or after the main alarm and 1680 each of its recurrences (if any). Enter how long in advance or 1681 afterwards, using the edit controls beside the check box. Note that 1682 if the alarm recurs, the reminder period is normally limited to 1683 being less than the recurrence or sub-repetition interval.</para> 1684 1685 <note><para>Reminders are not displayed for sub-repetitions within a 1686 recurrence. Reminders are only shown for each main recurrence of the 1687 alarm.</para></note> 1688 1689 <para>If the alarm recurs, check <guilabel>Reminder for first 1690 recurrence only</guilabel> if you only want a reminder for the alarm's 1691 first recurrence. If this is checked, and it is an advance reminder, 1692 the reminder period is not subject to the normal limit of being less 1693 than the recurrence or sub-repetition interval.</para> 1694 1695 1696 </sect2> 1697 1698 <sect2> 1699 <title>Cancelation</title> 1700 1701 <para>The late-cancelation options determine how an alarm is treated 1702 after its scheduled time:</para> 1703 1704 <itemizedlist> 1705 <listitem> 1706 <para>The <guilabel>Cancel if late</guilabel> check box determines what 1707 happens if the alarm cannot be triggered at its scheduled time.</para> 1708 1709 <para>Check this box to cancel the alarm if it cannot be triggered 1710 within a specified time period after the right time. The time period 1711 is selected using controls which appear when you check the box. For 1712 example, if you enter a time period of 1 hour, the alarm will be 1713 triggered at the first opportunity up to an hour after it is due, but 1714 if it cannot be triggered within an hour its activation will be 1715 canceled.</para> 1716 1717 <note><para>The lateness of date-only alarms, &ie; ones for which the 1718 <guilabel>Any time</guilabel> option is selected, is calculated from 1719 the start-of-day time on the alarm's scheduled date.</para></note> 1720 1721 <para>Leave the box unchecked to trigger the alarm at the first 1722 opportunity starting at the scheduled time, regardless of how late it 1723 is.</para> 1724 1725 <note><para>An alarm can only be triggered while you are logged in, 1726 and while both X and &kalarm; are running.</para></note> 1727 </listitem> 1728 1729 <listitem> 1730 <para>Check <guilabel>Auto-close window after this time</guilabel> if 1731 you want the alarm window to be automatically closed if it is still 1732 showing at the expiry of the late-cancelation time.</para> 1733 </listitem> 1734 </itemizedlist> 1735 1736 </sect2> 1737 1738 <sect2> 1739 <title>Recurrence</title> 1740 1741 <para>Specify whether or how the alarm should be repeated using the 1742 <guilabel>Recurrence</guilabel> tab.</para> 1743 1744 <note><para>The alarm's basic repetition characteristics are displayed 1745 for convenience in the title of the <guilabel>Recurrence</guilabel> 1746 tab. The recurrence interval is shown first, followed by any 1747 sub-repetition interval set up using the 1748 <guibutton>Sub-Repetition</guibutton> button.</para></note> 1749 1750 <para>In the <guilabel>Recurrence Rule</guilabel> group box, set the 1751 recurrence type or time period as follows:</para> 1752 1753 <itemizedlist> 1754 <listitem><para>To trigger the alarm once only, select <guilabel>No 1755 recurrence</guilabel>.</para></listitem> 1756 1757 <listitem><para>Select <guilabel>At login</guilabel> to trigger the 1758 alarm whenever you log in, until its scheduled end time. Then, at its 1759 scheduled end time it will finally be triggered one last time. (Note 1760 that an alarm repeated at login will also be triggered any time you 1761 restart &kalarm;.)</para></listitem> 1762 1763 <listitem> 1764 <para>To make the alarm recur at regular intervals, select one of the 1765 time period types and then enter in the 1766 <guilabel>Recur every</guilabel> box how many time periods should 1767 elapse between recurrences. For example, to repeat 1768 every fortnight, you could select <guilabel>Daily</guilabel> and enter 1769 a value of 14, or select <guilabel>Weekly</guilabel> and enter a value 1770 of 2. Depending on the time period type selected, you may have further 1771 options:</para> 1772 1773 <itemizedlist> 1774 <listitem> 1775 <para>For a weekly recurrence, check each day in the week on which you 1776 wish to trigger the alarm.</para> 1777 </listitem> 1778 1779 <listitem> 1780 <para>For a monthly recurrence, you may select either a fixed date, or 1781 a position (⪚ the second Tuesday).</para> 1782 </listitem> 1783 1784 <listitem> 1785 <para>For a yearly recurrence, you may select either a fixed day in 1786 the month, or a position in a month (⪚ the last Saturday in 1787 May). Check each month of the year in which you wish to trigger the 1788 alarm.</para> 1789 1790 <para>If you set up a yearly recurrence for February 29th, you can 1791 specify how it is to be handled in non-leap years by selecting the 1792 appropriate 1793 <guilabel>February 29th alarm in non-leap years</guilabel> 1794 option:</para> 1795 1796 <itemizedlist> 1797 <listitem><para><guilabel>None</guilabel>: the alarm will occur on 1798 February 29th in leap years, but will be suppressed in non-leap 1799 years.</para> 1800 </listitem> 1801 1802 <listitem><para><guilabel>28 Feb</guilabel>: the alarm will occur on 1803 February 29th in leap years, and on February 28th in non-leap 1804 years.</para> 1805 </listitem> 1806 1807 <listitem><para><guilabel>1 Mar</guilabel>: the alarm will occur on 1808 February 29th in leap years, and on March 1st in non-leap 1809 years.</para> 1810 </listitem> 1811 </itemizedlist> 1812 </listitem> 1813 </itemizedlist> 1814 1815 <tip><para>To set a daily alarm to occur only on weekdays, use a 1816 weekly recurrence and check each weekday.</para></tip> 1817 1818 </listitem> 1819 </itemizedlist> 1820 1821 <para>In the <guilabel>Recurrence End</guilabel> group box, set the 1822 overall recurrence time span as follows:</para> 1823 1824 <itemizedlist> 1825 <listitem><para>Select <guilabel>No end</guilabel> to continue the 1826 repetitions indefinitely.</para></listitem> 1827 1828 <listitem><para>Select <guilabel>End after</guilabel> to specify the 1829 total number of occurrences of the alarm.</para></listitem> 1830 1831 <listitem><para>Select <guilabel>End by</guilabel> to specify the 1832 date/time until which the alarm will be repeated. Note that this uses 1833 the same time zone as the alarm's start time.</para> 1834 1835 <note><para>The end date/time determines when the last main recurrence 1836 will be, but does not limit sub-repetitions. If sub-repetitions are 1837 configured, they will trigger as normal after the last main recurrence, 1838 regardless of the end date/time.</para></note> 1839 </listitem> 1840 </itemizedlist> 1841 1842 <para>The <guilabel>Exceptions</guilabel> group box allows you to 1843 exclude certain date/times from the recurrence which you have set up. 1844 Note that these controls are not shown in the simplified form of the 1845 Alarm Edit dialog: to see them, click 1846 <guibutton>More Options</guibutton>.</para> 1847 1848 <itemizedlist> 1849 <listitem> 1850 <para>The list of exceptions (&ie; excluded date/times) is shown on 1851 the left. To add a new exception, enter a date on the right and press 1852 <guibutton>Add</guibutton>. To change an exception, highlight it in 1853 the list, enter the new date on the right and press 1854 <guibutton>Change</guibutton>. To delete an exception, highlight it 1855 in the list and press <guibutton>Delete</guibutton>.</para> 1856 </listitem> 1857 1858 <listitem> 1859 <para>You can restrict an alarm not to occur on holidays by checking 1860 <guilabel>Exclude holidays</guilabel>. This does not change the way 1861 the alarm is scheduled; it simply suppresses the alarm whenever it 1862 happens to trigger on a holiday. You can select your holiday country 1863 or region in the 1864 <link linkend="preferences-time">Configuration dialog</link>.</para> 1865 </listitem> 1866 1867 <listitem> 1868 <para>You can restrict an alarm to occur only during working time by 1869 checking <guilabel>Only during working hours</guilabel>. This does not 1870 change the way the alarm is scheduled; it simply suppresses the alarm 1871 whenever it happens to trigger outside working hours. Work days and 1872 working hours are set in the 1873 <link linkend="preferences-time">Configuration dialog</link>.</para> 1874 </listitem> 1875 </itemizedlist> 1876 1877 <sect3> 1878 <title>Sub-Repetition</title> 1879 1880 <para>You can use the <guibutton>Sub-Repetition</guibutton> button to 1881 set up a repetition within a repetition. In this case, each time the 1882 alarm is due as specified in the main recurrence, instead of being 1883 triggered just once it is triggered repeatedly in accordance with your 1884 sub-repetition specification. For example, to set up an alarm which 1885 repeats every hour from noon to 6 pm each Thursday, you would set up a 1886 weekly recurrence on Thursday at 12:00, and use the Sub-Repetition 1887 dialog to specify an interval of 1 hour and either a count of 6 or a 1888 duration of 6 hours.</para> 1889 1890 <para>In the Sub-Repetition dialog which is displayed when you click 1891 the <guibutton>Sub-Repetition</guibutton> button, check 1892 <guilabel>Repeat every</guilabel> to set up a repetition, or uncheck 1893 it to remove the repetition. If <guilabel>Repeat every</guilabel> is 1894 checked, set up the repetition as follows:</para> 1895 1896 <itemizedlist> 1897 <listitem><para>Enter the time interval between repetitions in the 1898 controls beside <guilabel>Repeat every</guilabel>. Select the desired 1899 time units (⪚ <guilabel>days</guilabel>) and then enter the number 1900 of units.</para> 1901 </listitem> 1902 1903 <listitem><para>Specify either the repetition count or its 1904 duration:</para> 1905 1906 <itemizedlist> 1907 <listitem><para>Select <guilabel>Number of times</guilabel> to enter 1908 how many times the alarm should be triggered after the main 1909 recurrence. So, for example, to make the alarm occur 4 times at each 1910 main recurrence, &ie; 3 additional times, you should enter 3 1911 here.</para> 1912 </listitem> 1913 1914 <listitem><para>Select <guilabel>Duration</guilabel> to enter the 1915 total time period during which the alarm should be repeated. This need 1916 not be an exact multiple of the repetition interval; it will 1917 automatically be rounded down when you click 1918 <guibutton>OK</guibutton>.</para> 1919 </listitem> 1920 </itemizedlist> 1921 </listitem> 1922 </itemizedlist> 1923 1924 <note><para>To prevent overlapping sub-repetitions for the same alarm, 1925 a sub-repetition's duration is restricted to be less than the longest 1926 interval between main recurrences. Each time the alarm recurs as 1927 specified in the main recurrence, any still active sub-repetition 1928 which started at the previous recurrence is automatically 1929 cancelled.</para></note> 1930 1931 </sect3> 1932 </sect2> 1933 1934 <sect2> 1935 <title>Other Controls</title> 1936 1937 <para>If the system configuration allows multiple alarms to wake the 1938 system from suspension, you can select 1939 <guilabel>Wake from suspend</guilabel> to wake the system if it is 1940 currently suspended when the alarm becomes due. This function is not 1941 available for date-only alarms because their time is not defined. See 1942 <link linkend="wake-suspend">Wake From Suspend</link> for more 1943 information.</para> 1944 1945 <para>For display alarms, the 1946 <guilabel>Confirm acknowledgment</guilabel> check box lets you specify 1947 whether you will be prompted for confirmation when you close the alarm 1948 message window. This may be used as a safeguard against accidental 1949 acknowledgment of alarms.</para> 1950 1951 <para>Select <guilabel>Show in &korganizer;</guilabel> to add the 1952 alarm to &korganizer;'s active calendar, where it will appear as an 1953 event without an alarm. This option allows you to track alarms in 1954 &korganizer; while still making use of &kalarm;'s functions.</para> 1955 1956 <note><para>If you later modify or delete the alarm in &kalarm;, the 1957 &korganizer; event will be modified or deleted correspondingly. But 1958 if you change the event in &korganizer;, the alarm in &kalarm; will 1959 not be affected.</para></note> 1960 1961 <para>Press the <guibutton>Load Template</guibutton> button to select 1962 a template to preset the dialog with, as described in <link 1963 linkend="create-edit">Creating and Manipulating Alarms</link>. </para> 1964 1965 <para>Press the <guibutton>Try</guibutton> button to test the alarm 1966 and check whether it works correctly. The alarm is executed just as 1967 if it had been scheduled in the normal way. In the case of an audio 1968 alarm, press the <guibutton>Try</guibutton> button a second time to 1969 stop playing the sound file.</para> 1970 1971 <para>Press the <guibutton>OK</guibutton> button 1972 when all details are correct, to add the alarm to the scheduled 1973 list. Note that when editing an existing alarm, the 1974 <guibutton>OK</guibutton> button is disabled while no changes have 1975 been made.</para> 1976 1977 </sect2> 1978 </sect1> 1979 1980 <sect1 id="message-display"> 1981 <title>Alarm Message Display</title> 1982 1983 <para>Alarm messages may be displayed in windows or as notifications, 1984 depending on the option chosen in the 1985 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>. These two 1986 display options are described below.</para> 1987 1988 <para>If you inhibit notifications for the desktop, the execution of 1989 display alarms will be suspended until notifications are re-enabled. 1990 Note that this applies to all display alarms, regardless of whether 1991 they are displayed in windows or as notifications.</para> 1992 1993 <sect2 id="message-window"> 1994 <title>Alarm Message Window</title> 1995 1996 <para>Alarm messages which are displayed in windows provide the 1997 fullest functionality.</para> 1998 1999 <para>When an alarm message is due, it is displayed on each 2000 desktop and cannot be covered by ordinary windows, to ensure that 2001 you see it. The message window shows the time for which the alarm was 2002 scheduled, so that you can see when it popped up if you were away from 2003 the computer at the time. If the alarm's scheduled time is in a 2004 different time zone from your local computer's setting, its time zone 2005 will also be displayed. (For reminder messages, the date/time shown is 2006 that for the main alarm or its recurrence, not the reminder message 2007 time, and the window title is <quote>Reminder</quote>.)</para> 2008 2009 <para>Alarm message windows remain visible until you acknowledge them, 2010 unless <guilabel>Auto-close window after late-cancelation 2011 time</guilabel> was checked in the <link 2012 linkend="alarm-edit-dlg">Alarm Edit dialog</link>. In the case of a 2013 recurring alarm, if an unacknowledged message window remains from a 2014 previous occurrence of the alarm, the existing window is simply popped 2015 up when the alarm recurs. This avoids having to acknowledge multiple 2016 copies of the same message should you not wish, or be unable, to 2017 acknowledge a message at the time it appears.</para> 2018 2019 <para>The alarm message window provides whichever of the following 2020 options are applicable to the displayed alarm:</para> 2021 2022 <itemizedlist> 2023 <listitem> 2024 <para>Acknowledge the alarm by clicking the 2025 <guibutton>Close</guibutton> button. This closes the window (after a 2026 prompt for confirmation, if you selected 2027 <guilabel>Confirm acknowledgment</guilabel>).</para> 2028 </listitem> 2029 2030 <listitem> 2031 <para>Edit the alarm by clicking the <guibutton>Edit...</guibutton> 2032 button. This displays the 2033 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>.</para> 2034 </listitem> 2035 2036 <listitem> 2037 <para>Display options to defer the alarm until later by clicking the 2038 <guibutton>Defer...</guibutton> button. Then select 2039 <guilabel>Defer for</guilabel> to enter how long after now the 2040 message should be redisplayed (the <guilabel>Preset</guilabel> 2041 button lets you select from a list of common time intervals), or 2042 select <guilabel>Defer until</guilabel> to enter the date and time 2043 when the message is to be redisplayed. Then click 2044 <guibutton>OK</guibutton> to defer the alarm message and close its 2045 window.</para> 2046 2047 <note><para>The time the alarm is deferred to must be earlier than its 2048 next scheduled occurrence or next advance reminder. For this reason, 2049 the <guibutton>Defer...</guibutton> button in the alarm message window 2050 and the <guibutton>OK</guibutton> button in the Deferral dialog are 2051 disabled one minute before the next occurrence or advance 2052 reminder.</para> 2053 <para>Note that if a reminder is configured <emphasis>after</emphasis> 2054 the alarm, you <emphasis>can</emphasis> defer the alarm past its 2055 reminder time. In this case, the reminder will be 2056 suppressed.</para></note> 2057 2058 <note><para>The <guibutton>Defer...</guibutton> button is not 2059 available for alarms which are displayed at login due to the 2060 <guilabel>Repeat at login</guilabel> option having been 2061 selected.</para></note> 2062 </listitem> 2063 2064 <listitem> 2065 <para>Stop playing the alarm's sound file by clicking the button 2066 showing the <quote>stop playing</quote> symbol.</para> 2067 </listitem> 2068 2069 <listitem> 2070 <para>If the alarm message was created by dragging an email from 2071 &kmail;, you can directly access the email in &kmail; by clicking the 2072 button showing the &kmail; icon. This will display the email and 2073 select the folder containing the email in &kmail;'s folder list.</para> 2074 2075 <warning><para>If &kmail;'s indexes are regenerated, the link to the 2076 email in &kmail; will be lost.</para></warning> 2077 </listitem> 2078 2079 <listitem> 2080 <para>The button showing the <guiicon>&kalarm;</guiicon> icon provides 2081 a convenient way to activate &kalarm;'s main window, with that alarm 2082 highlighted.</para> 2083 </listitem> 2084 </itemizedlist> 2085 2086 <para>You can choose in the 2087 <link linkend="preferences-view">Configuration dialog</link> which of 2088 two different modes should be used to display alarm message 2089 windows:</para> 2090 2091 <itemizedlist> 2092 <listitem> 2093 <para>As a normal window. In this mode, the keyboard focus is taken 2094 by the alarm message window when it appears, so if you are typing at 2095 the time your keystrokes will be diverted to it rather than your 2096 original application.</para> 2097 </listitem> 2098 2099 <listitem> 2100 <para>As a non-modal window. In this mode, the keyboard focus is 2101 unaffected when the alarm message window appears, so it will not 2102 interfere with your typing. However in this mode the window has no 2103 titlebar or frame, so you cannot move it or resize it.</para> 2104 </listitem> 2105 </itemizedlist> 2106 2107 <note><para>When an alarm is displayed on top of a full screen 2108 application, it is shown as a non-modal window regardless of this 2109 configuration setting. This is due to a limitation of the window 2110 system.</para></note> 2111 2112 <sect3> 2113 <title>Positioning of Message Windows</title> 2114 2115 <para>You can choose in the 2116 <link linkend="preferences-view">Configuration dialog</link> which of 2117 two schemes should be used to position alarm message windows:</para> 2118 2119 <itemizedlist> 2120 <listitem> 2121 <para>The windows are displayed as far away from the current mouse 2122 cursor as possible. This minimizes disruption to your work flow and 2123 minimizes the possibility of accidentally acknowledging the 2124 alarm.</para> 2125 </listitem> 2126 2127 <listitem> 2128 <para>The windows are displayed in the center of the screen. To reduce 2129 the chance of accidentally acknowledging the alarm, the buttons on the 2130 window are initially disabled, becoming active only after a 2131 configurable delay.</para> 2132 </listitem> 2133 </itemizedlist> 2134 2135 <para>If you have several alarm message windows, or error messages, 2136 displayed, you can spread the windows out across the screen to make 2137 them all visible, or group them all together again in the top left 2138 corner of the screen, by means of the <menuchoice> 2139 <guimenu>View</guimenu><guimenuitem>Spread Windows</guimenuitem> 2140 </menuchoice> menu option. If you wish, you can set up a global 2141 shortcut key for this action.</para> 2142 2143 </sect3> 2144 </sect2> 2145 2146 <sect2> 2147 <title>Alarm Message Notifications</title> 2148 2149 <para>Alarm messages which are displayed as notifications provide 2150 less functionality than those displayed in windows.</para> 2151 2152 <para>When an alarm message is due, it is displayed as a notification. 2153 The notification shows the time for which the alarm was scheduled. If 2154 the alarm's scheduled time is in a different time zone 2155 from your local computer's setting, its time zone will also be 2156 displayed. (For reminder messages, the date/time shown is that for the 2157 main alarm or its recurrence, not the reminder message time, and a 2158 “Reminder” heading is shown.)</para> 2159 2160 <para>The notification automatically closes after a short time-out. 2161 (Note that the time-out is common to all applications; it can be 2162 changed in &systemsettings;.) After a notification times out, it can 2163 still be seen in the notification history until you remove it or 2164 until you log out. Because applications have no way to access the 2165 notification history, &kalarm; cannot remove or replace notifications 2166 in the history as it would for alarm windows. So the history may 2167 contain multiple notifications for the same alarm, including reminders 2168 and recurrences.</para> 2169 2170 <para>The alarm message notification provides the following options. 2171 Note that selecting any option will immediately close the notification, 2172 and prevent it being shown in the notification history. 2173 Note also that these options are only available while the notification 2174 is active, before it times out. If you subsequently access the 2175 notification in the notification history, then due to the limitations 2176 of the notification system, the only interaction available is to 2177 remove it from the history.</para> 2178 2179 <itemizedlist> 2180 <listitem> 2181 <para>Acknowledge the alarm by clicking the 2182 <guibutton>Close</guibutton> button. This closes the notification.</para> 2183 </listitem> 2184 2185 <listitem> 2186 <para>Edit the alarm by clicking the <guibutton>Edit</guibutton> 2187 button. This displays the 2188 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>.</para> 2189 </listitem> 2190 2191 <listitem> 2192 <para>Display options to defer the alarm until later by clicking the 2193 <guibutton>Defer</guibutton> button. This button is only shown if it 2194 is possible to defer the alarm. See the description of the defer 2195 option in the 2196 <link linkend="message-window">Alarm Message Window</link> section 2197 for details.</para> 2198 </listitem> 2199 2200 <listitem> 2201 <para>Clicking the notification anywhere other than a button will 2202 activate &kalarm;'s main window, with that alarm highlighted.</para> 2203 </listitem> 2204 2205 </itemizedlist> 2206 2207 </sect2> 2208 </sect1> 2209 2210 <sect1 id="system-tray"> 2211 <title>System Tray Operation</title> 2212 2213 <para>&kalarm; by default displays an icon in the system tray. The icon 2214 provides both control and an alarm monitoring status indication. A 2215 normal &kalarm; icon indicates that all alarms are being monitored, 2216 while two different modified icons indicate either that 2217 some alarms, or that all alarms, are not being monitored. The icon 2218 modifications depend on the icon theme being used.</para> 2219 2220 <para>&kalarm;'s system tray icon is by default automatically hidden 2221 whenever there are no alarms due in the next 24 hours. You can change 2222 the auto-hide time limit, or always show the system tray icon, using 2223 the <link linkend="preferences-view">Configuration dialog</link>. To 2224 show the icon when it has been automatically hidden, click the arrow 2225 in the system tray to reveal hidden icons.</para> 2226 2227 <para>If you hover the mouse cursor over the system tray icon, a 2228 summary of the first few message alarms due in the next 24 hours are 2229 displayed as a tooltip. You can switch this feature off, or configure 2230 the number of alarms to display and their format, in the 2231 <link linkend="preferences-view">Configuration dialog</link>.</para> 2232 2233 <para><mousebutton>Left</mousebutton> click on the system tray icon to 2234 toggle between displaying and hiding the &kalarm; main window.</para> 2235 2236 <para><mousebutton>Right</mousebutton> click on the system tray icon to 2237 display its context menu:</para> 2238 2239 <variablelist> 2240 <varlistentry> 2241 <term><menuchoice><guimenuitem>Enable Alarms</guimenuitem></menuchoice></term> 2242 <listitem><para><action>Enables or disables monitoring of alarms.</action></para> 2243 <para>See 2244 <link linkend="enable-disable">Enabling and Disabling Alarms</link> 2245 for details.</para> 2246 </listitem> 2247 </varlistentry> 2248 2249 <varlistentry> 2250 <term><menuchoice><guimenuitem>New Alarm</guimenuitem></menuchoice></term> 2251 <listitem><para><action>After you select the alarm type from the list 2252 which appears, opens the Alarm Edit dialog to create a new 2253 alarm.</action></para> 2254 </listitem> 2255 </varlistentry> 2256 2257 <varlistentry> 2258 <term><menuchoice><guimenuitem>Stop Play</guimenuitem></menuchoice></term> 2259 <listitem><para><action>Halts playback of the audio file currently 2260 playing.</action></para> 2261 </listitem> 2262 </varlistentry> 2263 2264 <varlistentry> 2265 <term><menuchoice><guimenuitem>Spread Windows</guimenuitem></menuchoice></term> 2266 <listitem><para><action>Spreads alarm and error message windows across 2267 the screen, or groups them together again.</action></para> 2268 </listitem> 2269 </varlistentry> 2270 2271 <varlistentry> 2272 <term><menuchoice><guimenuitem>Configure &kalarm;...</guimenuitem></menuchoice></term> 2273 <listitem><para><action>Displays the &kalarm; Configuration dialog.</action></para> 2274 <para>The Configuration dialog is described in 2275 <link linkend="preferences">Configuring &kalarm;</link>. It 2276 includes options relating to the &kalarm; system tray icon.</para> 2277 </listitem> 2278 </varlistentry> 2279 2280 <varlistentry> 2281 <term><menuchoice><guimenuitem>Restore / Minimize</guimenuitem></menuchoice></term> 2282 <listitem><para><action>Restores or minimizes the main &kalarm; window.</action></para> 2283 </listitem> 2284 </varlistentry> 2285 2286 <varlistentry> 2287 <term><menuchoice><guimenuitem>Quit</guimenuitem></menuchoice></term> 2288 <listitem><para><action>Closes the &kalarm; system tray 2289 icon and main windows.</action></para> 2290 <para>Quits &kalarm; if no alarm message windows are displayed.</para> 2291 </listitem> 2292 </varlistentry> 2293 </variablelist> 2294 2295 <sect2> 2296 <title>Displaying &kalarm; in the System Tray</title> 2297 2298 <para>You must be running the &plasma; desktop or another suitable window 2299 manager in order to display &kalarm; in the system tray.</para> 2300 2301 <para>Select <menuchoice><guimenu>View</guimenu> 2302 <guimenuitem>Show in System Tray</guimenuitem></menuchoice> to display 2303 &kalarm; in the system tray according to the preferences set in the 2304 <link linkend="preferences-view">View</link> tab of the Configuration 2305 dialog.</para> 2306 2307 <para>To remove &kalarm; from the system tray, deselect 2308 <menuchoice><guimenu>View</guimenu> 2309 <guimenuitem>Show in System Tray</guimenuitem></menuchoice>.</para> 2310 2311 <para>To choose whether or not &kalarm; will be shown at startup in 2312 the system tray, use the <link linkend="preferences-view">View</link> 2313 tab of the Configuration dialog.</para> 2314 </sect2> 2315 </sect1> 2316 2317 <sect1 id="refreshing"> 2318 <title>Refreshing Alarms</title> 2319 2320 <para>If in the unlikely event that any alarm was not triggered when 2321 it should have been, you can refresh the alarm list and trigger any 2322 missed alarms by selecting 2323 <menuchoice> 2324 <guimenu>Actions</guimenu><guimenuitem>Refresh Alarms</guimenuitem> 2325 </menuchoice>. This causes &kalarm; to reload all alarm 2326 calendars.</para> 2327 2328 <para>You can reload an individual calendar and refresh its alarms in 2329 the alarm list by 2330 <mousebutton>Right</mousebutton> clicking the calendar in the 2331 calendars list and selecting the 2332 <menuchoice><guimenuitem>Reload</guimenuitem></menuchoice> menu 2333 option. See <link linkend="calendars">Alarm Calendars</link> for 2334 details.</para> 2335 2336 </sect1> 2337 2338 <sect1 id="enable-disable"> 2339 <title>Enabling and Disabling Alarms</title> 2340 2341 <para>Alarms may be enabled and disabled either as a whole or 2342 individually:</para> 2343 2344 <itemizedlist> 2345 <listitem> 2346 <para><quote>Alarm monitoring</quote> applies to alarms as a whole. 2347 While alarm monitoring is disabled, no alarms are triggered at all. 2348 While alarm monitoring is enabled (the normal situation), all alarms 2349 which are not individually disabled will trigger at the appropriate 2350 times.</para> 2351 2352 <para>When alarm monitoring is re-enabled, alarms which would have 2353 triggered while it was disabled are now triggered (unless any 2354 late-cancel option prevents this). In other words, disabling alarm 2355 monitoring has the same effect as stopping &kalarm; – alarms are 2356 postponed until it is re-enabled.</para> 2357 </listitem> 2358 2359 <listitem> 2360 <para>Alarms may be individually enabled and disabled, independently 2361 of the alarm monitoring status. So the enabled/disabled status of 2362 individual alarms will be unchanged by disabling and then re-enabling 2363 alarm monitoring. Unlike alarm monitoring which could potentially be 2364 disabled due to &kalarm; not running, individual alarms can only be 2365 disabled if you use menu commands to do so.</para> 2366 2367 <para>When an alarm is individually re-enabled, it is not now 2368 triggered if it became due while disabled. In other words, disabling 2369 an individual alarm cancels all its occurrences until it is 2370 re-enabled.</para> 2371 2372 <para>An alarm's individual enabled/disabled status is indicated by 2373 its color in the alarm list (the color being configurable in the 2374 <link linkend="preferences-view">View</link> tab of the Configuration 2375 dialog).</para> 2376 </listitem> 2377 </itemizedlist> 2378 2379 <para>For an alarm to trigger, it must be individually enabled as well 2380 as alarm monitoring being enabled.</para> 2381 2382 <sect2> 2383 <title>Enabling Alarm Monitoring</title> 2384 2385 <para>For alarm monitoring to occur, &kalarm; must be running. Once you 2386 run &kalarm;, it will from then on start automatically whenever you log 2387 in unless you later disable it in the 2388 <link linkend="preferences-general">General</link> tab of the 2389 Configuration dialog.</para> 2390 2391 <para>If alarm monitoring is currently disabled, do one of the 2392 following to enable alarms:</para> 2393 2394 <itemizedlist> 2395 <listitem> 2396 <para>Select <menuchoice><guimenu>Actions</guimenu> 2397 <guimenuitem>Enable Alarms</guimenuitem></menuchoice>.</para> 2398 </listitem> 2399 2400 <listitem> 2401 <para><mousebutton>Right</mousebutton> click on the system tray icon 2402 and choose 2403 <menuchoice><guimenuitem>Enable Alarms</guimenuitem></menuchoice> 2404 from the context menu.</para> 2405 </listitem> 2406 </itemizedlist> 2407 2408 </sect2> 2409 2410 <sect2> 2411 <title>Disabling Alarm Monitoring</title> 2412 2413 <para>You can temporarily disable alarm monitoring, which prevents 2414 &kalarm; from checking any alarms either until you re-enable alarms, or 2415 – assuming that &kalarm; is configured to start at login – 2416 until the next time you log in.</para> 2417 2418 <itemizedlist> 2419 <listitem> 2420 <para>Unselect <menuchoice><guimenu>Actions</guimenu> 2421 <guimenuitem>Enable Alarms</guimenuitem></menuchoice>.</para> 2422 </listitem> 2423 2424 <listitem> 2425 <para><mousebutton>Right</mousebutton> click on the system tray icon 2426 and uncheck 2427 <menuchoice><guimenuitem>Enable Alarms</guimenuitem></menuchoice> 2428 from the context menu.</para> 2429 </listitem> 2430 2431 <listitem> 2432 <para>Run &kalarm; with the command line option 2433 <option>--disable-all</option>.</para> 2434 </listitem> 2435 2436 <listitem> 2437 <para>Stop &kalarm; as described in 2438 <link linkend="quitting">Quitting &kalarm;</link>.</para> 2439 </listitem> 2440 </itemizedlist> 2441 2442 <para>Alarms may be permanently disabled by preventing &kalarm; from 2443 being started at login using the 2444 <link linkend="preferences-general">General</link> tab of the 2445 Configuration dialog.</para> 2446 2447 </sect2> 2448 2449 <sect2> 2450 <title>Enabling and Disabling Individual Alarms</title> 2451 2452 <para>To enable individual alarms which are currently disabled, do 2453 one of the following:</para> 2454 2455 <itemizedlist> 2456 <listitem> 2457 <para>Select one or more alarms by clicking on their entries in the 2458 alarm list. Then choose <menuchoice> 2459 <guimenu>Actions</guimenu><guimenuitem>Enable</guimenuitem> 2460 </menuchoice>.</para> 2461 </listitem> 2462 2463 <listitem> 2464 <para><mousebutton>Right</mousebutton> click on the desired entries in 2465 the alarm list and choose 2466 <menuchoice><guimenuitem>Enable</guimenuitem></menuchoice> 2467 from the context menu.</para> 2468 </listitem> 2469 </itemizedlist> 2470 2471 <para>To disable individual alarms which are currently enabled, do one 2472 of the following:</para> 2473 2474 <itemizedlist> 2475 <listitem> 2476 <para>Select one or more alarms by clicking on their entries in the 2477 alarm list. Then choose <menuchoice> 2478 <guimenu>Actions</guimenu><guimenuitem>Disable</guimenuitem> 2479 </menuchoice>.</para> 2480 </listitem> 2481 2482 <listitem> 2483 <para><mousebutton>Right</mousebutton> click on the desired entries in 2484 the alarm list and choose 2485 <menuchoice><guimenuitem>Disable</guimenuitem></menuchoice> 2486 from the context menu.</para> 2487 </listitem> 2488 </itemizedlist> 2489 2490 </sect2> 2491 </sect1> 2492 2493 <sect1 id="wake-suspend"> 2494 <title>Wake From Suspend</title> 2495 2496 <para>Alarms can be configured to wake your computer from hibernation 2497 or suspension when the alarm triggers, so that the alarm action can 2498 occur even when the system is shut down. The mechanism used by 2499 &kalarm; to wake the system, and the user interface to control it, 2500 depend on the type of system and user permissions. There are two 2501 possibilities:</para> 2502 2503 <sect2> 2504 <title>Linux Kernel Timer Wake From Suspend</title> 2505 2506 <para>On Linux systems, if the user has kernel alarm timer 2507 (<literal>cap_wake_alarm</literal>) capability, any number of alarms 2508 can be set to wake from suspend. In this case, wake from suspend is 2509 configured for each individual alarm in the 2510 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> using its 2511 <guilabel>Wake from suspend</guilabel> option.</para> 2512 2513 <para>You can configure how long before the alarm to wake from suspend, 2514 to ensure that the system has time to fully restore itself before the 2515 alarm triggers, in the 2516 <link linkend="preferences-time">Configuration dialog</link>.</para> 2517 2518 </sect2> 2519 2520 <sect2> 2521 <title>RTC Wake From Suspend</title> 2522 2523 <para>On non-Linux systems, or on Linux systems where the user does not 2524 have <literal>cap_wake_alarm</literal> capability, the real time clock 2525 (<acronym>RTC</acronym>) alarm is used. This can only be set for one 2526 alarm at a time. In this case, a special Wake From Suspend dialog is 2527 used to configure it. The dialog allows the Wake From Suspend alarm to 2528 be set, cancelled or displayed. To access the dialog, select 2529 <menuchoice><guimenu>Actions</guimenu> 2530 <guimenuitem>Wake From Suspend</guimenuitem></menuchoice>.</para> 2531 2532 <para>Use of the Wake From Suspend function requires 2533 administrative privileges. You will be prompted for the root password 2534 when you set or cancel a Wake From Suspend alarm.</para> 2535 2536 <note><para>Wake From Suspend is not supported on some computers, 2537 especially older ones, and some computers only support setting a 2538 wakeup time up to 24 hours ahead. There may also be restrictions on 2539 which suspend mode the function will wake from. You should consider 2540 setting up test alarms to check your system's capability before 2541 relying on this feature.</para></note> 2542 2543 <warning><para>Your computer can only schedule a single Wake From 2544 Suspend at a time. If you use this function with &kalarm;, you must 2545 ensure that this does not conflict with any other application which 2546 also uses Wake From Suspend. Whenever an application schedules or 2547 clears Wake From Suspend, this cancels any previously set Wake From 2548 Suspend, no matter whether set by &kalarm; or any other 2549 application.</para></warning> 2550 2551 <para>The Wake From Suspend dialog is used in conjunction with the 2552 alarm list in &kalarm;'s main window.</para> 2553 2554 <itemizedlist> 2555 <listitem> 2556 <para><guibutton>Use highlighted alarm</guibutton>: this sets the 2557 alarm currently highlighted in the alarm list as the Wake From Suspend 2558 alarm. Any existing scheduled Wake From Suspend is cancelled, as 2559 explained above. The button is enabled only if exactly one alarm is 2560 highlighted.</para> 2561 </listitem> 2562 2563 <listitem> 2564 <para><guibutton>Cancel wake from suspend</guibutton>: this cancels 2565 any existing Wake From Suspend (whether set by &kalarm; or any other 2566 application - see above). Note that this only cancels the wakeup 2567 function associated with the alarm; the alarm itself is not deleted 2568 and will continue to operate as normal.</para> 2569 </listitem> 2570 2571 <listitem> 2572 <para><guibutton>Show current alarm</guibutton>: this highlights the 2573 current Wake From Suspend alarm in the alarm list, so that it can be 2574 identified. The button is disabled if no Wake From Suspend is 2575 currently configured.</para> 2576 </listitem> 2577 2578 <listitem> 2579 <para>The <guilabel>Number of minutes before alarm to wake from 2580 suspend</guilabel> control allows you, if you wish, to ensure that the 2581 system has time to fully restore itself before the alarm triggers, so 2582 that the alarm can trigger at the correct time.</para> 2583 </listitem> 2584 </itemizedlist> 2585 2586 </sect2> 2587 </sect1> 2588 2589 <sect1 id="quitting"> 2590 <title>Quitting &kalarm;</title> 2591 2592 <para>Quit &kalarm; by selecting <menuchoice> 2593 <guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice>, 2594 or <menuchoice><guimenuitem>Quit</guimenuitem></menuchoice> in the 2595 system tray icon context menu. Alternatively, if the system tray icon 2596 is not visible, close all &kalarm;'s windows.</para> 2597 2598 </sect1> 2599 </chapter> 2600 2601 <chapter id="preferences"> 2602 <title>Configuring &kalarm;</title> 2603 2604 <para>To configure &kalarm;'s operation to suit your system and your 2605 personal preferences, select <menuchoice><guimenu>Settings</guimenu> 2606 <guimenuitem>Configure &kalarm;...</guimenuitem></menuchoice>. 2607 This displays the Configuration dialog.</para> 2608 2609 <sect1 id="preferences-general"> 2610 <title>General</title> 2611 2612 <para>The <guilabel>General</guilabel> section lets you control 2613 &kalarm;'s overall behavior:</para> 2614 2615 <itemizedlist> 2616 <listitem> 2617 <para><guilabel>Start at login</guilabel>: &kalarm; will be started 2618 automatically at session login, ensuring that &kalarm; runs at 2619 all times unless you manually quit.</para> 2620 2621 <warning><para>This option should always be checked unless you intend 2622 to discontinue use of &kalarm;.</para></warning> 2623 2624 <note><para>This option is automatically reselected whenever &kalarm; 2625 is run. So if you have unchecked this option and want to continue to 2626 prevent &kalarm; from running at login, you need to uncheck this 2627 option again each time you run &kalarm;.</para></note> 2628 </listitem> 2629 2630 <listitem> 2631 <para><guilabel>Warn before quitting</guilabel>: When alarms are 2632 disabled while &kalarm; is not running, selecting this option prompts 2633 you for confirmation if you attempt to terminate &kalarm; using the 2634 system tray icon's <menuchoice><guimenu>Quit</guimenu></menuchoice> 2635 option. This prevents accidental disabling of alarms. For safety, this 2636 option is automatically re-enabled by default whenever you change run 2637 mode.</para> 2638 </listitem> 2639 2640 <listitem><para><guilabel>Enable alarm names</guilabel>: Specify 2641 whether each alarm can be given a name to help you to identify it. 2642 This determines whether the <guilabel>Name</guilabel> column will be 2643 shown in the <link linkend="alarm-list">alarm list</link>, and 2644 whether the <guilabel>Alarm name</guilabel> field will appear in the 2645 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>.</para> 2646 </listitem> 2647 2648 <listitem><para><guilabel>Confirm alarm deletions</guilabel>: Specify 2649 whether you should be prompted for confirmation each time you delete 2650 an alarm.</para> 2651 </listitem> 2652 2653 <listitem><para><guilabel>Default defer time interval</guilabel>: 2654 Enter the default time interval, in hours and minutes, to show 2655 initially when the Defer Alarm dialog is displayed. Note that if an 2656 alarm has been deferred previously, the interval shown initially in the 2657 Defer Alarm dialog will be equal to the deferral interval used the last 2658 time that alarm was deferred.</para> 2659 </listitem> 2660 2661 <listitem><para><guilabel>Terminal for Command Alarms</guilabel>: 2662 Here, you can select which type of terminal window should be used for 2663 command alarms which are executed in a terminal window. Some of the 2664 most common terminal window applications are preconfigured, ⪚ 2665 <application>xterm</application>, &konsole;, although only those 2666 which are installed on your system will be shown here. You can view 2667 the actual command options used for each application by displaying the 2668 context help for its radio button.</para> 2669 2670 <para>If you want to use another application, or want to use one of 2671 those listed but with different command options, select 2672 <guilabel>Other</guilabel> and enter the command to invoke the 2673 terminal window. By default, the alarm's command string will be 2674 appended to what you specify. Alternatively, you may specify where the 2675 alarm's command string should be inserted, by use of the following 2676 codes:</para> 2677 2678 <variablelist> 2679 <varlistentry> 2680 <term>%c</term> 2681 <listitem> 2682 <para>The alarm's command string will be substituted.</para> 2683 </listitem> 2684 </varlistentry> 2685 <varlistentry> 2686 <term>%w</term> 2687 <listitem> 2688 <para>The alarm's command string will be substituted, with a <literal>sleep</literal> appended.</para> 2689 </listitem> 2690 </varlistentry> 2691 <varlistentry> 2692 <term>%C</term> 2693 <listitem> 2694 <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> 2695 </listitem> 2696 </varlistentry> 2697 <varlistentry> 2698 <term>%W</term> 2699 <listitem> 2700 <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> 2701 </listitem> 2702 </varlistentry> 2703 <varlistentry> 2704 <term>%t</term> 2705 <listitem> 2706 <para>&kalarm;'s name in the current language will be substituted.</para> 2707 </listitem> 2708 </varlistentry> 2709 </variablelist> 2710 2711 <para>When the command alarm is triggered, its command string will be 2712 quoted before being inserted into the terminal window command.</para> 2713 </listitem> 2714 2715 <listitem><para><guilabel>Enable Akonadi</guilabel>: 2716 Choose whether to use &akonadi; to provide features which depend on it. 2717 See <link linkend="akonadi-plugin">Akonadi plugin</link> for details. 2718 Note that this option is only shown if the Akonadi plugin is 2719 installed.</para> 2720 </listitem> 2721 2722 </itemizedlist> 2723 </sect1> 2724 2725 <sect1 id="preferences-time"> 2726 <title>Time & Date</title> 2727 2728 <para>The <guilabel>Time & Date</guilabel> section lets you set 2729 options relating to time and date:</para> 2730 2731 <itemizedlist> 2732 <listitem><para><guilabel>Time zone</guilabel>: Select your time zone. 2733 &kalarm; uses this time zone throughout, except when you override it 2734 for individual alarms.</para> 2735 </listitem> 2736 2737 <listitem><para><guilabel>Holiday region</guilabel>: Select which 2738 country's or region's holidays to use. This affects recurring alarms 2739 for which the option to exclude holidays is selected.</para> 2740 </listitem> 2741 2742 <listitem><para><guilabel>Wake from suspend before alarm</guilabel>: 2743 Enter the number of minutes before the alarm trigger time to wake the 2744 system, for alarms set to wake from suspend. This allows you to ensure 2745 that the system has time to fully restore itself before the alarm 2746 triggers, so that the alarm can trigger at the correct time. This 2747 option is only shown if the system configuration allows multiple alarms 2748 to wake the system from suspension. See 2749 <link linkend="wake-suspend">Wake From Suspend</link> for more 2750 information.</para> 2751 </listitem> 2752 2753 <listitem><para><guilabel>Start of day for date-only 2754 alarms</guilabel>: Set the start-of-day time for the purposes of 2755 triggering date-only alarms, &ie; ones for which the <guilabel>Any 2756 time</guilabel> option was selected. On the date when they are due, 2757 such alarms will be output at the earliest opportunity during the 2758 24 hours starting from the start-of-day time.</para> 2759 </listitem> 2760 2761 <listitem><para><guilabel>Working Hours</guilabel> group box: These 2762 options let you define your working hours, needed when the 2763 <guilabel>Only during working hours</guilabel> option is selected for 2764 a recurrence in the 2765 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>.</para> 2766 2767 <itemizedlist> 2768 <listitem><para>Check each day which is a working day.</para> 2769 </listitem> 2770 2771 <listitem><para><guilabel>Daily start time</guilabel>: enter the time 2772 at which you start work each day.</para> 2773 </listitem> 2774 2775 <listitem><para><guilabel>Daily end time</guilabel>: enter the time 2776 at which you finish work each day.</para> 2777 </listitem> 2778 </itemizedlist> 2779 </listitem> 2780 2781 <listitem><para><guilabel>KOrganizer event duration</guilabel>: Enter 2782 the event duration to set in &korganizer; for alarms which are copied to 2783 &korganizer;. The default duration is zero.</para> 2784 </listitem> 2785 2786 </itemizedlist> 2787 </sect1> 2788 2789 <sect1 id="preferences-storage"> 2790 <title>Storage</title> 2791 2792 <para>The <guilabel>Storage</guilabel> section lets you choose options 2793 for saving and archiving alarms:</para> 2794 2795 <itemizedlist> 2796 <listitem> 2797 <para><guilabel>New Alarms & Templates</guilabel>: Specify which 2798 calendar to store new alarms and alarm templates in when using 2799 multiple alarm calendars:</para> 2800 2801 <itemizedlist> 2802 <listitem> 2803 <para><guilabel>Store in default calendar</guilabel>: New alarms and 2804 alarm templates are automatically added to the default alarm calendar 2805 without prompting for confirmation.</para> 2806 </listitem> 2807 2808 <listitem> 2809 <para><guilabel>Prompt for which calendar to store in</guilabel>: 2810 When you create a new alarm or alarm template and there is more than 2811 one writeable alarm calendar, you will be prompted to choose which 2812 calendar to save it in. Note that when alarms are saved on expiry, 2813 they are always stored in the default archived alarm calendar without 2814 prompting.</para> 2815 </listitem> 2816 </itemizedlist> 2817 </listitem> 2818 2819 <listitem><para><guilabel>Archived Alarms</guilabel> group box: These 2820 options control the storage of archived alarms in the default archived 2821 alarm calendar.</para> 2822 2823 <itemizedlist> 2824 <listitem><para><guilabel>Keep alarms after expiry</guilabel>: 2825 Select this option to archive expired and deleted alarms. Deselect it 2826 to keep no record of alarms once they cease to be active. Note that 2827 deleted alarms are only archived if they have previously been 2828 triggered. If you delete an alarm before it ever triggers, it is 2829 discarded.</para> 2830 </listitem> 2831 2832 <listitem><para><guilabel>Discard archived alarms after</guilabel>: 2833 Set the number of days to store expired and deleted alarms in the 2834 archive, after which they are permanently deleted.</para> 2835 </listitem> 2836 2837 <listitem><para><guibutton>Clear archived alarms</guibutton>: This 2838 button discards all currently archived alarms from the default archived 2839 alarm calendar. (Other archived alarm calendars are left unchanged in 2840 case they are shared with other people.) This has no effect on 2841 alarms which subsequently expire or are deleted; they will continue to 2842 be archived according to the selected options.</para> 2843 </listitem> 2844 </itemizedlist> 2845 </listitem> 2846 2847 </itemizedlist> 2848 </sect1> 2849 2850 <sect1 id="preferences-email"> 2851 <title>Email</title> 2852 2853 <para>The <guilabel>Email</guilabel> section lets you choose options 2854 for sending and addressing email alarms:</para> 2855 2856 <note><para>Options dependent on &kmail; are only available if &kalarm;'s 2857 <link linkend="akonadi-plugin">Akonadi plugin</link> is installed and 2858 enabled.</para> 2859 </note> 2860 2861 <itemizedlist> 2862 <listitem> 2863 <para><guilabel>Email client</guilabel>: Specify the email 2864 client to be used to send email alarms:</para> 2865 2866 <itemizedlist> 2867 <listitem><para><guilabel>KMail</guilabel>: When an email alarm is 2868 triggered, the email is sent automatically using &kmail;.</para> 2869 </listitem> 2870 2871 <listitem><para><guilabel>Sendmail</guilabel>: When an email alarm is 2872 triggered, the email is sent automatically using 2873 &Sendmail;. This option will only work if 2874 your system is configured to use &Sendmail;, 2875 or a &Sendmail; compatible mail transport 2876 agent such as <application>postfix</application> or 2877 <application>qmail</application>.</para> 2878 </listitem> 2879 </itemizedlist> 2880 </listitem> 2881 2882 <listitem> 2883 <para><guilabel>Copy sent emails into &kmail;'s "sent-mail" folder</guilabel>: 2884 Select this option if, every time an email alarm is triggered, you 2885 want a copy of the transmitted email to be stored in &kmail;'s 2886 <filename>sent-mail</filename> folder.</para> 2887 2888 <note><para>This option is not available when &kmail; is selected as 2889 the email client, since &kmail; automatically does this.</para></note> 2890 </listitem> 2891 2892 <listitem> 2893 <para><guilabel>Notify when remote emails are queued</guilabel>: 2894 Select this option to display a notification whenever an email alarm 2895 queues an email for sending to a remote system. This may be useful 2896 if, for example, you have a dial-up connection, or email is queued in 2897 &kmail;'s <filename>outbox</filename> folder, so that you can 2898 ensure that you do whatever is needed to actually transmit 2899 the email.</para> 2900 </listitem> 2901 2902 <listitem> 2903 <para>Select your email address to be used as the sender's address in 2904 email alarms:</para> 2905 2906 <itemizedlist> 2907 <listitem><para>Select <guilabel>From</guilabel> to enter an email 2908 address.</para> 2909 </listitem> 2910 2911 <listitem><para>Select <guilabel>Use default KMail identity</guilabel> 2912 to use your default email address which is configured in &kmail;.</para> 2913 </listitem> 2914 2915 <listitem><para>Select <guilabel>Use &kmail; identities</guilabel> to 2916 be able to choose at the time you configure an email alarm which of 2917 &kmail;'s email identities to use. &kmail;'s default identity will be 2918 used for alarms which were already configured before you selected this 2919 option.</para> 2920 </listitem> 2921 </itemizedlist> 2922 </listitem> 2923 2924 <listitem> 2925 <para>Select your email address to be used for sending blind copies of 2926 email alarms to yourself when the 2927 <guilabel>Copy email to self</guilabel> option is selected:</para> 2928 2929 <itemizedlist> 2930 <listitem><para>Select <guilabel>Bcc</guilabel> to enter an email 2931 address. If blind copies are to be sent to your account on the 2932 computer which &kalarm; runs on, you could simply enter your user 2933 login name here.</para> 2934 </listitem> 2935 2936 <listitem><para>Select <guilabel>Use default KMail identity</guilabel> 2937 to use your default email address which is configured in &kmail;.</para> 2938 </listitem> 2939 </itemizedlist> 2940 </listitem> 2941 </itemizedlist> 2942 </sect1> 2943 2944 <sect1 id="preferences-view"> 2945 <title>View</title> 2946 2947 <para>The <guilabel>View</guilabel> section lets you control some 2948 aspects of &kalarm;'s appearance. In the <guilabel>General</guilabel> 2949 tab:</para> 2950 <itemizedlist> 2951 2952 <listitem> 2953 <para><guilabel>Show in system tray</guilabel> group box: When 2954 selected, the system tray icon is displayed while &kalarm; is running, 2955 subject to the selected option:</para> 2956 2957 <itemizedlist> 2958 <listitem> 2959 <para><guilabel>Always show</guilabel>: The system tray icon is always 2960 displayed.</para> 2961 </listitem> 2962 2963 <listitem> 2964 <para><guilabel>Automatically hide if no active alarms</guilabel>: 2965 The system tray icon is hidden if there are no active alarms.</para> 2966 </listitem> 2967 2968 <listitem> 2969 <para><guilabel>Automatically hide if no alarm due within time period</guilabel>: 2970 The system tray icon is hidden if no alarm is due within the entered 2971 time period, starting from now.</para> 2972 </listitem> 2973 </itemizedlist> 2974 2975 <para>When the system tray icon is automatically hidden, you can make 2976 it visible by means of the system tray option to show hidden icons.</para> 2977 2978 <para>When <guilabel>Show in system tray</guilabel> is selected, 2979 closing the system tray icon closes all &kalarm; main windows, and if 2980 no message windows are visible, quits the application.</para> 2981 </listitem> 2982 2983 <listitem> 2984 <para><guilabel>System Tray Tooltip</guilabel> group box: These options 2985 control what information is shown in the tooltip which appears when the 2986 mouse cursor hovers over &kalarm;'s system tray icon.</para> 2987 2988 <itemizedlist> 2989 <listitem> 2990 <para><guilabel>Show next 24 hours' alarms</guilabel>: When selected, 2991 a summary of the first few alarms due in the next 24 hours is 2992 displayed.</para> 2993 </listitem> 2994 2995 <listitem> 2996 <para><guilabel>Maximum number of alarms to show</guilabel>: Deselect 2997 this option to display all of the next 24 hours' alarms. Select it to 2998 set the maximum number of alarms which will be displayed.</para> 2999 </listitem> 3000 3001 <listitem> 3002 <para><guilabel>Show alarm time</guilabel>: Select this option to show 3003 the time at which each alarm is scheduled.</para> 3004 </listitem> 3005 3006 <listitem> 3007 <para><guilabel>Show time until alarm</guilabel>: Select this option to 3008 show the length of time remaining before each alarm's next scheduled 3009 occurrence. The length of time is shown in hours and minutes.</para> 3010 3011 <itemizedlist> 3012 <listitem> 3013 <para><guilabel>Prefix</guilabel>: Specify a symbol or text to show in 3014 front of the length of time until the alarm, to distinguish it from the 3015 time at which the alarm is scheduled.</para> 3016 </listitem> 3017 </itemizedlist> 3018 </listitem> 3019 </itemizedlist> 3020 </listitem> 3021 3022 <listitem> 3023 <para>The <guilabel>Alarm List</guilabel> group box allows the 3024 selection of the colors used in the alarm list in &kalarm;'s main 3025 window, to show disabled and archived alarms.</para> 3026 </listitem> 3027 </itemizedlist> 3028 3029 <para>The <guilabel>Alarm Windows</guilabel> tab contains options to control 3030 the appearance of alarm message windows.</para> 3031 3032 <itemizedlist> 3033 <listitem> 3034 <para><guilabel>Position windows far from mouse cursor</guilabel>: 3035 Select this option to display alarm message windows as far away from 3036 the current mouse cursor position as possible. This minimizes the 3037 chance of accidentally acknowledging an alarm by unintentionally 3038 clicking on a button just as the message window appears.</para> 3039 </listitem> 3040 3041 <listitem> 3042 <para><guilabel>Center windows, delay activating window buttons</guilabel>: 3043 Select this option to display alarm message windows in the center of 3044 the screen. To reduce the chance of accidentally acknowledging the 3045 alarm, the window's buttons are initially disabled. The delay in 3046 seconds before they become active is set in 3047 <guilabel>Button activation delay (seconds)</guilabel>.</para> 3048 </listitem> 3049 3050 <listitem> 3051 <para><guilabel>Message windows have a titlebar and take keyboard focus</guilabel>: 3052 This option controls whether alarm message windows are modal or not, 3053 &ie; whether they grab the keyboard focus when they appear. See the 3054 <link linkend="message-display">Alarm Message Display</link> section 3055 for details.</para> 3056 </listitem> 3057 </itemizedlist> 3058 </sect1> 3059 3060 <sect1 id="preferences-edit"> 3061 <title>Edit</title> 3062 3063 <para>The <guilabel>Edit</guilabel> section lets you choose 3064 default values for the options in the 3065 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>:</para> 3066 3067 <itemizedlist> 3068 <listitem><para>The <guilabel>General</guilabel> tab contains options 3069 which apply to all alarm types.</para> 3070 3071 <itemizedlist> 3072 <listitem><para>Set the default method for displaying alarm 3073 messages.</para> 3074 </listitem> 3075 3076 <listitem><para>Set the default states for the <guilabel>Show in 3077 KOrganizer</guilabel> and <guilabel>Cancel if late</guilabel> check 3078 boxes.</para> 3079 </listitem> 3080 3081 <listitem><para>Set the default recurrence type.</para> 3082 </listitem> 3083 3084 <listitem><para>Select the default handling in non-leap years of 3085 yearly recurrences scheduled for February 29th.</para> 3086 </listitem> 3087 </itemizedlist> 3088 </listitem> 3089 3090 <listitem><para>The <guilabel>Alarm Types</guilabel> tab contains 3091 options which apply to specific types of alarm.</para> 3092 3093 <itemizedlist> 3094 <listitem> 3095 <para>For display alarms:</para> 3096 3097 <itemizedlist> 3098 <listitem><para>Set the default states for the 3099 <guilabel>Auto-close window after this time</guilabel> and 3100 <guilabel>Confirm acknowledgment</guilabel> check boxes.</para> 3101 </listitem> 3102 3103 <listitem><para>Set the default reminder period units.</para> 3104 </listitem> 3105 3106 <listitem><para>Set the default special display alarm actions.</para> 3107 </listitem> 3108 3109 <listitem><para>Set the default sound options. Note that a default 3110 sound file may be specified even if the sound type is not set to 3111 <guilabel>Sound file</guilabel>.</para> 3112 </listitem> 3113 </itemizedlist> 3114 </listitem> 3115 3116 <listitem> 3117 <para>For command alarms:</para> 3118 3119 <itemizedlist> 3120 <listitem><para>Set the default states for the <guilabel>Enter a 3121 script</guilabel> and <guilabel>Execute in terminal window</guilabel> 3122 check boxes.</para> 3123 </listitem> 3124 </itemizedlist> 3125 </listitem> 3126 3127 <listitem> 3128 <para>For email alarms:</para> 3129 3130 <itemizedlist> 3131 <listitem><para>Set the default state for the <guilabel>Copy email to 3132 self</guilabel> check box.</para> 3133 </listitem> 3134 </itemizedlist> 3135 </listitem> 3136 </itemizedlist> 3137 </listitem> 3138 3139 <listitem><para>The <guilabel>Font & Color</guilabel> tab lets you 3140 set the default appearance of alarm messages. Select their default 3141 font, and foreground and background colors.</para> 3142 </listitem> 3143 </itemizedlist> 3144 </sect1> 3145 3146 </chapter> 3147 3148 <chapter id="cmdline-operation"> 3149 <title>Command Line Operation</title> 3150 3151 <para>When command line parameters are supplied, &kalarm; does not 3152 display the list of scheduled alarms as described in <link 3153 linkend="using-kalarm">Using &kalarm;</link> above. Command line 3154 options specific to &kalarm; may be used to perform the following 3155 operations:</para> 3156 3157 <itemizedlist> 3158 <listitem><para>schedule a new alarm</para> 3159 </listitem> 3160 <listitem><para>control &kalarm;'s display mode</para> 3161 </listitem> 3162 <listitem><para>obtain help</para> 3163 </listitem> 3164 </itemizedlist> 3165 3166 <para>Additional command line options are provided primarily to enable 3167 other programs to interface to &kalarm;. They are described in the 3168 chapter <link linkend="cmdline-interface">Developer's Guide to 3169 &kalarm;</link>.</para> 3170 3171 <para>The command line must only contain options applicable to one 3172 &kalarm; operation. If you want to perform multiple operations, you 3173 must invoke &kalarm; multiple times with a single set of options each 3174 time.</para> 3175 3176 <sect1 id="cmdline-schedule"> 3177 <title>Schedule a New Alarm</title> 3178 3179 <para>The following options are used to schedule a new alarm:</para> 3180 3181 <informaltable> 3182 <tgroup cols="2"> 3183 <thead> 3184 <row> 3185 <entry>Option</entry> 3186 <entry>Description</entry> 3187 </row> 3188 </thead> 3189 <tbody> 3190 <row> 3191 <entry><option>-a</option>, <option>--ack-confirm</option></entry> 3192 <entry>Prompt for confirmation when the alarm message is 3193 acknowledged.</entry> 3194 </row> 3195 <row> 3196 <entry><option>-A</option>, <option>--attach <replaceable>URL</replaceable></option></entry> 3197 <entry>Specify the path or &URL; of a file which is to be attached 3198 to the email. This option may be repeated as necessary. 3199 <option>--mail</option> must be specified with this option.</entry> 3200 </row> 3201 <row> 3202 <entry><option>--auto-close</option></entry> 3203 <entry>Automatically close the alarm window after the expiry of the 3204 <option>--late-cancel</option> period. 3205 <option>--late-cancel</option> must be specified with this 3206 option.</entry> 3207 </row> 3208 <row> 3209 <entry><option>-b</option>, <option>--beep</option></entry> 3210 <entry>Make an audible beep when the message is displayed. 3211 <option>--speak</option>, <option>--play</option> and 3212 <option>--play-repeat</option> cannot be specified with this 3213 option.</entry> 3214 </row> 3215 <row> 3216 <entry><option>--bcc</option></entry> 3217 <entry>Blind copy the email to yourself. 3218 <option>--mail</option> must be specified with this option.</entry> 3219 </row> 3220 <row> 3221 <entry><option>-c</option>, <option>--color</option>, <option>--colour 3222 <replaceable>color</replaceable></option></entry> 3223 <entry>Set the message background color to the specified &Qt; 3224 color name or hex code 0xRRGGBB.</entry> 3225 </row> 3226 <row> 3227 <entry><option>-C</option>, <option>--colorfg</option>, <option>--colourfg 3228 <replaceable>color</replaceable></option></entry> 3229 <entry>Set the message foreground color to the specified &Qt; 3230 color name or hex code 0xRRGGBB.</entry> 3231 </row> 3232 <row> 3233 <entry><option>-d</option>, <option>--disable</option></entry> 3234 <entry>Disable the alarm. It will not trigger until it has been 3235 manually enabled.</entry> 3236 </row> 3237 <row> 3238 <entry><option>--disable-all</option></entry> 3239 <entry>Disable alarm monitoring. This prevents any alarms from 3240 being triggered until you re-enable alarms or restart &kalarm;, ⪚ 3241 at next login. 3242 <option>--triggerEvent</option> cannot be specified with this 3243 option.</entry> 3244 </row> 3245 <row> 3246 <entry><option>-e</option>, <option>--exec <replaceable>commandline</replaceable></option></entry> 3247 <entry>Specify a shell command to execute. If specified, this option 3248 must be the last &kalarm; option in &kalarm;'s command line. All 3249 subsequent command parameters and options are interpreted as 3250 forming the command line to execute. <option>--file</option> and 3251 <option>--exec-display</option> and <option>--mail</option> cannot 3252 be specified with this option. 3253 <option>--ack-confirm</option>, <option>--beep</option>, 3254 <option>--color</option> and <option>--colorfg</option> are ignored 3255 with this option.</entry> 3256 </row> 3257 <row> 3258 <entry><option>-E</option>, <option>--exec-display <replaceable>commandline</replaceable></option></entry> 3259 <entry>Specify a shell command to execute to generate the alarm 3260 message text. If specified, this option must be the last &kalarm; 3261 option in &kalarm;'s command line. All subsequent command parameters 3262 and options are interpreted as forming the command line to execute. 3263 <option>--exec</option>, <option>--file</option> and 3264 <option>--mail</option> cannot be specified with this option.</entry> 3265 </row> 3266 <row> 3267 <entry><option>-f</option>, <option>--file <replaceable>URL</replaceable></option></entry> 3268 <entry>Specify the path or &URL; of a text or image file whose 3269 contents are to form the alarm message. <option>--exec</option>, 3270 <option>--exec-display</option> and <option>--mail</option> cannot 3271 be specified, and <replaceable>message</replaceable> must not be 3272 present with this option.</entry> 3273 </row> 3274 <row> 3275 <entry><option>-F</option>, <option>--from-id 3276 <replaceable>ID</replaceable></option></entry> 3277 <entry>Use the specified &kmail; identity as the sender of the 3278 email. <option>--mail</option> must be specified with this 3279 option.</entry> 3280 </row> 3281 <row> 3282 <entry><option>-i</option>, <option>--interval 3283 <replaceable>period</replaceable></option></entry> 3284 <entry>Set the interval between repetitions of the alarm. 3285 Hours/minutes are specified in the format 3286 <replaceable>nHnM</replaceable>, where <replaceable>n</replaceable> 3287 is a number, ⪚ 3H30M. Other time periods are specified in the 3288 format <replaceable>nX</replaceable>, where 3289 <replaceable>n</replaceable> is a number and 3290 <replaceable>X</replaceable> is one of the following letters: Y 3291 (years), M (months), W (weeks), D (days). If 3292 <option>--recurrence</option> is also specified, Y (years) and M 3293 (months) are not allowed. 3294 Mandatory if <option>--repeat</option> or <option>--until</option> 3295 is specified.</entry> 3296 </row> 3297 <row> 3298 <entry><option>-k</option>, <option>--korganizer</option></entry> 3299 <entry>Show the alarm as an event in &korganizer;'s active 3300 calendar.</entry> 3301 </row> 3302 <row> 3303 <entry><option>-l</option>, <option>--late-cancel 3304 <replaceable>period</replaceable></option></entry> 3305 <entry>Cancel the alarm if it cannot be triggered within the 3306 specified <replaceable>period</replaceable> after the correct time. 3307 Hours/minutes are specified in the format 3308 <replaceable>nHnM</replaceable>, where <replaceable>n</replaceable> 3309 is a number, ⪚ 3H30M. Other time periods are specified in the 3310 format <replaceable>nX</replaceable>, where 3311 <replaceable>n</replaceable> is a number and 3312 <replaceable>X</replaceable> is one of the following letters: W 3313 (weeks), D (days). 3314 The default value of <replaceable>period</replaceable> is 1 3315 minute.</entry> 3316 </row> 3317 <row> 3318 <entry><option>-L</option>, <option>--login</option></entry> 3319 <entry>Trigger the alarm every time you log in. 3320 <option>--interval</option>, <option>--repeat</option> and 3321 <option>--until</option> cannot be specified with this 3322 option.</entry> 3323 </row> 3324 <row> 3325 <entry><option>-m</option>, <option>--mail 3326 <replaceable>address</replaceable></option></entry> 3327 <entry>Send an email to the specified address. This option may be 3328 repeated as necessary. <option>--exec</option>, 3329 <option>--exec-display</option> and <option>--file</option> cannot 3330 be specified with this option. 3331 <option>--ack-confirm</option>, <option>--beep</option>, 3332 <option>--color</option> and <option>--colorfg</option> are ignored 3333 with this option.</entry> 3334 </row> 3335 <row> 3336 <entry><option>-n</option>, <option>--name</option></entry> 3337 <entry>Specify a name to help you to identify the alarm.</entry> 3338 </row> 3339 <row> 3340 <entry><option>-N</option>, <option>--notify</option></entry> 3341 <entry>Display the alarm as a notification, not in a window. 3342 <option>--color</option>, <option>--colorfg</option>, 3343 <option>--play</option>, <option>--ack-confirm</option> and 3344 <option>--auto-close</option> cannot be specified with this 3345 option.</entry> 3346 </row> 3347 <row> 3348 <entry><option>-p</option>, <option>--play <replaceable>URL</replaceable></option></entry> 3349 <entry>Specify the path or &URL; of an audio file to be played once, 3350 either as an audio alarm or when the alarm message is displayed. 3351 <option>--play-repeat</option>, <option>--beep</option> and 3352 <option>--speak</option> cannot be specified with this 3353 option.</entry> 3354 </row> 3355 <row> 3356 <entry><option>-P</option>, <option>--play-repeat <replaceable>URL</replaceable></option></entry> 3357 <entry>Specify the path or &URL; of an audio file to be played 3358 repeatedly, either until <guilabel>Stop Play</guilabel> is used, or 3359 for as long as the alarm message is displayed. 3360 <option>--play</option>, <option>--beep</option> and 3361 <option>--speak</option> cannot be specified with this 3362 option.</entry> 3363 </row> 3364 <row> 3365 <entry><option>--recurrence 3366 <replaceable>spec</replaceable></option></entry> 3367 <entry>Set the alarm to recur. Specify the recurrence using iCalendar 3368 syntax (defined in 3369 <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>), 3370 ⪚ <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote>. 3371 <option>--until</option> cannot be specified with this 3372 option.</entry> 3373 </row> 3374 <row> 3375 <entry><option>-r</option>, <option>--repeat 3376 <replaceable>count</replaceable></option></entry> 3377 <entry>Set the number of times the alarm should be triggered, or if 3378 a recurrence is specified with <option>--recurrence</option>, the 3379 number of times the alarm should be triggered each time 3380 <option>--recurrence</option> activates it (&ie; a repetition within 3381 a recurrence). If <option>--recurrence</option> is not present, 3382 specify -1 to repeat the alarm indefinitely. 3383 <option>--interval</option> must be, and <option>--until</option> 3384 cannot be, specified with this option.</entry> 3385 </row> 3386 <row> 3387 <entry><option>-R</option>, <option>--reminder 3388 <replaceable>period</replaceable></option></entry> 3389 <entry>Output a reminder alarm the specified length of time before 3390 or after the main alarm and each of its recurrences (if any). 3391 The <replaceable>period</replaceable> is specified in 3392 the same format as described for <option>--late-cancel</option>. 3393 By default, the reminder will occur before the alarm. To specify a 3394 reminder after the alarm, prefix <replaceable>period</replaceable> 3395 with <replaceable>+</replaceable>, ⪚ +3D. This option cannot be 3396 specified with <option>--exec</option>, <option>--mail</option> or 3397 <option>--reminder-once</option>.</entry> 3398 </row> 3399 <row> 3400 <entry><option>--reminder-once 3401 <replaceable>period</replaceable></option></entry> 3402 <entry>Output a reminder alarm once, the specified length of time 3403 before or after the first recurrence of the alarm. No reminder will 3404 be displayed before or after subsequent recurrences (if any). The 3405 <replaceable>period</replaceable> is specified in the same format as 3406 described for <option>--reminder</option>. This option cannot 3407 be specified with <option>--exec</option>, <option>--mail</option> 3408 or <option>--reminder</option>.</entry> 3409 </row> 3410 <row> 3411 <entry><option>-s</option>, <option>--speak</option></entry> 3412 <entry>Speak the message when it is displayed. This option requires 3413 &kalarm; to have been built with speech enabled and the &Qt; Speech 3414 module to be installed and working. <option>--beep</option>, 3415 <option>--play</option> and <option>--play-repeat</option> cannot be 3416 specified with this option.</entry> 3417 </row> 3418 <row> 3419 <entry><option>-S</option>, <option>--subject 3420 <replaceable>subject</replaceable></option></entry> 3421 <entry>The subject line of the email. <option>--mail</option> must 3422 be specified with this option.</entry> 3423 </row> 3424 <!-- test-set-time time (debug mode)--> 3425 <row> 3426 <entry><option>-t</option>, <option>--time 3427 <replaceable>date/time</replaceable></option></entry> 3428 <entry>Trigger alarm on the date or at the date/time specified. 3429 Specify a date without a time in the format 3430 <replaceable>yyyy-mm-dd[ TZ]</replaceable>; specify a date and time 3431 by <replaceable>[[[yyyy-]mm-]dd-]hh:mm[ TZ]</replaceable> (where 3432 omitted, date fields default to the values for today). 3433 If no time zone is specified, the local system time zone is 3434 assumed. If a time zone specifier <replaceable>TZ</replaceable> is 3435 present, it may be the name of a system time zone (⪚ 3436 <userinput>Europe/London</userinput>), or <userinput>UTC</userinput> 3437 representing the UTC time zone.</entry> 3438 </row> 3439 <row> 3440 <entry><option>-v</option>, <option>--volume 3441 <replaceable>percentage</replaceable></option></entry> 3442 <entry>Set the audio volume for playing the audio file. This option 3443 can only be used when <option>--play</option> or 3444 <option>--play-repeat</option> is specified.</entry> 3445 </row> 3446 <row> 3447 <entry><option>-u</option>, <option>--until 3448 <replaceable>date/time</replaceable></option></entry> 3449 <entry>Repeat the alarm until the date or date/time specified. 3450 Specify the date or date/time using the same syntax as for 3451 <option>--time</option>. Note that if <option>--time</option> is 3452 specified, the time zone will be taken from its value and no time 3453 zone may be included in the <option>--until</option> value. 3454 <option>--interval</option> must be, and 3455 <option>--repeat</option> and <option>--recurrence</option> cannot 3456 be, specified with this option.</entry> 3457 </row> 3458 <row> 3459 <entry><replaceable>message</replaceable></entry> 3460 <entry>Message text to display or, if <option>--mail</option> is 3461 specified, the body of the email message.</entry> 3462 </row> 3463 </tbody> 3464 </tgroup> 3465 </informaltable> 3466 3467 <para>Either a message text, <option>--file</option>, 3468 <option>--exec</option>, <option>--exec-display</option>, 3469 <option>--play</option> or <option>--play-repeat</option> must be 3470 specified; except as noted above, all the options are optional.</para> 3471 3472 <para>Two alternative examples which display a multi-line message with 3473 a red background at 10 p.m. on the 27th of this month are:</para> 3474 3475 <informalexample><screen> 3476 <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> 3477 <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> 3478 </screen> 3479 </informalexample> 3480 3481 </sect1> 3482 3483 <sect1 id="cmdline-other"> 3484 <title>Other Options</title> 3485 3486 <para>The following options are used to perform various functions, 3487 including displaying the 3488 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link>.</para> 3489 3490 <informaltable> 3491 <tgroup cols="2"> 3492 <thead> 3493 <row> 3494 <entry>Option</entry> 3495 <entry>Description</entry> 3496 </row> 3497 </thead> 3498 <tbody> 3499 <row> 3500 <entry><option>--edit <replaceable>eventID</replaceable></option></entry> 3501 <entry>Display the Alarm Edit dialog to edit the alarm with the 3502 specified event ID. The event ID is the unique ID of the event, optionally 3503 prefixed by the configuration name or numeric ID of the resource containing 3504 the event, in the format 3505 <replaceable>[resourceID:]eventUID</replaceable>.</entry> 3506 </row> 3507 <row> 3508 <entry><option>--edit-new-audio</option></entry> 3509 <entry>Display the Alarm Edit dialog, in order to edit a new audio 3510 alarm.</entry> 3511 </row> 3512 <row> 3513 <entry><option>--edit-new-command</option></entry> 3514 <entry>Display the Alarm Edit dialog, in order to edit a new command 3515 alarm.</entry> 3516 </row> 3517 <row> 3518 <entry><option>--edit-new-display</option></entry> 3519 <entry>Display the Alarm Edit dialog, in order to edit a new display 3520 alarm.</entry> 3521 </row> 3522 <row> 3523 <entry><option>--edit-new-email</option></entry> 3524 <entry>Display the Alarm Edit dialog, in order to edit a new email 3525 alarm.</entry> 3526 </row> 3527 <row> 3528 <entry><option>--edit-new-preset <replaceable>templateName</replaceable></option></entry> 3529 <entry>Display the Alarm Edit dialog, preset with the alarm template 3530 of the specified name, in order to edit a new alarm.</entry> 3531 </row> 3532 <row> 3533 <entry><option>--list</option></entry> 3534 <entry>Output a list of scheduled alarms to <filename>stdout</filename>. 3535 The list shows brief details of each pending alarm: its resource 3536 identifier, UID, next scheduled time and message text or file.</entry> 3537 </row> 3538 <row> 3539 <entry><option>--tray</option></entry> 3540 <entry>Display &kalarm; as an icon in the system tray.</entry> 3541 </row> 3542 <row> 3543 <entry><option>--disable-all</option></entry> 3544 <entry>Disable monitoring of all alarms.</entry> 3545 </row> 3546 </tbody> 3547 </tgroup> 3548 </informaltable> 3549 3550 <para>See also:</para> 3551 <simplelist> 3552 <member>kf5options(7)</member> 3553 <member>qt5options(7)</member> 3554 </simplelist> 3555 3556 </sect1> 3557 3558 </chapter> 3559 3560 <chapter id="developers"> 3561 <title>Developer's Guide to &kalarm;</title> 3562 3563 <para>&kalarm; provides an interface to allow other applications to 3564 request the following functions:</para> 3565 3566 <itemizedlist> 3567 <listitem><para>schedule a new alarm</para></listitem> 3568 <listitem><para>cancel an already scheduled alarm</para></listitem> 3569 <listitem><para>trigger an already scheduled alarm</para></listitem> 3570 <listitem><para>display the Alarm Edit dialog</para></listitem> 3571 <listitem><para>list scheduled alarms</para></listitem> 3572 </itemizedlist> 3573 3574 <para>Each of the above functions is implemented both by a &DBus; call 3575 and by the command line. &DBus; calls should be used in preference if 3576 &kalarm; is already running.</para> 3577 3578 <sect1 id="dbus-interface"> 3579 <title>&DBus; Interface</title> 3580 3581 <para>The &DBus; calls described in this document are all implemented 3582 in &kalarm;'s <constant>/kalarm</constant> &DBus; object path. The 3583 interface is defined in the files 3584 <filename>org.kde.kalarm.kalarm.xml</filename> and 3585 <filename>kalarmiface.h</filename>.</para> 3586 3587 <refentry id="cancelEvent"> 3588 <refmeta> 3589 <refentrytitle>cancelEvent</refentrytitle> 3590 </refmeta> 3591 <refnamediv> 3592 <refname>cancelEvent</refname> 3593 <refpurpose>cancel an already scheduled alarm.</refpurpose> 3594 </refnamediv> 3595 <refsynopsisdiv> 3596 <synopsis> 3597 void cancelEvent(const QString& <replaceable>eventID</replaceable>) 3598 </synopsis> 3599 3600 <refsect2> 3601 <title>Parameters</title> 3602 <variablelist> 3603 <varlistentry> 3604 <term><parameter>eventID</parameter></term> 3605 <listitem> 3606 <para>Specifies the unique ID of the event to be canceled, optionally 3607 prefixed by the configuration name or numeric ID of the resource containing 3608 the event, in the format 3609 <replaceable>[resourceID:]eventUID</replaceable>.</para> 3610 </listitem> 3611 </varlistentry> 3612 </variablelist> 3613 </refsect2> 3614 </refsynopsisdiv> 3615 3616 <refsect1> 3617 <title>Description</title> 3618 3619 <para><function>cancelEvent()</function> is a &DBus; call to cancel 3620 the specified alarm. &kalarm; deletes the alarm from the calendar 3621 without displaying or executing it.</para> 3622 3623 </refsect1> 3624 </refentry> 3625 3626 <refentry id="triggerEvent"> 3627 <refmeta> 3628 <refentrytitle>triggerEvent</refentrytitle> 3629 </refmeta> 3630 <refnamediv> 3631 <refname>triggerEvent</refname> 3632 <refpurpose>trigger an already scheduled alarm.</refpurpose> 3633 </refnamediv> 3634 <refsynopsisdiv> 3635 <synopsis> 3636 void triggerEvent(const QString& <replaceable>eventID</replaceable>) 3637 </synopsis> 3638 3639 <refsect2> 3640 <title>Parameters</title> 3641 <variablelist> 3642 <varlistentry> 3643 <term><parameter>eventID</parameter></term> 3644 <listitem> 3645 <para>Specifies the unique ID of the event to be triggered, optionally 3646 prefixed by the configuration name or numeric ID of the resource containing 3647 the event, in the format 3648 <replaceable>[resourceID:]eventUID</replaceable>.</para> 3649 </listitem> 3650 </varlistentry> 3651 </variablelist> 3652 </refsect2> 3653 </refsynopsisdiv> 3654 3655 <refsect1> 3656 <title>Description</title> 3657 3658 <para><function>triggerEvent()</function> is a &DBus; call to trigger 3659 the immediate display or execution of the specified alarm (regardless 3660 of what time it is scheduled for). &kalarm; retrieves the alarm from 3661 the calendar and then displays or executes it.</para> 3662 3663 <para>If the alarm is already due, &kalarm; then deletes all scheduled 3664 occurrences of the alarm up to the current time, and if no repetitions 3665 of the alarm still remain, the alarm is deleted from the calendar. If 3666 the alarm is not due yet, its scheduled occurrences are left 3667 unchanged.</para> 3668 3669 </refsect1> 3670 </refentry> 3671 3672 <refentry id="scheduleMessage"> 3673 <refmeta> 3674 <refentrytitle>scheduleMessage</refentrytitle> 3675 </refmeta> 3676 <refnamediv> 3677 <refname>scheduleMessage</refname> 3678 <refpurpose>schedule a new alarm message.</refpurpose> 3679 </refnamediv> 3680 <refsynopsisdiv> 3681 <synopsis> 3682 bool scheduleMessage(const QString& <replaceable>name</replaceable>, 3683 const QString& <replaceable>message</replaceable>, 3684 const QString& <replaceable>startDateTime</replaceable>, 3685 int <replaceable>lateCancel</replaceable>, 3686 unsigned <replaceable>flags</replaceable>, 3687 const QString& <replaceable>bgColor</replaceable>, 3688 const QString& <replaceable>fgColor</replaceable>, 3689 const QString& <replaceable>font</replaceable>, 3690 const QString& <replaceable>audioURL</replaceable>, 3691 int <replaceable>reminderMins</replaceable>, 3692 const QString& <replaceable>recurrence</replaceable>, 3693 int <replaceable>subRepeatInterval</replaceable>, 3694 int <replaceable>subRepeatCount</replaceable>) 3695 </synopsis> 3696 <synopsis> 3697 bool scheduleMessage(const QString& <replaceable>name</replaceable>, 3698 const QString& <replaceable>message</replaceable>, 3699 const QString& <replaceable>startDateTime</replaceable>, 3700 int <replaceable>lateCancel</replaceable>, 3701 unsigned <replaceable>flags</replaceable>, 3702 const QString& <replaceable>bgColor</replaceable>, 3703 const QString& <replaceable>fgColor</replaceable>, 3704 const QString& <replaceable>font</replaceable>, 3705 const QString& <replaceable>audioURL</replaceable>, 3706 int <replaceable>reminderMins</replaceable>, 3707 int <replaceable>recurType</replaceable>, 3708 int <replaceable>recurInterval</replaceable>, 3709 int <replaceable>recurCount</replaceable>) 3710 </synopsis> 3711 <synopsis> 3712 bool scheduleMessage(const QString& <replaceable>name</replaceable>, 3713 const QString& <replaceable>message</replaceable>, 3714 const QString& <replaceable>startDateTime</replaceable>, 3715 int <replaceable>lateCancel</replaceable>, 3716 unsigned <replaceable>flags</replaceable>, 3717 const QString& <replaceable>bgColor</replaceable>, 3718 const QString& <replaceable>fgColor</replaceable>, 3719 const QString& <replaceable>font</replaceable>, 3720 const QString& <replaceable>audioURL</replaceable>, 3721 int <replaceable>reminderMins</replaceable>, 3722 int <replaceable>recurType</replaceable>, 3723 int <replaceable>recurInterval</replaceable>, 3724 const QString& <replaceable>endDateTime</replaceable>) 3725 </synopsis> 3726 3727 <refsect2> 3728 <title>Parameters</title> 3729 <variablelist> 3730 <varlistentry> 3731 <term><parameter>name</parameter></term> 3732 <listitem> 3733 <para>Specifies an optional name for the alarm.</para> 3734 </listitem> 3735 </varlistentry> 3736 3737 <varlistentry> 3738 <term><parameter>message</parameter></term> 3739 <listitem> 3740 <para>Specifies the text of the message to be scheduled, or if 3741 <parameter>flags</parameter> has the 3742 <userinput>DISPLAY_COMMAND</userinput> bit set, specifies the command 3743 line to execute to generate the message text.</para> 3744 </listitem> 3745 </varlistentry> 3746 3747 <varlistentry> 3748 <term><parameter>startDateTime</parameter></term> 3749 <listitem> 3750 <para>Specifies the scheduled date, or date and time, at which the 3751 message should be displayed. For a date-only alarm, the string should 3752 be in the format <replaceable>YYYY-MM-DD[ TZ]</replaceable> (as 3753 returned by <methodname>QDate::toString(Qt::ISODate)</methodname>). For 3754 an alarm with a date and time, the string should be in the format 3755 <replaceable>YYYY-MM-DDTHH:MM[:SS][ TZ]</replaceable> (as returned by 3756 <methodname>QDateTime::toString(Qt::ISODate)</methodname>) or 3757 <replaceable>HH:MM[:SS]</replaceable> (as returned by 3758 <methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is 3759 specified, today's date is used. Note that any seconds value is 3760 ignored.</para> 3761 3762 <para>If no time zone is specified, the local system time zone is 3763 assumed. If a time zone specifier <replaceable>TZ</replaceable> is 3764 present, it may be the name of a system time zone (⪚ 3765 <userinput>Europe/London</userinput>), or <userinput>UTC</userinput> 3766 representing the UTC time zone.</para> 3767 </listitem> 3768 </varlistentry> 3769 3770 <varlistentry> 3771 <term><parameter>lateCancel</parameter></term> 3772 <listitem> 3773 <para>Causes the alarm to be canceled if it cannot be triggered within 3774 the specified number of minutes after the alarm's scheduled time. If 3775 the value is 0, the alarm will not be canceled no matter how late it 3776 is triggered.</para> 3777 </listitem> 3778 </varlistentry> 3779 3780 <varlistentry> 3781 <term><parameter>flags</parameter></term> 3782 <listitem> 3783 <para>Specifies the logical OR of the desired alarm flags. The flag 3784 bits are those defined in class <classname>KAlarmIface</classname> in 3785 <filename>kalarmiface.h</filename>. Note that not all flag bits are 3786 applicable to message alarms.</para> 3787 </listitem> 3788 </varlistentry> 3789 3790 <varlistentry> 3791 <term><parameter>bgColor</parameter></term> 3792 <listitem> 3793 <para>Specifies the background color for displaying the message. The 3794 string may be in the format <quote>#RRGGBB</quote> (as returned by 3795 <methodname>QColor::name()</methodname>) where RR, GG and BB are 3796 two-digit hexadecimal values for red, green and blue. Alternatively 3797 the string may be in any of the other formats accepted by 3798 <methodname>QColor::setNamedColor()</methodname>, such as a name from 3799 the X color database (⪚ <quote>red</quote> or 3800 <quote>steelblue</quote>). Set the string to null to specify the 3801 current default background color.</para> 3802 </listitem> 3803 </varlistentry> 3804 3805 <varlistentry> 3806 <term><parameter>fgColor</parameter></term> 3807 <listitem> 3808 <para>Specifies the foreground color for displaying the message. The 3809 format of the string is the same as for 3810 <parameter>bgColor</parameter>, or alternatively set the string to 3811 null to specify the current default foreground color.</para> 3812 </listitem> 3813 </varlistentry> 3814 3815 <varlistentry> 3816 <term><parameter>font</parameter></term> 3817 <listitem> 3818 <para>Specifies the font for displaying the message. The format of the 3819 string is that output by <methodname>QFont::toString()</methodname>. 3820 Set the string to null to use the default message font current at the 3821 time the message is displayed.</para> 3822 </listitem> 3823 </varlistentry> 3824 3825 <varlistentry> 3826 <term><parameter>audioURL</parameter></term> 3827 <listitem> 3828 <para>Specifies the audio file which is to be played when the message 3829 is displayed. Set the value to null if no audio file is to be 3830 played.</para> 3831 </listitem> 3832 </varlistentry> 3833 3834 <varlistentry> 3835 <term><parameter>reminderMins</parameter></term> 3836 <listitem> 3837 <para>Specifies the number of minutes in advance of the main alarm and 3838 of each of its recurrences (if any) at which a reminder alarm should 3839 be displayed. Specify a negative value for a reminder to be displayed 3840 after the main alarm. Specify 0 if no reminder is required.</para> 3841 </listitem> 3842 </varlistentry> 3843 3844 <varlistentry> 3845 <term><parameter>recurrence</parameter></term> 3846 <listitem> 3847 <para>Specifies a regular recurrence for the alarm, using iCalendar 3848 syntax as defined in 3849 <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. 3850 For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> 3851 would specify 4 repetitions at 3-monthly intervals on the last Monday 3852 of the month. For a non-recurring alarm, specify an empty 3853 string.</para> 3854 </listitem> 3855 </varlistentry> 3856 3857 <varlistentry> 3858 <term><parameter>recurType</parameter></term> 3859 <listitem> 3860 <para>Specifies the recurrence type for the alarm. The permissible 3861 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These 3862 are defined in class <classname>KAlarmIface</classname> in 3863 <filename>kalarmiface.h</filename>. Monthly recurrences are of the 3864 day of the month type, and yearly recurrences are of the date in 3865 the year type, with the date in both cases taken from the 3866 <parameter>startDateTime</parameter> parameter.</para> 3867 </listitem> 3868 </varlistentry> 3869 3870 <varlistentry> 3871 <term><parameter>recurInterval</parameter></term> 3872 <listitem> 3873 <para>Specifies the number of periods 3874 (minutes/days/weeks/months/years as specified by 3875 <parameter>recurType</parameter>) between recurrences of the 3876 alarm.</para> 3877 </listitem> 3878 </varlistentry> 3879 3880 <varlistentry> 3881 <term><parameter>recurCount</parameter></term> 3882 <listitem> 3883 <para>Specifies the number of times that the alarm should be 3884 repeated. Specify -1 to repeat the alarm indefinitely.</para> 3885 </listitem> 3886 </varlistentry> 3887 3888 <varlistentry> 3889 <term><parameter>endDateTime</parameter></term> 3890 <listitem> 3891 <para>Specifies the end date, or date and time, for recurrences of the 3892 alarm. If <parameter>startDateTime</parameter> includes a time, this 3893 parameter must also include a time; if <parameter>startDateTime</parameter> 3894 contains only a date, this parameter must also contain only a 3895 date. It must not contain a time zone specifier; the same time zone as 3896 for <parameter>startDateTime</parameter> is used to interpret this 3897 parameter's value.</para> 3898 </listitem> 3899 </varlistentry> 3900 3901 <varlistentry> 3902 <term><parameter>subRepeatInterval</parameter></term> 3903 <listitem> 3904 <para>Specifies the number of minutes between sub-repetitions of 3905 the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence 3906 is specified.</para> 3907 </listitem> 3908 </varlistentry> 3909 3910 <varlistentry> 3911 <term><parameter>subRepeatCount</parameter></term> 3912 <listitem> 3913 <para>Specifies the number of sub-repetitions of the alarm, 3914 including the initial occurrence.</para> 3915 </listitem> 3916 </varlistentry> 3917 </variablelist> 3918 </refsect2> 3919 </refsynopsisdiv> 3920 3921 <refsect1 id="scheduleMessage-descrip"> 3922 <title>Description</title> 3923 <para><function>scheduleMessage()</function> is a &DBus; call to 3924 schedule the specified alarm message for display at the specified date 3925 and time. It has three forms. The most general form allows an 3926 arbitrary recurrence to be specified – use this also for 3927 non-repeating alarms. The other forms provide convenient access to a 3928 restricted set of alarm recurrence types, one specifying a repetition 3929 count and the other an end time.</para> 3930 3931 <para>If the scheduled time (including any repetitions) has already 3932 passed, &kalarm; immediately displays the message (unless the 3933 <parameter>lateCancel</parameter> value indicates that it is now too 3934 late to display the alarm, in which case &kalarm; ignores the 3935 request). If the scheduled time (or a repetition) is in the future, 3936 &kalarm; adds the alarm message to the default active alarm calendar 3937 for later display.</para> 3938 </refsect1> 3939 </refentry> 3940 3941 <refentry id="scheduleFile"> 3942 <refmeta> 3943 <refentrytitle>scheduleFile</refentrytitle> 3944 </refmeta> 3945 <refnamediv> 3946 <refname>scheduleFile</refname> 3947 <refpurpose>schedule a new alarm which displays the contents of a 3948 text or image file.</refpurpose> 3949 </refnamediv> 3950 <refsynopsisdiv> 3951 <synopsis> 3952 bool scheduleFile(const QString& <replaceable>name</replaceable>, 3953 const QString& <replaceable>URL</replaceable>, 3954 const QString& <replaceable>startDateTime</replaceable>, 3955 int <replaceable>lateCancel</replaceable>, 3956 unsigned <replaceable>flags</replaceable>, 3957 const QString& <replaceable>bgColor</replaceable>, 3958 const QString& <replaceable>audioURL</replaceable>, 3959 int <replaceable>reminderMins</replaceable>, 3960 const QString& <replaceable>recurrence</replaceable>, 3961 int <replaceable>subRepeatInterval</replaceable>, 3962 int <replaceable>subRepeatCount</replaceable>) 3963 </synopsis> 3964 <synopsis> 3965 bool scheduleFile(const QString& <replaceable>name</replaceable>, 3966 const QString& <replaceable>URL</replaceable>, 3967 const QString& <replaceable>startDateTime</replaceable>, 3968 int <replaceable>lateCancel</replaceable>, 3969 unsigned <replaceable>flags</replaceable>, 3970 const QString& <replaceable>bgColor</replaceable>, 3971 const QString& <replaceable>audioURL</replaceable>, 3972 int <replaceable>reminderMins</replaceable>, 3973 int <replaceable>recurType</replaceable>, 3974 int <replaceable>recurInterval</replaceable>, 3975 int <replaceable>recurCount</replaceable>) 3976 </synopsis> 3977 <synopsis> 3978 bool scheduleFile(const QString& <replaceable>name</replaceable>, 3979 const QString& <replaceable>URL</replaceable>, 3980 const QString& <replaceable>startDateTime</replaceable>, 3981 int <replaceable>lateCancel</replaceable>, 3982 unsigned <replaceable>flags</replaceable>, 3983 const QString& <replaceable>bgColor</replaceable>, 3984 const QString& <replaceable>audioURL</replaceable>, 3985 int <replaceable>reminderMins</replaceable>, 3986 int <replaceable>recurType</replaceable>, 3987 int <replaceable>recurInterval</replaceable>, 3988 const QString& <replaceable>endDateTime</replaceable>) 3989 </synopsis> 3990 3991 <refsect2> 3992 <title>Parameters</title> 3993 <variablelist> 3994 <varlistentry> 3995 <term><parameter>name</parameter></term> 3996 <listitem> 3997 <para>Specifies an optional name for the alarm.</para> 3998 </listitem> 3999 </varlistentry> 4000 4001 <varlistentry> 4002 <term><parameter>URL</parameter></term> 4003 <listitem> 4004 <para>Specifies the text or image file whose contents are to be 4005 displayed in the message to be scheduled.</para> 4006 </listitem> 4007 </varlistentry> 4008 4009 <varlistentry> 4010 <term><parameter>startDateTime</parameter></term> 4011 <listitem> 4012 <para>Specifies the scheduled date, or date and time, at which the 4013 message should be displayed. For a date-only alarm, the string should 4014 be in the format <replaceable>YYYY-MM-DD[ TZ]</replaceable> (as 4015 returned by <methodname>QDate::toString(Qt::ISODate)</methodname>). For 4016 an alarm with a date and time, the string should be in the format 4017 <replaceable>YYYY-MM-DDTHH:MM[:SS][ TZ]</replaceable> (as returned by 4018 <methodname>QDateTime::toString(Qt::ISODate)</methodname>) or 4019 <replaceable>HH:MM[:SS]</replaceable> (as returned by 4020 <methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is 4021 specified, today's date is used. Note that any seconds value is 4022 ignored.</para> 4023 4024 <para>If no time zone is specified, the local system time zone is 4025 assumed. If a time zone specifier <replaceable>TZ</replaceable> is 4026 present, it may be the name of a system time zone (⪚ 4027 <userinput>Europe/London</userinput>), or <userinput>UTC</userinput> 4028 representing the UTC time zone.</para> 4029 </listitem> 4030 </varlistentry> 4031 4032 <varlistentry> 4033 <term><parameter>lateCancel</parameter></term> 4034 <listitem> 4035 <para>Causes the alarm to be canceled if it cannot be triggered within 4036 the specified number of minutes after the alarm's scheduled time. If 4037 the value is 0, the alarm will not be canceled no matter how late it 4038 is triggered.</para> 4039 </listitem> 4040 </varlistentry> 4041 4042 <varlistentry> 4043 <term><parameter>flags</parameter></term> 4044 <listitem> 4045 <para>Specifies the logical OR of the desired alarm flags. The flag 4046 bits are those defined in class <classname>KAlarmIface</classname> in 4047 <filename>kalarmiface.h</filename>. Note that not all flag bits are 4048 applicable to file alarms.</para> 4049 </listitem> 4050 </varlistentry> 4051 4052 <varlistentry> 4053 <term><parameter>bgColor</parameter></term> 4054 <listitem> 4055 <para>Specifies the background color for displaying the file. The 4056 string may be in the format <quote>#RRGGBB</quote> (as returned by 4057 <methodname>QColor::name()</methodname>) where RR, GG and BB are 4058 two-digit hexadecimal values for red, green and blue. Alternatively 4059 the string may be in any of the other formats accepted by 4060 <methodname>QColor::setNamedColor()</methodname>, such as a name from 4061 the X color database (⪚ <quote>red</quote> or 4062 <quote>steelblue</quote>). Set the string to null to specify the 4063 current default background color.</para> 4064 </listitem> 4065 </varlistentry> 4066 4067 <varlistentry> 4068 <term><parameter>audioURL</parameter></term> 4069 <listitem> 4070 <para>Specifies the audio file which is to be played when the message 4071 is displayed. Set the value to null if no audio file is to be 4072 played.</para> 4073 </listitem> 4074 </varlistentry> 4075 4076 <varlistentry> 4077 <term><parameter>reminderMins</parameter></term> 4078 <listitem> 4079 <para>Specifies the number of minutes in advance of the main alarm and 4080 of each of its recurrences (if any) at which a reminder alarm should 4081 be displayed. Specify a negative value for a reminder to be displayed 4082 after the main alarm. Specify 0 if no reminder is required.</para> 4083 </listitem> 4084 </varlistentry> 4085 4086 <varlistentry> 4087 <term><parameter>recurrence</parameter></term> 4088 <listitem> 4089 <para>Specifies a regular recurrence for the alarm, using iCalendar 4090 syntax as defined in 4091 <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. 4092 For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> 4093 would specify 4 repetitions at 3-monthly intervals on the last Monday 4094 of the month. For a non-recurring alarm, specify an empty 4095 string.</para> 4096 </listitem> 4097 </varlistentry> 4098 4099 <varlistentry> 4100 <term><parameter>recurType</parameter></term> 4101 <listitem> 4102 <para>Specifies the recurrence type for the alarm. The permissible 4103 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These 4104 are defined in class <classname>KAlarmIface</classname> in 4105 <filename>kalarmiface.h</filename>. Monthly recurrences are of the 4106 day of the month type, and yearly recurrences are of the date in 4107 the year type, with the date in both cases taken from the 4108 <parameter>startDateTime</parameter> parameter.</para> 4109 </listitem> 4110 </varlistentry> 4111 4112 <varlistentry> 4113 <term><parameter>recurInterval</parameter></term> 4114 <listitem> 4115 <para>Specifies the number of periods 4116 (minutes/days/weeks/months/years as specified by 4117 <parameter>recurType</parameter>) between recurrences of the 4118 alarm.</para> 4119 </listitem> 4120 </varlistentry> 4121 4122 <varlistentry> 4123 <term><parameter>recurCount</parameter></term> 4124 <listitem> 4125 <para>Specifies the number of times that the alarm should be 4126 repeated. Specify -1 to repeat the alarm indefinitely.</para> 4127 </listitem> 4128 </varlistentry> 4129 4130 <varlistentry> 4131 <term><parameter>endDateTime</parameter></term> 4132 <listitem> 4133 <para>Specifies the end date, or date and time, for recurrences of the 4134 alarm. If <parameter>startDateTime</parameter> includes a time, this 4135 parameter must also include a time; if <parameter>startDateTime</parameter> 4136 contains only a date, this parameter must also contain only a 4137 date. It must not contain a time zone specifier; the same time zone as 4138 for <parameter>startDateTime</parameter> is used to interpret this 4139 parameter's value.</para> 4140 </listitem> 4141 </varlistentry> 4142 4143 <varlistentry> 4144 <term><parameter>subRepeatInterval</parameter></term> 4145 <listitem> 4146 <para>Specifies the number of minutes between sub-repetitions of 4147 the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence 4148 is specified.</para> 4149 </listitem> 4150 </varlistentry> 4151 4152 <varlistentry> 4153 <term><parameter>subRepeatCount</parameter></term> 4154 <listitem> 4155 <para>Specifies the number of sub-repetitions of the alarm, 4156 including the initial occurrence.</para> 4157 </listitem> 4158 </varlistentry> 4159 </variablelist> 4160 </refsect2> 4161 </refsynopsisdiv> 4162 4163 <refsect1> 4164 <title>Description</title> 4165 <para><function>scheduleFile()</function> is a &DBus; call to schedule 4166 the specified text or image file for display at the specified date and 4167 time. Apart from specifying a file path or &URL; and omitting the 4168 foreground color and font, its usage is identical to 4169 <link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link> 4170 - see the description of that function for further details.</para> 4171 </refsect1> 4172 </refentry> 4173 4174 4175 <refentry id="scheduleCommand"> 4176 <refmeta> 4177 <refentrytitle>scheduleCommand</refentrytitle> 4178 </refmeta> 4179 <refnamediv> 4180 <refname>scheduleCommand</refname> 4181 <refpurpose>schedule a new alarm which executes a shell 4182 command.</refpurpose> 4183 </refnamediv> 4184 <refsynopsisdiv> 4185 <synopsis> 4186 bool scheduleCommand(const QString& <replaceable>name</replaceable>, 4187 const QString& <replaceable>commandLine</replaceable>, 4188 const QString& <replaceable>startDateTime</replaceable>, 4189 int <replaceable>lateCancel</replaceable>, 4190 unsigned <replaceable>flags</replaceable>, 4191 const QString& <replaceable>recurrence</replaceable>, 4192 int <replaceable>subRepeatInterval</replaceable>, 4193 int <replaceable>subRepeatCount</replaceable>) 4194 </synopsis> 4195 <synopsis> 4196 bool scheduleCommand(const QString& <replaceable>name</replaceable>, 4197 const QString& <replaceable>commandLine</replaceable>, 4198 const QString& <replaceable>startDateTime</replaceable>, 4199 int <replaceable>lateCancel</replaceable>, 4200 unsigned <replaceable>flags</replaceable>, 4201 int <replaceable>recurType</replaceable>, 4202 int <replaceable>recurInterval</replaceable>, 4203 int <replaceable>recurCount</replaceable>) 4204 </synopsis> 4205 <synopsis> 4206 bool scheduleCommand(const QString& <replaceable>name</replaceable>, 4207 const QString& <replaceable>commandLine</replaceable>, 4208 const QString& <replaceable>startDateTime</replaceable>, 4209 int <replaceable>lateCancel</replaceable>, 4210 unsigned <replaceable>flags</replaceable>, 4211 int <replaceable>recurType</replaceable>, 4212 int <replaceable>recurInterval</replaceable>, 4213 const QString& <replaceable>endDateTime</replaceable>) 4214 </synopsis> 4215 4216 <refsect2> 4217 <title>Parameters</title> 4218 <variablelist> 4219 <varlistentry> 4220 <term><parameter>name</parameter></term> 4221 <listitem> 4222 <para>Specifies an optional name for the alarm.</para> 4223 </listitem> 4224 </varlistentry> 4225 4226 <varlistentry> 4227 <term><parameter>commandLine</parameter></term> 4228 <listitem> 4229 <para>Specifies the command whose execution is to be scheduled. The 4230 <parameter>flags</parameter> parameter indicates whether this 4231 parameter contains a shell command line or a command script.</para> 4232 </listitem> 4233 </varlistentry> 4234 4235 <varlistentry> 4236 <term><parameter>startDateTime</parameter></term> 4237 <listitem> 4238 <para>Specifies the scheduled date, or date and time, at which the 4239 message should be displayed. For a date-only alarm, the string should 4240 be in the format <replaceable>YYYY-MM-DD[ TZ]</replaceable> (as 4241 returned by <methodname>QDate::toString(Qt::ISODate)</methodname>). For 4242 an alarm with a date and time, the string should be in the format 4243 <replaceable>YYYY-MM-DDTHH:MM[:SS][ TZ]</replaceable> (as returned by 4244 <methodname>QDateTime::toString(Qt::ISODate)</methodname>) or 4245 <replaceable>HH:MM[:SS]</replaceable> (as returned by 4246 <methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is 4247 specified, today's date is used. Note that any seconds value is 4248 ignored.</para> 4249 4250 <para>If no time zone is specified, the local system time zone is 4251 assumed. If a time zone specifier <replaceable>TZ</replaceable> is 4252 present, it may be the name of a system time zone (⪚ 4253 <userinput>Europe/London</userinput>), or <userinput>UTC</userinput> 4254 representing the UTC time zone.</para> 4255 </listitem> 4256 </varlistentry> 4257 4258 <varlistentry> 4259 <term><parameter>lateCancel</parameter></term> 4260 <listitem> 4261 <para>Causes the alarm to be canceled if it cannot be triggered within 4262 the specified number of minutes after the alarm's scheduled time. If 4263 the value is 0, the alarm will not be canceled no matter how late it 4264 is triggered.</para> 4265 </listitem> 4266 </varlistentry> 4267 4268 <varlistentry> 4269 <term><parameter>flags</parameter></term> 4270 <listitem> 4271 <para>Specifies the logical OR of the desired alarm flags. The flag 4272 bits are those defined in class <classname>KAlarmIface</classname> in 4273 <filename>kalarmiface.h</filename>. Note that not all flag bits are 4274 applicable to command alarms.</para> 4275 </listitem> 4276 </varlistentry> 4277 4278 <varlistentry> 4279 <term><parameter>recurrence</parameter></term> 4280 <listitem> 4281 <para>Specifies a regular recurrence for the alarm, using iCalendar 4282 syntax as defined in 4283 <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. 4284 For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> 4285 would specify 4 repetitions at 3-monthly intervals on the last Monday 4286 of the month. For a non-recurring alarm, specify an empty 4287 string.</para> 4288 </listitem> 4289 </varlistentry> 4290 4291 <varlistentry> 4292 <term><parameter>recurType</parameter></term> 4293 <listitem> 4294 <para>Specifies the recurrence type for the alarm. The permissible 4295 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These 4296 are defined in class <classname>KAlarmIface</classname> in 4297 <filename>kalarmiface.h</filename>. Monthly recurrences are of the 4298 day of the month type, and yearly recurrences are of the date in 4299 the year type, with the date in both cases taken from the 4300 <parameter>startDateTime</parameter> parameter.</para> 4301 </listitem> 4302 </varlistentry> 4303 4304 <varlistentry> 4305 <term><parameter>recurInterval</parameter></term> 4306 <listitem> 4307 <para>Specifies the number of periods 4308 (minutes/days/weeks/months/years as specified by 4309 <parameter>recurType</parameter>) between recurrences of the 4310 alarm.</para> 4311 </listitem> 4312 </varlistentry> 4313 4314 <varlistentry> 4315 <term><parameter>recurCount</parameter></term> 4316 <listitem> 4317 <para>Specifies the number of times that the alarm should be 4318 repeated. Specify -1 to repeat the alarm indefinitely.</para> 4319 </listitem> 4320 </varlistentry> 4321 4322 <varlistentry> 4323 <term><parameter>endDateTime</parameter></term> 4324 <listitem> 4325 <para>Specifies the end date, or date and time, for recurrences of the 4326 alarm. If <parameter>startDateTime</parameter> includes a time, this 4327 parameter must also include a time; if <parameter>startDateTime</parameter> 4328 contains only a date, this parameter must also contain only a 4329 date. It must not contain a time zone specifier; the same time zone as 4330 for <parameter>startDateTime</parameter> is used to interpret this 4331 parameter's value.</para> 4332 </listitem> 4333 </varlistentry> 4334 4335 <varlistentry> 4336 <term><parameter>subRepeatInterval</parameter></term> 4337 <listitem> 4338 <para>Specifies the number of minutes between sub-repetitions of 4339 the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence 4340 is specified.</para> 4341 </listitem> 4342 </varlistentry> 4343 4344 <varlistentry> 4345 <term><parameter>subRepeatCount</parameter></term> 4346 <listitem> 4347 <para>Specifies the number of sub-repetitions of the alarm, 4348 including the initial occurrence.</para> 4349 </listitem> 4350 </varlistentry> 4351 </variablelist> 4352 </refsect2> 4353 </refsynopsisdiv> 4354 4355 <refsect1> 4356 <title>Description</title> 4357 <para><function>scheduleCommand()</function> is a &DBus; call to 4358 schedule the specified shell command line, or command script, for 4359 execution at the specified date and time. Apart from specifying a 4360 command and omitting the message color, font and audio file 4361 parameters, its usage is identical to 4362 <link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link> 4363 - see the description of that function for further details.</para> 4364 </refsect1> 4365 </refentry> 4366 4367 4368 <refentry id="scheduleEmail"> 4369 <refmeta> 4370 <refentrytitle>scheduleEmail</refentrytitle> 4371 </refmeta> 4372 <refnamediv> 4373 <refname>scheduleEmail</refname> 4374 <refpurpose>schedule a new alarm which sends an email.</refpurpose> 4375 </refnamediv> 4376 <refsynopsisdiv> 4377 <synopsis> 4378 bool scheduleEmail(const QString& <replaceable>name</replaceable>, 4379 const QString& <replaceable>fromID</replaceable>, 4380 const QString& <replaceable>addresses</replaceable>, 4381 const QString& <replaceable>subject</replaceable>, 4382 const QString& <replaceable>message</replaceable>, 4383 const QString& <replaceable>attachments</replaceable>, 4384 const QString& <replaceable>startDateTime</replaceable>, 4385 int <replaceable>lateCancel</replaceable>, 4386 unsigned <replaceable>flags</replaceable>, 4387 const QString& <replaceable>recurrence</replaceable>, 4388 int <replaceable>subRepeatInterval</replaceable>, 4389 int <replaceable>subRepeatCount</replaceable>) 4390 </synopsis> 4391 <synopsis> 4392 bool scheduleEmail(const QString& <replaceable>name</replaceable>, 4393 const QString& <replaceable>fromID</replaceable>, 4394 const QString& <replaceable>addresses</replaceable>, 4395 const QString& <replaceable>subject</replaceable>, 4396 const QString& <replaceable>message</replaceable>, 4397 const QString& <replaceable>attachments</replaceable>, 4398 const QString& <replaceable>startDateTime</replaceable>, 4399 int <replaceable>lateCancel</replaceable>, 4400 unsigned <replaceable>flags</replaceable>, 4401 int <replaceable>recurType</replaceable>, 4402 int <replaceable>recurInterval</replaceable>, 4403 int <replaceable>recurCount</replaceable>) 4404 </synopsis> 4405 <synopsis> 4406 bool scheduleEmail(const QString& <replaceable>name</replaceable>, 4407 const QString& <replaceable>fromID</replaceable>, 4408 const QString& <replaceable>addresses</replaceable>, 4409 const QString& <replaceable>subject</replaceable>, 4410 const QString& <replaceable>message</replaceable>, 4411 const QString& <replaceable>attachments</replaceable>, 4412 const QString& <replaceable>startDateTime</replaceable>, 4413 int <replaceable>lateCancel</replaceable>, 4414 unsigned <replaceable>flags</replaceable>, 4415 int <replaceable>recurType</replaceable>, 4416 int <replaceable>recurInterval</replaceable>, 4417 const QString& <replaceable>endTime</replaceable>) 4418 </synopsis> 4419 4420 <refsect2> 4421 <title>Parameters</title> 4422 <variablelist> 4423 <varlistentry> 4424 <term><parameter>name</parameter></term> 4425 <listitem> 4426 <para>Specifies an optional name for the alarm.</para> 4427 </listitem> 4428 </varlistentry> 4429 4430 <varlistentry> 4431 <term><parameter>fromID</parameter></term> 4432 <listitem> 4433 <para>The &kmail; identity to use as the sender of the email. If 4434 empty, the sender's email address will be that configured in 4435 &kalarm;'s 4436 <link linkend="preferences-email">Email preferences</link>.</para> 4437 </listitem> 4438 </varlistentry> 4439 4440 <varlistentry> 4441 <term><parameter>addresses</parameter></term> 4442 <listitem> 4443 <para>A comma separated list of recipients' email addresses.</para> 4444 </listitem> 4445 </varlistentry> 4446 4447 <varlistentry> 4448 <term><parameter>subject</parameter></term> 4449 <listitem> 4450 <para>Specifies the subject line of the email.</para> 4451 </listitem> 4452 </varlistentry> 4453 4454 <varlistentry> 4455 <term><parameter>message</parameter></term> 4456 <listitem> 4457 <para>Specifies the email message body.</para> 4458 </listitem> 4459 </varlistentry> 4460 4461 <varlistentry> 4462 <term><parameter>attachments</parameter></term> 4463 <listitem> 4464 <para>A comma-separated list of paths or &URL;s of files to send as 4465 email attachments.</para> 4466 </listitem> 4467 </varlistentry> 4468 4469 <varlistentry> 4470 <term><parameter>startDateTime</parameter></term> 4471 <listitem> 4472 <para>Specifies the scheduled date, or date and time, at which the 4473 message should be displayed. For a date-only alarm, the string should 4474 be in the format <replaceable>YYYY-MM-DD[ TZ]</replaceable> (as 4475 returned by <methodname>QDate::toString(Qt::ISODate)</methodname>). For 4476 an alarm with a date and time, the string should be in the format 4477 <replaceable>YYYY-MM-DDTHH:MM[:SS][ TZ]</replaceable> (as returned by 4478 <methodname>QDateTime::toString(Qt::ISODate)</methodname>) or 4479 <replaceable>HH:MM[:SS]</replaceable> (as returned by 4480 <methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is 4481 specified, today's date is used. Note that any seconds value is 4482 ignored.</para> 4483 4484 <para>If no time zone is specified, the local system time zone is 4485 assumed. If a time zone specifier <replaceable>TZ</replaceable> is 4486 present, it may be the name of a system time zone (⪚ 4487 <userinput>Europe/London</userinput>), or <userinput>UTC</userinput> 4488 representing the UTC time zone.</para> 4489 </listitem> 4490 </varlistentry> 4491 4492 <varlistentry> 4493 <term><parameter>lateCancel</parameter></term> 4494 <listitem> 4495 <para>Causes the alarm to be canceled if it cannot be triggered within 4496 the specified number of minutes after the alarm's scheduled time. If 4497 the value is 0, the alarm will not be canceled no matter how late it 4498 is triggered.</para> 4499 </listitem> 4500 </varlistentry> 4501 4502 <varlistentry> 4503 <term><parameter>flags</parameter></term> 4504 <listitem> 4505 <para>Specifies the logical OR of the desired alarm flags. The flag 4506 bits are those defined in class <classname>KAlarmIface</classname> in 4507 <filename>kalarmiface.h</filename>. Note that not all flag bits are 4508 applicable to email alarms.</para> 4509 </listitem> 4510 </varlistentry> 4511 4512 <varlistentry> 4513 <term><parameter>recurrence</parameter></term> 4514 <listitem> 4515 <para>Specifies a regular recurrence for the alarm, using iCalendar 4516 syntax as defined in 4517 <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. 4518 For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> 4519 would specify 4 repetitions at 3-monthly intervals on the last Monday 4520 of the month. For a non-recurring alarm, specify an empty 4521 string.</para> 4522 </listitem> 4523 </varlistentry> 4524 4525 <varlistentry> 4526 <term><parameter>recurType</parameter></term> 4527 <listitem> 4528 <para>Specifies the recurrence type for the alarm. The permissible 4529 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These 4530 are defined in class <classname>KAlarmIface</classname> in 4531 <filename>kalarmiface.h</filename>. Monthly recurrences are of the 4532 day of the month type, and yearly recurrences are of the date in 4533 the year type, with the date in both cases taken from the 4534 <parameter>startDateTime</parameter> parameter.</para> 4535 </listitem> 4536 </varlistentry> 4537 4538 <varlistentry> 4539 <term><parameter>recurInterval</parameter></term> 4540 <listitem> 4541 <para>Specifies the number of periods 4542 (minutes/days/weeks/months/years as specified by 4543 <parameter>recurType</parameter>) between recurrences of the 4544 alarm.</para> 4545 </listitem> 4546 </varlistentry> 4547 4548 <varlistentry> 4549 <term><parameter>recurCount</parameter></term> 4550 <listitem> 4551 <para>Specifies the number of times that the alarm should be 4552 repeated. Specify -1 to repeat the alarm indefinitely.</para> 4553 </listitem> 4554 </varlistentry> 4555 4556 <varlistentry> 4557 <term><parameter>endDateTime</parameter></term> 4558 <listitem> 4559 <para>Specifies the end date, or date and time, for recurrences of the 4560 alarm. If <parameter>startDateTime</parameter> includes a time, this 4561 parameter must also include a time; if <parameter>startDateTime</parameter> 4562 contains only a date, this parameter must also contain only a 4563 date. It must not contain a time zone specifier; the same time zone as 4564 for <parameter>startDateTime</parameter> is used to interpret this 4565 parameter's value.</para> 4566 </listitem> 4567 </varlistentry> 4568 4569 <varlistentry> 4570 <term><parameter>subRepeatInterval</parameter></term> 4571 <listitem> 4572 <para>Specifies the number of minutes between sub-repetitions of 4573 the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence 4574 is specified.</para> 4575 </listitem> 4576 </varlistentry> 4577 4578 <varlistentry> 4579 <term><parameter>subRepeatCount</parameter></term> 4580 <listitem> 4581 <para>Specifies the number of sub-repetitions of the alarm, 4582 including the initial occurrence.</para> 4583 </listitem> 4584 </varlistentry> 4585 </variablelist> 4586 </refsect2> 4587 </refsynopsisdiv> 4588 4589 <refsect1> 4590 <title>Description</title> 4591 <para><function>scheduleEmail()</function> is a &DBus; call to 4592 schedule the specified email for sending at the specified date and 4593 time. Apart from specifying the email header and contents and omitting 4594 the message color, font and audio file parameters, its usage is 4595 identical to 4596 <link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link> 4597 - see the description of that function for further details.</para> 4598 </refsect1> 4599 </refentry> 4600 4601 4602 <refentry id="scheduleAudio"> 4603 <refmeta> 4604 <refentrytitle>scheduleAudio</refentrytitle> 4605 </refmeta> 4606 <refnamediv> 4607 <refname>scheduleAudio</refname> 4608 <refpurpose>schedule a new alarm which executes a shell 4609 command.</refpurpose> 4610 </refnamediv> 4611 <refsynopsisdiv> 4612 <synopsis> 4613 bool scheduleAudio(const QString& <replaceable>name</replaceable>, 4614 const QString& <replaceable>audioURL</replaceable>, 4615 int <replaceable>volumePercent</replaceable>, 4616 const QString& <replaceable>startDateTime</replaceable>, 4617 int <replaceable>lateCancel</replaceable>, 4618 unsigned <replaceable>flags</replaceable>, 4619 const QString& <replaceable>recurrence</replaceable>, 4620 int <replaceable>subRepeatInterval</replaceable>, 4621 int <replaceable>subRepeatCount</replaceable>) 4622 </synopsis> 4623 <synopsis> 4624 bool scheduleAudio(const QString& <replaceable>name</replaceable>, 4625 const QString& <replaceable>audioURL</replaceable>, 4626 int <replaceable>volumePercent</replaceable>, 4627 const QString& <replaceable>startDateTime</replaceable>, 4628 int <replaceable>lateCancel</replaceable>, 4629 unsigned <replaceable>flags</replaceable>, 4630 int <replaceable>recurType</replaceable>, 4631 int <replaceable>recurInterval</replaceable>, 4632 int <replaceable>recurCount</replaceable>) 4633 </synopsis> 4634 <synopsis> 4635 bool scheduleAudio(const QString& <replaceable>name</replaceable>, 4636 const QString& <replaceable>audioURL</replaceable>, 4637 int <replaceable>volumePercent</replaceable>, 4638 const QString& <replaceable>startDateTime</replaceable>, 4639 int <replaceable>lateCancel</replaceable>, 4640 unsigned <replaceable>flags</replaceable>, 4641 int <replaceable>recurType</replaceable>, 4642 int <replaceable>recurInterval</replaceable>, 4643 const QString& <replaceable>endDateTime</replaceable>) 4644 </synopsis> 4645 4646 <refsect2> 4647 <title>Parameters</title> 4648 <variablelist> 4649 <varlistentry> 4650 <term><parameter>name</parameter></term> 4651 <listitem> 4652 <para>Specifies an optional name for the alarm.</para> 4653 </listitem> 4654 </varlistentry> 4655 4656 <varlistentry> 4657 <term><parameter>audioURL</parameter></term> 4658 <listitem> 4659 <para>Specifies the audio file which is to be played.</para> 4660 </listitem> 4661 </varlistentry> 4662 4663 <varlistentry> 4664 <term><parameter>volumePercent</parameter></term> 4665 <listitem> 4666 <para>Specifies the volume level to use, as a percentage of full 4667 volume. Specify -1 to use the default volume.</para> 4668 </listitem> 4669 </varlistentry> 4670 4671 <varlistentry> 4672 <term><parameter>startDateTime</parameter></term> 4673 <listitem> 4674 <para>Specifies the scheduled date, or date and time, at which the 4675 message should be displayed. For a date-only alarm, the string should 4676 be in the format <replaceable>YYYY-MM-DD[ TZ]</replaceable> (as 4677 returned by <methodname>QDate::toString(Qt::ISODate)</methodname>). For 4678 an alarm with a date and time, the string should be in the format 4679 <replaceable>YYYY-MM-DDTHH:MM[:SS][ TZ]</replaceable> (as returned by 4680 <methodname>QDateTime::toString(Qt::ISODate)</methodname>) or 4681 <replaceable>HH:MM[:SS]</replaceable> (as returned by 4682 <methodname>QTime::toString(Qt::ISODate)</methodname>). If no date is 4683 specified, today's date is used. Note that any seconds value is 4684 ignored.</para> 4685 4686 <para>If no time zone is specified, the local system time zone is 4687 assumed. If a time zone specifier <replaceable>TZ</replaceable> is 4688 present, it may be the name of a system time zone (⪚ 4689 <userinput>Europe/London</userinput>), or <userinput>UTC</userinput> 4690 representing the UTC time zone.</para> 4691 </listitem> 4692 </varlistentry> 4693 4694 <varlistentry> 4695 <term><parameter>lateCancel</parameter></term> 4696 <listitem> 4697 <para>Causes the alarm to be canceled if it cannot be triggered within 4698 the specified number of minutes after the alarm's scheduled time. If 4699 the value is 0, the alarm will not be canceled no matter how late it 4700 is triggered.</para> 4701 </listitem> 4702 </varlistentry> 4703 4704 <varlistentry> 4705 <term><parameter>flags</parameter></term> 4706 <listitem> 4707 <para>Specifies the logical OR of the desired alarm flags. The flag 4708 bits are those defined in class <classname>KAlarmIface</classname> in 4709 <filename>kalarmiface.h</filename>. Note that not all flag bits are 4710 applicable to command alarms.</para> 4711 </listitem> 4712 </varlistentry> 4713 4714 <varlistentry> 4715 <term><parameter>recurrence</parameter></term> 4716 <listitem> 4717 <para>Specifies a regular recurrence for the alarm, using iCalendar 4718 syntax as defined in 4719 <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445</ulink>. 4720 For example, <quote>FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO</quote> 4721 would specify 4 repetitions at 3-monthly intervals on the last Monday 4722 of the month. For a non-recurring alarm, specify an empty 4723 string.</para> 4724 </listitem> 4725 </varlistentry> 4726 4727 <varlistentry> 4728 <term><parameter>recurType</parameter></term> 4729 <listitem> 4730 <para>Specifies the recurrence type for the alarm. The permissible 4731 values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These 4732 are defined in class <classname>KAlarmIface</classname> in 4733 <filename>kalarmiface.h</filename>. Monthly recurrences are of the 4734 day of the month type, and yearly recurrences are of the date in 4735 the year type, with the date in both cases taken from the 4736 <parameter>startDateTime</parameter> parameter.</para> 4737 </listitem> 4738 </varlistentry> 4739 4740 <varlistentry> 4741 <term><parameter>recurInterval</parameter></term> 4742 <listitem> 4743 <para>Specifies the number of periods 4744 (minutes/days/weeks/months/years as specified by 4745 <parameter>recurType</parameter>) between recurrences of the 4746 alarm.</para> 4747 </listitem> 4748 </varlistentry> 4749 4750 <varlistentry> 4751 <term><parameter>recurCount</parameter></term> 4752 <listitem> 4753 <para>Specifies the number of times that the alarm should be 4754 repeated. Specify -1 to repeat the alarm indefinitely.</para> 4755 </listitem> 4756 </varlistentry> 4757 4758 <varlistentry> 4759 <term><parameter>endDateTime</parameter></term> 4760 <listitem> 4761 <para>Specifies the end date, or date and time, for recurrences of the 4762 alarm. If <parameter>startDateTime</parameter> includes a time, this 4763 parameter must also include a time; if <parameter>startDateTime</parameter> 4764 contains only a date, this parameter must also contain only a 4765 date. It must not contain a time zone specifier; the same time zone as 4766 for <parameter>startDateTime</parameter> is used to interpret this 4767 parameter's value.</para> 4768 </listitem> 4769 </varlistentry> 4770 4771 <varlistentry> 4772 <term><parameter>subRepeatInterval</parameter></term> 4773 <listitem> 4774 <para>Specifies the number of minutes between sub-repetitions of 4775 the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence 4776 is specified.</para> 4777 </listitem> 4778 </varlistentry> 4779 4780 <varlistentry> 4781 <term><parameter>subRepeatCount</parameter></term> 4782 <listitem> 4783 <para>Specifies the number of sub-repetitions of the alarm, 4784 including the initial occurrence.</para> 4785 </listitem> 4786 </varlistentry> 4787 </variablelist> 4788 </refsect2> 4789 </refsynopsisdiv> 4790 4791 <refsect1> 4792 <title>Description</title> 4793 <para><function>scheduleAudio()</function> is a &DBus; call to 4794 schedule the specified audio file to be played at the specified date 4795 and time. Apart from specifying a volume and omitting the message 4796 color and font parameters, its usage is identical to 4797 <link linkend="scheduleMessage-descrip"><function>scheduleMessage</function></link> 4798 - see the description of that function for further details.</para> 4799 </refsect1> 4800 </refentry> 4801 4802 <refentry id="dbus_edit"> 4803 <refmeta> 4804 <refentrytitle>edit</refentrytitle> 4805 </refmeta> 4806 <refnamediv> 4807 <refname>edit</refname> 4808 <refpurpose>Display the <link linkend="alarm-edit-dlg">Alarm Edit 4809 dialog</link> to edit an alarm.</refpurpose> 4810 </refnamediv> 4811 <refsynopsisdiv> 4812 <synopsis> 4813 bool edit(const QString& <replaceable>eventID</replaceable>) 4814 </synopsis> 4815 4816 <refsect2> 4817 <title>Parameters</title> 4818 <variablelist> 4819 <varlistentry> 4820 <term><parameter>eventID</parameter></term> 4821 <listitem> 4822 <para>Specifies the unique ID of the event to be edited, optionally 4823 prefixed by the configuration name or numeric ID of the resource containing 4824 the event, in the format 4825 <replaceable>[resourceID:]eventUID</replaceable>.</para> 4826 </listitem> 4827 </varlistentry> 4828 </variablelist> 4829 </refsect2> 4830 4831 <refsect2> 4832 <title>Return value</title> 4833 <para><returnvalue>false</returnvalue> if the specified 4834 alarm could not be found or is read-only, 4835 <returnvalue>true</returnvalue> otherwise.</para> 4836 </refsect2> 4837 </refsynopsisdiv> 4838 4839 <refsect1> 4840 <title>Description</title> 4841 4842 <para><function>edit()</function> is a &DBus; call to display the 4843 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> to edit the 4844 specified alarm.</para> 4845 4846 </refsect1> 4847 </refentry> 4848 4849 <refentry id="dbus_editnew"> 4850 <refmeta> 4851 <refentrytitle>editNew</refentrytitle> 4852 </refmeta> 4853 <refnamediv> 4854 <refname>editNew</refname> 4855 <refpurpose>Display the <link linkend="alarm-edit-dlg">Alarm Edit 4856 dialog</link> to edit a new alarm.</refpurpose> 4857 </refnamediv> 4858 <refsynopsisdiv> 4859 <synopsis> 4860 bool editNew(int <replaceable>type</replaceable>) 4861 </synopsis> 4862 <synopsis> 4863 bool editNew(const QString& <replaceable>templateName</replaceable>) 4864 </synopsis> 4865 4866 <refsect2> 4867 <title>Parameters</title> 4868 <variablelist> 4869 <varlistentry> 4870 <term><parameter>type</parameter></term> 4871 <listitem> 4872 <para>Specifies the alarm type. The permissible values are DISPLAY, 4873 COMMAND, EMAIL, AUDIO. These are defined in class 4874 <classname>KAlarmIface</classname> in 4875 <filename>kalarmiface.h</filename>.</para> 4876 </listitem> 4877 </varlistentry> 4878 4879 <varlistentry> 4880 <term><parameter>templateName</parameter></term> 4881 <listitem> 4882 <para>Specifies the name of an alarm template to base the new alarm 4883 on.</para> 4884 </listitem> 4885 </varlistentry> 4886 </variablelist> 4887 </refsect2> 4888 4889 <refsect2> 4890 <title>Return value</title> 4891 <para><returnvalue>false</returnvalue> if <parameter>type</parameter> 4892 has an invalid value, or if no template with the name 4893 <parameter>templateName</parameter> can be found; 4894 <returnvalue>true</returnvalue> otherwise.</para> 4895 </refsect2> 4896 </refsynopsisdiv> 4897 4898 <refsect1> 4899 <title>Description</title> 4900 4901 <para><function>editNew()</function> is a &DBus; call to display the 4902 <link linkend="alarm-edit-dlg">Alarm Edit dialog</link> to edit a new 4903 alarm. If an alarm type is specified as a parameter, a blank dialog is 4904 displayed. Alternatively, if an alarm template name is specified as a 4905 parameter, the dialog is preset with details from the template.</para> 4906 4907 </refsect1> 4908 </refentry> 4909 4910 <refentry id="dbus_list"> 4911 <refmeta> 4912 <refentrytitle>list</refentrytitle> 4913 </refmeta> 4914 <refnamediv> 4915 <refname>list</refname> 4916 <refpurpose>Return a list of scheduled alarms.</refpurpose> 4917 </refnamediv> 4918 <refsynopsisdiv> 4919 <synopsis> 4920 QString list() 4921 </synopsis> 4922 4923 <refsect2> 4924 <title>Return value</title> 4925 <para>List of alarms, separated by newlines, each in the format 4926 <returnvalue><replaceable>resource_id</replaceable>:<replaceable>UID</replaceable> <replaceable>time</replaceable> <replaceable>text</replaceable></returnvalue></para> 4927 </refsect2> 4928 </refsynopsisdiv> 4929 4930 <refsect1> 4931 <title>Description</title> 4932 4933 <para><function>list()</function> is a &DBus; call to return a string 4934 containing a summary of scheduled alarms. The list shows brief details 4935 of each pending alarm: its resource identifier, UID, next scheduled time 4936 and message text or file.</para> 4937 4938 </refsect1> 4939 </refentry> 4940 4941 </sect1> 4942 4943 <sect1 id="cmdline-interface"> 4944 <title>Command Line Interface</title> 4945 4946 <para>Command line options are provided to enable other programs to 4947 start up &kalarm; if it is not already running, in order to trigger or 4948 cancel scheduled alarms, or schedule new alarms. The reason for using 4949 command line options for this purpose is that if &kalarm; were started 4950 without any command line parameters and then sent &DBus; requests, it 4951 would start in its default graphical mode, which is clearly undesirable 4952 for an inter-program request.</para> 4953 4954 <note><para>Programs should first check whether &kalarm; is already 4955 running; if it is, they should instead use &DBus; calls to request these 4956 operations.</para></note> 4957 4958 <para>The command line options for scheduling a new alarm are as 4959 described in the chapter <link linkend="cmdline-operation">Command Line 4960 Operation</link>. The options for triggering and canceling scheduled 4961 alarms are as follows:</para> 4962 4963 <note><para>Normal users may also if they wish use these command line 4964 options (assuming that they can supply the necessary parameter 4965 information).</para></note> 4966 4967 <informaltable> 4968 <tgroup cols="2"> 4969 <thead> 4970 <row> 4971 <entry>Option</entry> 4972 <entry>Description</entry> 4973 </row> 4974 </thead> 4975 <tbody> 4976 <row> 4977 <entry><option>--cancelEvent <replaceable>eventID</replaceable></option></entry> 4978 <entry>Cancel the alarm with the specified event ID. The event ID is 4979 the unique ID of the event, optionally prefixed by the ID of the 4980 resource containing the event, in the format 4981 <replaceable>[resourceID:]eventUID</replaceable>. 4982 The action taken is the same as for the 4983 <link linkend="cancelEvent">cancelEvent()</link> &DBus; call. 4984 <option>--triggerEvent</option> cannot be specified with this 4985 option.</entry> 4986 </row> 4987 <row> 4988 <entry><option>--triggerEvent <replaceable>eventID</replaceable></option></entry> 4989 <entry>Trigger the alarm with the specified event ID. The event ID is 4990 the unique ID of the event, optionally prefixed by the ID of the 4991 resource containing the event, in the format 4992 <replaceable>[resourceID:]eventUID</replaceable>. 4993 The action taken is the same as for the 4994 <link linkend="triggerEvent">triggerEvent()</link> &DBus; call. 4995 <option>--cancelEvent</option> cannot be specified with this 4996 option.</entry> 4997 </row> 4998 </tbody> 4999 </tgroup> 5000 </informaltable> 5001 5002 <para>Examples are:</para> 5003 5004 <informalexample><screen> 5005 <prompt>%</prompt> <userinput><command>kalarm</command> <option>--triggerEvent <replaceable>&kalarm;-387486299.702</replaceable></option></userinput> 5006 <prompt>%</prompt> <userinput><command>kalarm</command> <option>--cancelEvent <replaceable>&kalarm;-388886299.793</replaceable></option></userinput> 5007 </screen> 5008 </informalexample> 5009 5010 </sect1> 5011 </chapter> 5012 5013 5014 <chapter id="faq"> 5015 <title>Questions and Answers</title> 5016 5017 <qandaset id="faqlist"> 5018 <qandaentry> 5019 <question> 5020 <para>What configuration files does &kalarm; use?</para> 5021 </question> 5022 <answer> 5023 <para>&kalarm;'s configuration is held in the following files in the folder 5024 <command>qtpaths --paths GenericConfigLocation</command> :</para> 5025 5026 <itemizedlist> 5027 <listitem> 5028 <simpara><filename>kalarmrc</filename> holds your &kalarm; 5029 preferences.</simpara> 5030 </listitem> 5031 5032 <listitem> 5033 <simpara><filename>kalarmresources</filename> holds the list of alarm 5034 calendars currently used by &kalarm;.</simpara> 5035 </listitem> 5036 </itemizedlist> 5037 </answer> 5038 </qandaentry> 5039 5040 <qandaentry> 5041 <question> 5042 <para>Where does &kalarm; store its alarms?</para> 5043 </question> 5044 <answer> 5045 5046 <para>When &kalarm; is run the first time, it creates the following 5047 alarm calendars in the folder 5048 <command>qtpaths --paths GenericDataLocation</command> :</para> 5049 5050 <itemizedlist> 5051 <listitem> 5052 <simpara><filename>kalarm/calendar.ics</filename>, which holds active 5053 alarms.</simpara> 5054 </listitem> 5055 5056 <listitem> 5057 <simpara><filename>kalarm/expired.ics</filename>, which holds archived 5058 alarms.</simpara> 5059 </listitem> 5060 5061 <listitem> 5062 <simpara><filename>kalarm/template.ics</filename>, which holds alarm 5063 templates.</simpara> 5064 </listitem> 5065 5066 <listitem> 5067 <simpara><filename>kalarm/displaying.ics</filename>, which is a special 5068 calendar file to hold details of alarms currently being displayed, 5069 which allows &kalarm;, when it is restarted, to redisplay alarms which 5070 were being displayed when it last stopped.</simpara> 5071 </listitem> 5072 </itemizedlist> 5073 5074 <para>You can subsequently replace these calendars, except 5075 <filename>displaying.ics</filename>, or create 5076 additional alarm calendars in any location which you choose. You can 5077 find out which calendar files are currently in use by viewing each 5078 calendar's details in the alarm calendars list.</para> 5079 </answer> 5080 </qandaentry> 5081 5082 <qandaentry> 5083 <question> 5084 <para>What format are alarms stored in?</para> 5085 </question> 5086 <answer> 5087 <para>The calendar files in which &kalarm; stores its alarms are text 5088 files whose format is defined by the document 5089 <ulink url="http://www.w3.org/2002/12/cal/rfc2445.html">RFC2445 - 5090 Internet Calendaring and Scheduling Core Object Specification 5091 (iCalendar)</ulink>. This is the standard format used by all kdepim 5092 applications. &kalarm; uses certain non-standard properties, in 5093 conformance with RFC2445. These are documented in the 5094 <filename>DESIGN-kalarmcalendar.html</filename> file which is 5095 distributed with &kalarm;.</para> 5096 </answer> 5097 </qandaentry> 5098 5099 <qandaentry id="akonadi-plugin"> 5100 <question> 5101 <para>What is the function of &kalarm;'s Akonadi plugin?</para> 5102 </question> 5103 <answer> 5104 <para>&kalarm; uses its Akonadi plugin to provide all features which 5105 depend on &akonadi; (the &kde; &PIM; cross-desktop storage service). 5106 If this plugin is not installed and enabled, &kalarm; will lack the 5107 following features: 5108 <itemizedlist> 5109 <listitem> 5110 <simpara>Sending emails via &kmail;, leaving &Sendmail; as the only 5111 option to send emails (see 5112 <link linkend="preferences-email">Email preferences</link>).</simpara> 5113 </listitem> 5114 <listitem> 5115 <simpara>Drag and drop of emails.</simpara> 5116 </listitem> 5117 <listitem> 5118 <simpara>Selection of email addresses from &kaddressbook;.</simpara> 5119 </listitem> 5120 <listitem> 5121 <simpara>Import of birthdays from &kaddressbook;.</simpara> 5122 </listitem> 5123 <listitem> 5124 <simpara>Migration of &akonadi; alarm calendar resources on the first 5125 run of a new version of &kalarm;.</simpara> 5126 </listitem> 5127 </itemizedlist> 5128 </para> 5129 <para>If the plugin is installed, it can be enabled or disabled in the 5130 <link linkend="preferences-general">General</link> tab of the 5131 Configuration dialog.</para> 5132 </answer> 5133 </qandaentry> 5134 5135 <qandaentry> 5136 <question> 5137 <para>What is the program <application>kalarmautostart</application>?</para> 5138 </question> 5139 <answer> 5140 <para><application>kalarmautostart</application> is a little helper 5141 program whose function is to autostart &kalarm; at login.</para> 5142 5143 <para>&kalarm; is usually restored by the session manager at login 5144 (to redisplay its windows in the same state as they were when you 5145 logged off). But if it was not running when you logged off, it would 5146 not be started by the session manager and therefore needs to be 5147 autostarted. The problem is that when an application is both session 5148 managed and autostarted, there is no guarantee as to which will occur 5149 first. If autostart gets in first, it will prevent the session manager 5150 from restoring the application's state.</para> 5151 5152 <para>To avoid this problem, 5153 <application>kalarmautostart</application> is autostarted at login 5154 instead of &kalarm;. All it does is wait for a short time (to ensure 5155 that the session manager has time to do its job) before starting 5156 &kalarm;, at which point it terminates.</para> 5157 </answer> 5158 </qandaentry> 5159 5160 <qandaentry> 5161 <question> 5162 <para>How can I use &kalarm; on a non-&plasma; desktop?</para> 5163 </question> 5164 <answer> 5165 <para>To run &kalarm; on a non-&plasma; desktop, the main requirement is 5166 to ensure that &kalarm; is run automatically whenever you log in. More 5167 detailed instructions are contained in the 5168 <filename>INSTALL</filename> file which is distributed with 5169 &kalarm;.</para> 5170 </answer> 5171 </qandaentry> 5172 5173 </qandaset> 5174 </chapter> 5175 5176 5177 <chapter id="credits"> 5178 5179 <title>Credits and License</title> 5180 5181 <para> 5182 &kalarm; 5183 </para> 5184 <para> 5185 Program copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 &David.Jarvie; &David.Jarvie.mail; 5186 </para> 5187 5188 <para> 5189 Documentation copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2016, 2018, 2019, 2020, 2021, 2022, 2023 &David.Jarvie; &David.Jarvie.mail; 5190 </para> 5191 5192 <!-- TRANS:CREDIT_FOR_TRANSLATORS --> 5193 5194 &underFDL; <!-- FDL: do not remove --> 5195 5196 &underGPL; <!-- GPL License --> 5197 5198 <para>Thanks go to the author of the &kde; 1 KAlarm application, 5199 Stefan Nikolaus <email>stefan.nikolaus@stuco.uni-oldenburg.de</email>, 5200 who kindly agreed to allow the name &kalarm; to be used by this 5201 application, which has been available for &kde; 2 onwards. 5202 </para> 5203 5204 </chapter> 5205 5206 &documentation.index; 5207 </book> 5208 <!-- 5209 Local Variables: 5210 mode: sgml 5211 sgml-minimize-attributes:nil 5212 sgml-general-insert-case:lower 5213 sgml-indent-step:0 5214 sgml-indent-data:nil 5215 End: 5216 --> 5217