xcal(1) USER COMMANDS xcal(1)
NAME
xcal - calendar with alarms and a notebook for X11
SYNTAX
xcal [ -debug ][ -alarmscan ]
DESCRIPTION
Xcal is an interactive calendar program. The user interface
has several levels. When started xcal displays today's date
in a small command box on the screen. The date changes at
midnight. The command box is intended to sit on the screen
as a companion to the xclock program. The format of the
command box may be altered using the resource manager, so
you are not stuck with my preferred format. A small button
in the top level window can be pressed to inspect todays
appointments and also to edit or display a memo file.
The calendar and notebook functions are accessed by clicking
the mouse buttons inside date portion of the command window.
1) Mouse button one pops up a calendar `strip' for the
current month. The strip has some header lines and
then one line per day of the month. The `line per day'
display contains the day in the month and the day of
the week. Today may be highlighted specially - the
notion of Today alters at midnight. The strip has a
help button which displays a description of the panel.
The command buttons in the header line allows the user
to bring up a strip for the previous or the next month.
2) Pressing mouse button two in the date area will bring
up a dialog box which allows the user to select any
month of any year (yes, September 1752 is supported).
The month may be input as month name or abbreviation,
even though the prompt indicates a more restrictive
format.
3) Pressing mouse button 3 in the command window causes
the whole program to exit, a dialog box is used to ask
the user for confirmation.
Like xcalendar, daily events are stored in set of files, one
for each day. The file is created by entering a simple text
editor (the standard text widget) which is started by press-
ing the right hand side of the appropriate day line in the
strip. If the file exists its data is displayed as the
label in the command button. This allows the user to use
the first few lines of the file in an intelligent manner
since X11R4 allows multiple lines of text to appear in a
command button. The strip width is sized by the length of
the header, and users who wish to display a wider strip to
show more of the stored information should widen the strip
X Version 11 R4 Last change: September 1990 1
xcal(1) USER COMMANDS xcal(1)
using the minStripWidth resource (see below).
Data files are stored in a directory usually called Calendar
under the user's home directory. Each file is stored in a
subdirectory containing all the data for a particular year.
This is incompatible with xcalendar, the user may specify
that compatibility should be maintained.
Alarms are supported by xcal. When a line in the data file
starts with a digit it is assumed to be a time specification
and a candidate for an alarm. The line contains a string
giving the alarm time, and a text string displayed in a
dialogue alarm box. When the time is reached, or at some
user specified time before that, a dialogue box will be
popped up onto the screen. The dialogue box will automati-
cally go away after two minutes, unless the `Stick' button
is pressed glueing the box onto the screen. The box can be
made to go away at any time by hitting the `Unpin' button.
Xcal tries to be liberal about the times that it under-
stands. Time specifications are: h, hh, hhmm, hmm, hh:mm,
h:mm, hh.mm, h.mm; all of these may be optionally followed
by an am/pm indicator - one of: A, a, AM, am, Am, aM, P, p,
PM, pm, Pm, pM. Times must always be followed by at least
one space or tab. Some legal examples are:
12:00 Lunch - Meet Joe at Burger King
14.30 Meeting in the cafeteria
2:30p Ring Mark
7pm Pizza
Xcal also supports timed command execution from the data
file. To trigger a command, the data part of the line
starts with an exclamation mark, eg:
4.30pm !xmessage -message 'ring home'
It is also possible to make xcal execute a command whenever
an alarm is triggered, see the cmd resource below.
The Memo function of Xcal is accessed by pressing the non-
date portion of the command window. Currently this shows a
bitmap diagram of three mouse buttons. Clicking the left
mouse button in this area brings up a complex panel. The
top half of the panel displays the information held in the
diary for today; you cannot edit the data from here - and
must open the diary strip to change the data. The bottom
half of the panel is an edit window displaying the contents
of a file usually called `memo' in the Calendar directory.
The idea of this panel is to allow you to access your
current information in one button click.
OPTIONS
The -debug switch causes contents of the initial date window
X Version 11 R4 Last change: September 1990 2
xcal(1) USER COMMANDS xcal(1)
to be incremented once a second rather than once per day.
The -alarmscan switch prints debugging information about the
alarm system on standard output.
PANEL MAP
Xcal makes extensive use of the resource manager. The user
needs to know the names of the various panels and widgets
which comprise the application.
XCal Toplevel application
form Form containing two buttons
today Memo Command button
date Strip Command button
Then we have various popups. The Calendar Strip is:
"Mon Year" the popup shell
Month panel containing the strip
header label containing month and year
action form containing < quit > buttons
back command containing < - last month
quit command containing exit button
next command containing > - next month
help command generating help
"dd DDD" form containing day button (lots of these)
label label containing dd DDD, day of the month
and day of the week
info command containing the file data
The Edit Window is:
edit the popup shell
panel the panel inside the shell
title the form containing the first line
quit the exit button
The Help Window is:
help the popup shell
helpPanel the panel inside the shell
helpForm the form containing the title line
quit the exit button
helpText the text widget showing the information
X Version 11 R4 Last change: September 1990 3
xcal(1) USER COMMANDS xcal(1)
The Alarm Window is:
alarm the popup shell
alarmPanel the panel inside the shell
alarmForm form for top line
alarmQuit the exit button
alarmHold the hold button
alarmTitle the title on the alarm window
alarmText the text widget for displaying
The Memo Window is:
memo the popup shell
memoPanel the panel inside the shell
title Top line form widget
quit the exit button
help the help button
date display today's date
display text from today's date file
memoMiddle Middle line form widget
save Save button
memoTitle text title of middle line
memoText Text widget showing memo file
The Middle button date selection popup is:
question the popup shell
newdate the dialog widget
ok the OK button
cancel the cancel button
The Right button exit selection popup is:
question the popup shell
exit the dialog widget
yes the yes button
no the no button
An error is shown when a multiple attempts are made to edit
the same day file.
question the popup shell
noedit the dialog widget
ok the OK button
A dialog box is popped up when an attempt is made to exit
X Version 11 R4 Last change: September 1990 4
xcal(1) USER COMMANDS xcal(1)
from an editing box without saving the file.
check the dialog widget
yes the yes button
no the no button
RESOURCES
As with all standard X applications, xcal may be customised
through entries in the resource manager. It is a serious
mistake to install Xcal without putting the resource ini-
tialisation file Xcal in /usr/lib/X11/app-defaults.
Resource class names are listed below; resource instance
names are identical, except the first letter is in lower
case. The following resource manager entries are defined:
Debug If True enables accelerated time. Alarms
will not function correctly. Default:
False.
AlarmScan If True enables printing of alarm related
debugging information to the standard
output. Default: False.
ReverseVideo If true display the output in reverse
video.
Format The printf string used to create
the contents of the top command button.
The default is "%2d %s %d", the arguments
to this command are presented in a
default order: day, month string and
year. The order is controlled by the
Order resource which contains the default
string "dmy". These two resources should
allow all forms of date printing.
Order Legal combinations are: dmy, ymd, mdy,
ydm. The default is dmy.
MarkBackground The background colour for highlighting
entries. Default Black.
MarkForeground The foreground colour for highlighting
entries. Default White.
MarkToday If True then highlight today. Default
True.
TodayBackground the background colour when marking,
default Black.
X Version 11 R4 Last change: September 1990 5
xcal(1) USER COMMANDS xcal(1)
TodayForeground the foreground colour when marking today,
default White.
FontToday Today may be marked by using a special
font, if this is desired the font is
given by this resource. Default is to
use the default font.
Directory The name of the directory under the home
directory where the day files are stored.
Default: Calendar.
XcalendarCompat If true then subdirectories are not
created in the Calendar directory. This
flag is not relevant when files are being
read, so users can use both programs with
existing data files. Default: False.
GiveHelp If True than access to the help informa-
tion is given. If False, help buttons
disappear and the initial message is not
printed. Default: True.
InitialCalendar If True then the calendar for this month
is automatically displayed on startup.
If False, the calendar is not automati-
cally displayed. Default: False.
InitialEdit If True then an edit window for today is
automatically displayed on startup if a
file exists for today's date. If False,
the edit window is not automatically
displayed. Default: False.
UseWmTitle If True display the month and the year at
the head of each strip. This information
is duplicated if your window manager uses
titles so it is nice to be able to turn
it off. Default: True.
MinStripWidth The width of month strips are set by the
top line, which usually displays the
month and year. The whole strip can be
widened from this default value by set-
ting this resource to be non-zero.
Default: zero (i.e. off).
TextBufferSize the maximum number of bytes which we are
prepared to deal with in an edit window.
Default: 2048 bytes.
Alarms whether or not to enable the alarm
X Version 11 R4 Last change: September 1990 6
xcal(1) USER COMMANDS xcal(1)
system. Default: True.
Update When scanning for alarms in the data file
Xcal inspects it at program startup time
and also when it is edited using the nor-
mal built-in editing mechanism. However,
if some external program changes the data
file xcal will not see the new contents
and new alarms will not be set. Setting
this resource to non-zero will force xcal
to scan the data file every `update'
minutes looking for alterations in size
and modification date. When it detects
that the file is altered, then it will
rebuild the internal alarm list.
Default: zero.
Nbeeps When an alarm window is popped up, it is
accompanied by `Nbeeps' beeps. Default:
3.
Volume Control the loudness of the beep.
Default: 50.
Cmd This resource contains a command that is
executed by calling the shell when every
alarm is triggered. The command is
passed the contents of the data line as
one argument.
Countdown contains a comma separated string of
numbers; for example: 10,5,0. The string
allows the user to customise warning
alarms: so in the example, alarm boxes
will be displayed 10 minutes before the
stated time, 5 minutes before the stated
time and exactly on the stated time.
Commands lines in the data prefaced by a
`!' will always be triggered exactly at
the stated time. Default: 10,0.
Autoquit Each dialogue box containing an alarm
message contains an `Unpin' button allow-
ing the user to remove the message from
the screen by using mouse button one.
Additionally, the message box can remove
itself from the screen after a specified
period, this resource gives that timeout
in seconds. If the resource is set to
zero, then the user is always forced to
take explicit action to remove the box.
Default: 120, alarm boxes disappear after
X Version 11 R4 Last change: September 1990 7
xcal(1) USER COMMANDS xcal(1)
2 mins.
Alarmleft contains a printf string that is
displayed in the label at the top of an
alarm box when countdown is in operation
and there is some time before the stated
time. The time before the stated time is
supplied as the second argument to
printf. Default: ``%d minutes
before...''
Alarmnow contains the fIprintf string that is
displayed in the label at the top of an
alarm box when the stated time is
reached. Default: ``Time is now...''.
UseMemo enables the use of the memo feature.
This defaults to ``True'', but is present
to allow users to make XCal have as it
used to.
MemoLeft affects the placing of the memo button in
the top level date window. The default
is `True' meaning that the button box is
placed on the left of the date portion.
Setting this to `False' will place the
button box to the right of the date por-
tions.
MemoFile gives the name of the memo file within
the Calendar directory. The default is
`memo'.
MaxDisplayLines controls the maximum number of text lines
that can placed in the top half of the
memo panel. The top hald will normally
size to the number of lines in the diary
file for the day, unless the number of
lines exceed the value in this resource.
This ensures that today's events do not
dominate the memo panel. Default: 5
lines.
January February and so on. The names of the
long form of the month name.
Jan Feb and so on. A short form of the month
name - done this way because I doubt that
writing with %3s works in all languages.
Changing this resource means that the
data file will no longer be compatible
with xcalendar .
X Version 11 R4 Last change: September 1990 8
xcal(1) USER COMMANDS xcal(1)
Sunday Monday and so on. The names of the days,
these are currently set to a three char-
acter short form.
FILES
$HOME/Calendar/*
xc<dd><Mon><Year> A data file is day, Month in three letter
format and the year.
xy<Year> A year directory.
The standard resource database can be found in
/usr/lib/X11/app-defaults/Xcal. Assuming that this is where
the system admin installed it.
SEE ALSO
xrdb(1), xcal_cal(1)
BUGS
There should be some way of removing several edit windows
from the screen at once.
It would be nice to be able to cut from the date box on the
screen.
Setting an alarm 1 minute in the future may not work.
Countdown does not work in the early hours of the morning,
if you have a ten minute countdown and an alarm set at 0005
- then you will not get warning at 2325.
AUTHOR
Copyright 1989,1990 by Peter Collinson, Hillside Systems All
rights reserved. Placed into the public domain.
Much of the xcalendar program was plundered to create xcal ;
author is: Roman J. Budzianowski, MIT Project Athena
Thanks to Ed Gould, Mt Xinu for the support for the calen-
dar(1) program. Thanks to Mark Majhor, Sequent for the
basis of the alarm code. Thanks to Rod Whitby, Austek
Microsystems Pty. Ltd., Australia for the ideas of the
Stick/Unpin code for alarms and for prompting me to add the
memo code.
X Version 11 R4 Last change: September 1990 9