The Alarm Edit Dialogue

The Alarm Edit dialogue enables you to view and edit an alarm. When you first use KAlarm, a simplified form of the dialogue is displayed, with only a small number of options visible. To see all options, click the More Options button; to revert to the simplified dialogue, click the Less Options button. KAlarm always remembers your last display choice whenever the Alarm Edit dialogue is redisplayed.

You can configure the default values of many of the settings in the Alarm Edit dialogue using the Configuration dialogue's Edit tab.


Simplified Alarm Edit dialogue for a display alarm

Simplified Alarm Edit dialogue for a display alarm



Alarm Edit dialogue for a display alarm, showing all options

Alarm Edit dialogue for a display alarm, showing all options


Alarm Action

The controls in the Action group box vary depending on the type of alarm being edited.

Display Alarms

Display alarms display a window when the alarm triggers. Select the method used to generate the alarm window contents, using the combo box at the top:

  • Text message in order to enter an alarm message text (which may include newlines) in the edit box.

  • File contents to enter the path or URL of a text or image file whose contents are to be displayed in the alarm message. Use the button beside the edit box to display a file selection dialogue. The Speak option is not available for this type of alarm.

  • Command output to specify that the alarm message text will be generated by a command which is executed when the alarm triggers. See Command Alarms below for details of how to enter the command or command script to execute.

The controls available for display alarms are:

  • The Sound option allows you to select whether an audible alarm should sound when the alarm message is displayed. Choose:

    • None to display the alarm silently.

    • Beep to sound a beep.

    • Speak to have the alarm message spoken as well as being displayed. This option is only available if you have Jovie (from the kdeaccessibility package) installed and configured, together with a compatible speech synthesiser, e.g. Festival.

    • Sound file to play an audio file. Use the button on the right to display the Sound File dialogue which lets you select a file to play and set volume and repetition options. If you hover the mouse over the selector, a tooltip will display the audio file currently selected.

      In the Sound File dialogue:

      • Enter the sound file path, or use the button beside the edit box to display a file selection dialogue. You can listen to the selected file by clicking the play button to the left of the edit field. That button then changes function to allow you to stop playing when you have heard enough.

      • Tick Repeat to continually repeat the audio file for as long as the alarm is displayed. (The alarm message window contains a button to stop playing the sound should you need silence but still want to display the alarm.)

      • Tick Volume and adjust the slider control if you want to adjust the volume at which the audio file is played.

      • If you wish, you can fade the volume. Fading means to start playing the audio file at one volume and gradually change to the final volume, over a specified time interval. The final volume is that entered in Volume above. To enable fade, tick Fade, and then enter the fade period in seconds in the Fade time field, and adjust the Initial volume slider.

      Tip

      You can use the Try button to test out the selected sound levels.

  • Use the Font & Colour... button to select a font, and foreground and background colours, for the alarm message. In the Choose Alarm Font & Colour dialogue, tick Use default font to display the message in whatever font is configured as the default at the time the message is displayed. To choose a specific font for the message, untick Use default font. (The default font and colours can be set in the Configuration dialogue.)

    The selected colours are shown in the alarm message text entry field.

  • Use the Special Actions... button to specify shell commands to execute before or after displaying the alarm. In the Special Alarm Actions dialogue:

    • In the Pre-alarm action field, enter a shell command to execute before the alarm is displayed. Note that KAlarm will wait for the command to complete before displaying the alarm.

      A pre-alarm action is only executed once when the alarm message is initially displayed, including when a reminder message is replaced by the actual alarm message. It is not executed in any of the following circumstances:

      • When a reminder message is displayed.

      • When the message is redisplayed after deferring the alarm.

      • When the message was displaying at the time you logged off and is then restored when you log back in.

      • When a recurring alarm triggers but the alarm message (or a deferred alarm message) from a previous occurrence of the alarm is still visible; in other words, when the previous occurrence of the alarm has not yet been acknowledged.

      The pre-alarm action can be used to control whether to display the alarm message:

      • Tick Cancel alarm on error to cancel the alarm if the pre-alarm command returns an error status. This will prevent the alarm message from being displayed, and any post-alarm action from being executed.

      • Normally, if the pre-alarm command returns an error, an error message is displayed and an error indication is shown in the alarm list. These error notifications can be prevented by ticking Do not notify errors.

    • In the Post-alarm action field, enter a shell command to execute when the alarm is acknowledged (whether by clicking Close or by using the close button in the window's titlebar). It is not executed in any of the following circumstances:

      • When a reminder message is closed.

      • When you defer the alarm, except when the deferred alarm is finally acknowledged.

      • When the alarm message is closed due to logging out.

    See Command Alarms below for details of how shell commands are executed.

Command Alarms

Command alarms execute a command without displaying any alarm message.

Note

This alarm type is not available if KDE is running in kiosk mode.

When the command is executed, the environment variable KALARM_UID contains the event UID for the alarm. Note that when the command is executed from the Alarm Edit dialogue's Try button, KALARM_UID will be blank if it is a new alarm, or if the alarm has been modified in the dialogue, because the alarm only acquires a UID when it is saved in the alarm calendar.

The controls available for command alarms are:

  • The Enter a script tick box lets you choose whether to enter a shell command line or a script.

    If this option is unticked, you can enter a shell command line to execute. The command is passed straight to the default shell (defined by the SHELL environment variable), and may include whatever options, parameters, piped commands, etc. are permitted by the shell in a single line command.

    If this option is ticked, you can enter the text of a script to execute. Remember to include a first line such as #!/bin/bash to ensure that the correct command interpreter is invoked.

  • Use the Command Output group box to specify what you want to be done with any terminal output which the command produces when it executes.

    • Tick Execute in terminal window to cause the command to be executed in a terminal window. You can choose which type of terminal window should be used in the Configuration dialogue.

    • Tick Log to file to save the command's output in a file. The output, prefixed by a heading showing the time at which the command was scheduled to run, will be appended to any existing contents of the file. Enter the file name in the edit box, or use the button beside the edit box to display a file selection dialogue.

    • Tick Discard to throw away the command's output.

Email Alarms

Email alarms send an email without displaying any alarm message.

Fill in the recipients' addresses, the email subject line and the message body in the three edit fields. Use the button beside the addressee edit box to display your KDE address book from which you can select email recipients. Attachments may be added using the Add... button. Note that attached files must still exist when the alarm is triggered; no copy is stored at the time the alarm is configured. To remove an attachment, highlight it in the drop-down list and click the Remove button.

Set the following options:

  • The From combo box allows you to select which KMail identity to use as your email address for sending the email. This option only appears if your From email address in the Configuration dialogue is set to Use KMail identities. Otherwise your email address is preset in the Configuration dialogue, rendering this option inapplicable.

  • Tick Copy email to self to send a blind copy of the email to yourself when the alarm is triggered. The email address to which the copy will be sent may be set in the Configuration dialogue, the default being your email address set in the KDE System Settings.

Audio Alarms

Audio alarms play an audio file without displaying any alarm message.

Set the following options:

  • Enter the sound file path, or use the button beside the edit box to display a file selection dialogue.

  • Tick Repeat to continually repeat the audio file until the Stop Play option is selected. To stop playing the file, select the ActionsStop Play menu option, or Right click on the system tray icon and choose Stop Play from the context menu. If you wish, you can set up a global shortcut key for this action.

  • Tick Volume and adjust the slider control if you want to adjust the volume at which the audio file is played.

  • If you wish, you can fade the volume. Fading means to start playing the audio file at one volume and gradually change to the final volume, over a specified time interval. The final volume is that entered in Volume above. To enable fade, tick Fade, and then enter the fade period in seconds in the Fade time field, and adjust the Initial volume slider.

Deferral

If the alarm is a recurring alarm and it was deferred after it was last displayed, the Deferred Alarm group box shows the time the alarm was deferred to. Change... displays a dialogue which allows you to change the deferred time or to cancel the deferral.

Time

In the Time group box, select either

  • At date/time to enter the date and time when the alarm is to be triggered. Tick Any time if you want to specify only a date for the alarm: in this case the alarm will be displayed at the first opportunity on or after the configured start-of-day time, on the specified date. (Configuring KAlarm describes how to set the start-of-day time.)

    For a non-recurring alarm, the date/time which you enter must be in the future, or if you enter only a date it must be today or later. For a recurring alarm, there are no such restrictions since the start date/time will be automatically adjusted to the first recurrence due after the current time.

  • Time from now to enter how long after now (in hours and minutes) the alarm should be triggered.

If desired, choose a time zone to apply to the alarm. This time zone is used for all dates and times relating to this alarm, including recurrence and exception dates and times. Normally, you should leave the time zone controls unchanged unless you have a good reason to change them.

The time zone controls are displayed only when the selected time zone is different from the default time zone set in the Configuration dialogue, or if you click the Time Zone... button.

  • In the combo box, choose the time zone which this alarm is to use. When creating a new alarm, this is initially set to the time zone selected in the Configuration dialogue, which will be your computer's time zone unless you have changed it.

  • Tick Ignore time zone if you want to use the local computer time (on whichever computer KAlarm happens to be running on at the time), ignoring time zones.

    Warning

    You are recommended not to select this option if the alarm has a recurrence specified in hours and minutes; if you do, the alarm may occur at unexpected times after seasonal time shifts.

Reminder

For a display alarm, tick Reminder if you want to display a reminder either before or after the main alarm and each of its recurrences (if any). Enter how long in advance or afterwards, using the edit controls beside the tick box. Note that if the alarm recurs, the reminder period is normally limited to being less than the recurrence or sub-repetition interval.

Note

Reminders are not displayed for sub-repetitions within a recurrence. Reminders are only shown for each main recurrence of the alarm.

If the alarm recurs, tick Reminder for first recurrence only if you only want a reminder for the alarm's first recurrence. If this is ticked, and it is an advance reminder, the reminder period is not subject to the normal limit of being less than the recurrence or sub-repetition interval.

Cancellation

The late-cancellation options determine how an alarm is treated after its scheduled time:

  • The Cancel if late tick box determines what happens if the alarm cannot be triggered at its scheduled time.

    Tick this box to cancel the alarm if it cannot be triggered within a specified time period after the right time. The time period is selected using controls which appear when you tick the box. For example, if you enter a time period of 1 hour, the alarm will be triggered at the first opportunity up to an hour after it is due, but if it cannot be triggered within an hour its activation will be cancelled.

    Note

    The lateness of date-only alarms, i.e. ones for which the Any time option is selected, is calculated from the start-of-day time on the alarm's scheduled date.

    Leave the box unticked to trigger the alarm at the first opportunity starting at the scheduled time, regardless of how late it is.

    Note

    An alarm can only be triggered while you are logged in, and while both X and KAlarm are running.

  • Tick Auto-close window after this time if you want the alarm window to be automatically closed if it is still showing at the expiry of the late-cancellation time.

Recurrence

Specify whether or how the alarm should be repeated using the Recurrence tab.

Note

The alarm's basic repetition characteristics are displayed for convenience in the title of the Recurrence tab. The recurrence interval is shown first, followed by any sub-repetition interval set up using the Sub-Repetition button.

In the Recurrence Rule group box, set the recurrence type or time period as follows:

  • To trigger the alarm once only, select No recurrence.

  • Select At login to trigger the alarm whenever you log in, until its scheduled end time. Then, at its scheduled end time it will finally be triggered one last time. (Note that an alarm repeated at login will also be triggered any time you restart KAlarm.)

  • To make the alarm recur at regular intervals, select one of the time period types and then enter in the Recur every box how many time periods should elapse between recurrences. For example, to repeat every fortnight, you could select Daily and enter a value of 14, or select Weekly and enter a value of 2. Depending on the time period type selected, you may have further options:

    • For a weekly recurrence, tick each day in the week on which you wish to trigger the alarm.

    • For a monthly recurrence, you may select either a fixed date, or a position (e.g. the second Tuesday).

    • For a yearly recurrence, you may select either a fixed day in the month, or a position in a month (e.g. the last Saturday in May). Tick each month of the year in which you wish to trigger the alarm.

      If you set up a yearly recurrence for February 29th, you can specify how it is to be handled in non-leap years by selecting the appropriate February 29th alarm in non-leap years option:

      • None: the alarm will occur on February 29th in leap years, but will be suppressed in non-leap years.

      • 28 Feb: the alarm will occur on February 29th in leap years, and on February 28th in non-leap years.

      • 1 Mar: the alarm will occur on February 29th in leap years, and on March 1st in non-leap years.

    Tip

    To set a daily alarm to occur only on weekdays, use a weekly recurrence and tick each weekday.

In the Recurrence End group box, set the overall recurrence time span as follows:

  • Select No end to continue the repetitions indefinitely.

  • Select End after to specify the total number of occurrences of the alarm.

  • Select End by to specify the date/time until which the alarm will be repeated. Note that this uses the same time zone as the alarm's start time.

    Note

    The end date/time determines when the last main recurrence will be, but does not limit sub-repetitions. If sub-repetitions are configured, they will trigger as normal after the last main recurrence, regardless of the end date/time.

The Exceptions group box allows you to exclude certain date/times from the recurrence which you have set up. Note that these controls are not shown in the simplified form of the Alarm Edit dialogue: to see them, click More Options.

  • The list of exceptions (i.e. excluded date/times) is shown on the left. To add a new exception, enter a date on the right and press Add. To change an exception, highlight it in the list, enter the new date on the right and press Change. To delete an exception, highlight it in the list and press Delete.

  • You can restrict an alarm not to occur on holidays by checking Exclude holidays. This does not change the way the alarm is scheduled; it simply suppresses the alarm whenever it happens to trigger on a holiday. You can select your holiday country or region in the Configuration dialogue.

  • You can restrict an alarm to occur only during working time by ticking Only during working hours. This does not change the way the alarm is scheduled; it simply suppresses the alarm whenever it happens to trigger outside working hours. Work days and working hours are set in the Configuration dialogue.

Sub-Repetition

You can use the Sub-Repetition button to set up a repetition within a repetition. In this case, each time the alarm is due as specified in the main recurrence, instead of being triggered just once it is triggered repeatedly in accordance with your sub-repetition specification. For example, to set up an alarm which repeats every hour from noon to 6 pm each Thursday, you would set up a weekly recurrence on Thursday at 12:00, and use the Sub-Repetition dialogue to specify an interval of 1 hour and either a count of 6 or a duration of 6 hours.

In the Sub-Repetition dialogue which is displayed when you click the Sub-Repetition button, tick Repeat every to set up a repetition, or untick it to remove the repetition. If Repeat every is ticked, set up the repetition as follows:

  • Enter the time interval between repetitions in the controls beside Repeat every. Select the desired time units (e.g. days) and then enter the number of units.

  • Specify either the repetition count or its duration:

    • Select Number of times to enter how many times the alarm should be triggered after the main recurrence. So, for example, to make the alarm occur 4 times at each main recurrence, i.e. 3 additional times, you should enter 3 here.

    • Select Duration to enter the total time period during which the alarm should be repeated. This need not be an exact multiple of the repetition interval; it will automatically be rounded down when you click OK.

Note

To prevent overlapping sub-repetitions for the same alarm, a sub-repetition's duration is restricted to be less than the longest interval between main recurrences. Each time the alarm recurs as specified in the main recurrence, any still active sub-repetition which started at the previous recurrence is automatically cancelled.

Other Controls

For display alarms, the Confirm acknowledgement tick box lets you specify whether you will be prompted for confirmation when you close the alarm message window. This may be used as a safeguard against accidental acknowledgement of alarms.

Select Show in KOrganizer to add the alarm to KOrganizer's active calendar, where it will appear as an event without an alarm. This option allows you to track alarms in KOrganizer while still making use of KAlarm's functions.

Note

If you later modify or delete the alarm in KAlarm, the KOrganizer event will be modified or deleted correspondingly. But if you change the event in KOrganizer, the alarm in KAlarm will not be affected.

Press the Load Template button to select a template to preset the dialogue with, as described in Creating and Manipulating Alarms.

Press the Try button to test the alarm and check whether it works correctly. The alarm is executed just as if it had been scheduled in the normal way.

Press the OK button when all details are correct, to add the alarm to the scheduled list. Note that when editing an existing alarm, the OK button is disabled while no changes have been made.