XALARM(1) X Version 11(Release 4) XALARM(1)
NAME
xalarm - alarm clock for X
xmemo - memo for X
xfortune - fortune for X
xyow - yow for X
SYNOPSIS
xalarm [-toolkitoption ...] [-option ...] [messagetext]
xmemo [-toolkitoption ...] [-option ...] [messagetext]
xfortune [-toolkitoption ...] [-option ...]
xyow [-toolkitoption ...] [-option ...]
DESCRIPTION
xalarm is an interactive alarm program for X11, analogous to leave(1),
but much more powerful. You can set the alarm either on the command line
or by using the popup window. At the appropriate time, xalarm pops up a
window to tell you that your time is up. The time the alarm is to
trigger may be a specific time or a time for xalarm to wait before
triggering.
You can tell xalarm to pop up warning windows at specified times before
the alarm is to trigger, in order to warn you of the impending triggering
of the alarm, and specify what message you want the alarm to display.
You can also make xalarm read alarm times and dates, along with the
message to display in the alarm, from a file. This enables you to forget
your regular or important appointments, but xalarm will tell you by
popping up at the appropriate time.
The alarm window itself consists of a box of buttons and an area
containing the alarm message. To give you an opportunity to carry on
after the alarm has triggered and be late anyway, xalarm allows you to
snooze the alarm.
SETTING THE ALARM
If no time is specified, xalarm will pop up a window in order for an
alarm time to be entered. This form is suitable for inclusion as a menu
option under a window manager.
The window is also popped up if an invalid alarm or warning time is given
(see below for time syntax), or if you specify that confirmation should
be sought before setting the alarm.
The window gives you an opportunity to change the alarm setting, warning
times, and the message xalarm will display when the alarm is triggered.
10/89 Page 1
XALARM(1) X Version 11(Release 4) XALARM(1)
The popup resizes itself to edit any message larger than the space given
by default. The keymap used by the Athena Dialog widget is modelled on
the text buffer keymap of the editor/environment emacs(1), while text may
be entered when the pointer is anywhere within the popup.
This popup window comprises of three separate windows, dealing with the
alarm time, the warning time(s) and confirmation of all the settings
(where you can also re-edit the alarm message). If the window is popped
up, then you can re-edit the alarm time or warning time(s) by switching
through the windows using the edit buttons. Confirmation of a window's
settings is made using the enter buttons, and the translations resource
is set so that the return key will do the same thing. If confirmation is
not enabled, then the window for confirmation of all settings will not be
popped up even if the other windows are.
Also see the examples section.
USING AN ALARM FILE
You can make xalarm look for alarm times and messages in an alarm file.
This form is suitable for inclusion in your X start up or initialisation
script.
If the environment variable XALARM is set, it is assumed to be the name
of the file to read from. If it is not absolute, it is assumed to be
relative to your home directory. Otherwise, xalarm tries .xalarm in your
home directory.
Each line in the file should consist of the date the alarm is to trigger,
optionally followed the by time and/or message. If they are present,
they must be separated from the date by a `-' on its own. If both are
given, the time must come first, but if no time is specified, the alarm
will trigger immediately.
The date is in the form of that given by date(1), (day of week, month,
day of month) but can be in any order and case is not significant. If
any is omitted, it is assumed to correspond to today. The month and day
of the week must consist of at least the first 3 characters of the name.
Any line beginning with `#' or `!' is ignored, so this can be used to
insert comments in the alarm file.
All other command line options and resources still apply. Also see the
examples section.
TIMES
The time format is quite flexible and natural. The definition is that
for times given with 3 or 4 digits, the last 2 digits are always assumed
to be minutes. Absolute times may be suffixed with `am' or `pm', and are
assumed to be in hours if given with 1 or 2 digits. Times relative to
the present time must be prefixed by a `+', and are assumed to be in
minutes if given with 1 or 2 digits. The hours and minutes can be
separated with a `:', `.' or `-'. The format is a super-set (by far) of
Page 2 10/89
XALARM(1) X Version 11(Release 4) XALARM(1)
the format recognised by leave(1). Also see the examples section.
SNOOZING THE ALARM
Snoozing is done by selecting a time to snooze using the +mins buttons
(they can be pressed as often as necessary) and pressing the snooze
button. The snooze time may be zeroed by clicking on the snoozetime
button (it has these two functions; display and zero). For the really
lazy, the initial value of snoozetime can be set by either a command line
option or by its resource.
MORE ON XALARM
You can also specify that a number of words from the alarm message should
be displayed with any warnings, in case you've forgotten what you set it
for. If none are to be used, the warning will only indicate when the
alarm is due.
Even after you have set the alarm and confirmed it, you can reset the
alarm as long as you know the xalarm process number. This can be found
by using the command line option to list process numbers, or ps(1).
xalarm makes maximum use of resources, as well as having a number of
command line options, and these can be used to control most of the
appearance of xalarm and (just about) all of its behaviour. Both command
line options and useful resources are listed below.
When xalarm is invoked it immediately attempts to fork off a child and
exit itself, leaving the child to continue with the alarm. The child
disappears when the X session on which display xalarm is using is
terminated.
You can exit from xalarm at any time by pressing the available quit
button.
XMEMO, XFORTUNE & XYOW
In reality, xmemo is just a front end to xalarm (implemented as xalarm
-time +0 -nowarn), while xfortune and xyow are front ends to xmemo
(implemented as xmemo `fortune`"" etc.). Options supplied to them on
the command line still override these defaults, however.
Note that xfortune and xyow require fortune(6) and yow(6) respectively -
yow(6) comes with emacs(1). Also note that since they are front ends to
xmemo, you can actually give extra message text to include on the command
line. If you specify a time in the future, you can edit the message text
when asked to confirm (if enabled).
OPTIONS
xalarm accepts all of the standard X Toolkit command line options along
with the additional options listed below:
-h[elp] Print a (possibly) helpful usage message.
10/89 Page 3
XALARM(1) X Version 11(Release 4) XALARM(1)
-v[ersion]
Print out the version number of xalarm in the form
version.patchlevel.
-appointments
This option makes xalarm read alarm times from a file. Each line
in the file should consist of a date and optional time and/or
message. If the date specified at the beginning of the line is
today and the time has not passed, then the time is used to set
an alarm. Note that this must be given as the first option on
the command line.
-t[ime] time
This option indicates at what time the alarm is to be triggered.
Times relative to the present must be preceded with a `+',
absolute times may end with `am' or `pm'.
-w[arn] time[,time...]
Indicate the time(s) before the alarm is due to trigger when a
warning should be given. They need not be in any particular
order, and should be in the same format as for relative times, as
above, but without the preceding `+'. Note that multiple times
must be separated by commas but without any spaces.
-c[onfirm]
This option overrides the resource value and forces xalarm to ask
for confirmation, unless the alarm is due to trigger immediately.
-warnwords [-ww] number of words
Indicate the number of words from the alarm message you wish to
display with the warning.
-l[ist] List the process numbers of any xalarm processes running on the
current host. Note that this lists what ps(1) thinks are xalarm
processes, and only on the current host.
-r[eset] pid
Send a signal to the process number pid. If the process is an
xalarm, it will pop up the confirmation window to allow you to
re-edit the alarm settings.
-s[nooze] time
Indicate the time that snoozetime should initially have when the
alarm triggers. It should be in the same format as for relative
times, but without the preceding `+'.
-nowarn [-nw]
This option overrides the resource value and forces xalarm not to
give any warnings. This is the same as setting the warning times
resource to the empty string.
Page 4 10/89
XALARM(1) X Version 11(Release 4) XALARM(1)
-noconfirm [-nc]
As above, but prevents any confirmation being sought.
-nowarnwords [-noww]
This option overrides the resource value and forces xalarm not to
display any of the alarm text with any warnings. This is the
same as setting the warningwords resource to zero.
-bell -beep -b
These options override the resource value and force xalarm to
ring the terminal bell when any warnings and the alarm trigger.
-nobell -nobeep -nb
As above, but prevents any warnings and the alarm ringing the
bell when they trigger.
messagetext
The remaining unrecognised text is used as the message displayed
with the triggering of the alarm. Note that each separate
argument is assumed to be a single line, so words must be quoted
if they are to appear on the same line. For example:
% xalarm "On one line" Secondline "Third line"
It is a good idea always to use quotes, even when a line is only
one word. Newlines within arguments are recognised, so that
input from other tools can be used:
% xalarm -time +0 "`fortune -l`"
Also note that xalarm deletes its copy of any message given on
the command line, so your boss can't see what it is by looking at
the xalarm process.
EXAMPLES
An entry in an X initialisation file, before the window manager is
executed, making xalarm check the alarm file for today's appointments,
asking for confirmation before each of the alarms are set, and using up
to three words from the alarm message in any warning message:
xclock &
xbiff &
xalarm -appointments -confirm -warnwords 3 &
exec twm
The alarm file might contain, for example, the lines:
# This is just a comment.
! So is this. Format is: date [- [time] [message]]
Wednesday - 12:30pm Football !!!
Sun 29 september - 9pm Drag yourself home.
10/89 Page 5
XALARM(1) X Version 11(Release 4) XALARM(1)
Oct 4 - Contrib sometime today...
So that every Wednesday I have an alarm set for 12:30pm; on Sunday
September 29 there is an alarm to be set for 9pm; on October 4 the alarm
is to trigger straight away.
A twm(1) window manger entry which makes xalarm ask for confirmation and
ring the terminal bell when any warnings and the alarm are triggered, and
have the snooze time initially set to 5 minutes:
Menu "Utilities" {
...
"alarm": f.exec "xalarm -confirm -snooze 5 -beep &"
...
}
To set an alarm for 5 o'clock in the evening, without the default
warnings or confirmation, but with the default alarm message:
% xalarm -time 5pm -nowarn -noconfirm
To set an alarm for 2 hours in advance, warning 1 minute and 5 minutes
before it, with a message other than the default:
% xalarm -time +2.00 -warn 5,1 "Get off your bottom"
To set an alarm for 4.30 (not specifying am/pm, so it is whichever is
first), with the default warnings and a message other than the default:
% xalarm -time 4:30 "Time to sneak off home!"
Assuming that there is only one xalarm running, which we want to reset,
we first find out its process number, and then we can reset it:
% xalarm -list
xalarms: 12345
% xalarm -reset 12345
To put a 2 line message on the display foo immediately (this will only
work if the display foo can be opened):
% xmemo -display foo:0.0 "Bob!" "The bar for lunch?"
To quietly display a fortune at a specific geometry:
% xfortune -geometry +10+300 -nobeep
To display a Zippy quote (yow!!!) at a specific geometry in 5 minutes and
(characteristically) ring the bell:
Page 6 10/89
XALARM(1) X Version 11(Release 4) XALARM(1)
% xyow -geometry +100+100 -time +5 -beep
RESOURCES
The widget structure is as follows:
XAlarm
Alarm!
alarm
buttons
quit snooze snooze1 snooze5 snooze15 snoozetime
message
When?
when
label value ok toggle quit
warnings
label value ok toggle quit
confirm
label value ok cancel quit
Warning!
warning
dismiss message quit
Some example resources are:
! For some nice colours...
XAlarm*background: LightYellow
XAlarm*foreground: IndianRed
XAlarm*Command.background: IndianRed
XAlarm*Command.foreground: LightYellow
! But this is what you normally get...
XAlarm*background: White
XAlarm*foreground: Black
XAlarm*Command.background: Black
XAlarm*Command.foreground: White
! Perhaps the most commonly used resources...
XAlarm.bell: True
XAlarm.confirm: True
XAlarm.warnings: 5,15
XAlarm.warningwords: 0
XAlarm.snooze: 0
! If you want a more compact alarm window, try these...
XAlarm.Alarm!.alarm.buttons.snooze1.fromVert: quit
! This will vary depending on button labels & font...
XAlarm.Alarm!.alarm.buttons.snooze1.horizDistance: -93
XAlarm.Alarm!.alarm.buttons.snooze5.fromVert: quit
XAlarm.Alarm!.alarm.buttons.snooze15.fromVert: quit
XAlarm.Alarm!.alarm.buttons.snoozetime.fromHoriz: snooze
! Plus, if you want...
XAlarm.Alarm!.alarm.message.fromHoriz: buttons
10/89 Page 7
XALARM(1) X Version 11(Release 4) XALARM(1)
! This will vary depending on button labels & font...
XAlarm.Alarm!.alarm.message.vertDistance: -33
! Some other defaults...
XAlarm*font: *-times-bold-r-*-*-14-*
XAlarm.Alarm!.alarm.message.font: *-times-bold-i-*-*-34-*
XAlarm.Alarm!.alarm.background: Black
XAlarm.Alarm!.alarm.message.label: Alarm Call!!!
XAlarm.Alarm!.alarm.buttons.quit.label: Quit
XAlarm.Alarm!.alarm.buttons.snooze.label: Snooze
XAlarm.Alarm!.alarm.buttons.snooze1.label: +1 min
XAlarm.Alarm!.alarm.buttons.snooze5.label: +5 mins
XAlarm.Alarm!.alarm.buttons.snooze15.label: +15 mins
TOOLKIT OPTIONS
The following standard X Toolkit command line arguments are commonly used
with xalarm:
-display display
This option specifies the X server to contact.
-geometry geometry
This option specifies the preferred size and position of xalarm.
It is a little meaningless to specify a size; it is as large as
need be.
-xrm resourcestring
This option specifies a resource string to be used. This is
especially useful for setting resources that do not have separate
command line options.
ENVIRONMENT
DISPLAY to get the default host and display number.
XENVIRONMENT
to get the name of a resource file that overrides the global
resources stored in the RESOURCE_MANAGER property.
XALARM to get the name of the appointments file. Otherwise, it is
assumed to be the file ~/.xalarm. Any file not given as the full
path is assumed to be relative to the home directory.
SEE ALSO
X(1), leave(1), emacs(1), twm(1), ps(1), date(1), fortune(6), yow(6)
BUGS
Times: xalarm believes, and is thus at the mercy of, the system clock.
If the time is relative to the present and confirmation is
sought, the alarm and warnings are set from when the time is
confirmed, not from when xalarm was invoked.
Page 8 10/89
XALARM(1) X Version 11(Release 4) XALARM(1)
The response when an invalid time or warning time is entered is
not particularly friendly or helpful.
Can't cope with specified times more than 24 hours away. Can't
accept things like:
% xalarm -time +70
It must be in proper hours and minutes, otherwise things like the
following would be ambiguous:
% xalarm -time +100
Date checking when reading alarms from the alarm file is pretty
rudimentary - if a date is semantically false but syntactically
correct, xalarm will not notice.
Only times corresponding today's date are checked, even if xalarm
-appointments is invoked one minute before midnight.
Editing:
The dialog box uses a subset of the emacs(1) editor/environment
keymap for text buffers (which is certainly not a bug!).
However, the return key event is translated by default into the
confirm button event, as it is translated similarly in the alarm
time and warning dialog boxes. To insert a newline, use ctrl-m
(since under emacs(1) the return key is a synonym for ctrl-m,
under X they generate different events), or just change the
relevant resource(s) so that return produces the desired effect.
The resources, followed by the necessary value, are:
XAlarm.When?.when.value.translations
XAlarm.When?.warnings.value.translations
XAlarm.When?.confirm.value.translations
#override <Key>Return: newline()
Resetting:
Signalling is implemented very simply, and if the process
signalled is not an xalarm, strange things may occur. Usually,
nothing will happen.
Exiting:
Normally desirable, xalarm is killed when the X session on which
display it is using is terminated whether you like it or not.
Input: Doesn't take input from a pipe etc.
COPYRIGHT
Copyright 1991, 1992, Simon Marshall.
10/89 Page 9
XALARM(1) X Version 11(Release 4) XALARM(1)
AUTHOR
Simon Marshall, PhD Self Defense Group, Dept. of Computer Science,
University Of Hull, UK. S.Marshall@Hull.ac.UK
CONTRIBERS
Massive thanks have to go to Bill Leonard, Harris Computer Systems
Division, Florida, for harassing me with suggestions for improvements to
make xalarm a useful tool and this manual page easier to understand, and
Andreas Stolcke, International Computer Science Institute, Berkeley, for
his help fixing code. Without both, xalarm would still be pretty much as
version 2.
Thanks also to J Braham Levy, Stefan Haenssgen, Jamie Zawinski, Jason
Venner and Kimmo Suominen for their help with version 3.
For their help and suggestions with previous versions of xalarm, I would
also like to thank (in no real order) Dave Brooks, Reiner Hammer, Jay
Lawlor, Janet Anstett, Gordon Freedman, Francois-Regis Colin and Jeffrey
Mast. If I've missed anyone, sorry.
COMMENTS
I'd like some; comments, suggestions, code, bug reports and fixes, etc.
Don't forget to include which version of xalarm you are using (from
xalarm -version), machine/OS, X11 release & patch number, window manager
etc.
Page 10 10/89