xcal(1) X Version 11 R4(September 1990) 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 appointments for today. This
generates a panel showing information from the calendar file for today
and information from a set of seven daily files holding regular
commitments. Finally, the memo panel displays and allows the edit of 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 pressing 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 using the minStripWidth resource (see below).
10/89 Page 1
xcal(1) X Version 11 R4(September 1990) xcal(1)
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 automatically 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 understands. 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, clicking on the button again will pop is back down again. 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 next section of the panel displays the information
held in the weekly files. Again you cannot directly change the text in
this area, you must press on the Edit button to bring up a strip enabling
you to change things. The bottom portion 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.
It is obviously possible to change Xcal's data files without using the
inbuilt text widget editor. In general, Xcal will not notice this.
Editing random day files with a standard text editor will not change the
contents of any displayed strips until the strips are popped down and up
again. Xcal knows what days have been altered when the text widget is
Page 2 10/89
xcal(1) X Version 11 R4(September 1990) xcal(1)
used to edit the day files, and will reflect any change immediately into
the displayed strips.
You can make Xcal take notice of today's date file and the current memo
file. The `Update' resource sets a polling time in seconds. When the
clock fires and today's file has been altered, the alarm list is rebuilt
from the current date file and the memo panel is updated. The bottom
part of the memo panel is also updated if the `memo' file has been
altered on the clock tick.
OPTIONS
The -debug switch causes contents of the initial date window 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 weekly popup strip is:
weekly the popup shell
weekly panel containing the strip
header label containing the title
action form containing quit and help
quit command containing exit button
help command generating help
10/89 Page 3
xcal(1) X Version 11 R4(September 1990) xcal(1)
shortday form containing days
label label containing 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
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
weeklyMemo form for the Memo title line
weeklyEdit Edit button
weeklyTitle Title area
2 display text from today's weekly file
memoMiddle Middle line form widget
save Save button
memoTitle text title of middle line
memoText Text widget showing memo file
Page 4 10/89
xcal(1) X Version 11 R4(September 1990) xcal(1)
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 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 initialisation 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 format used to create the contents
of the top command button, the title in an edit window
and the title in the memo window. The default is "%s
%2d %s %d", the arguments to this command are
10/89 Page 5
xcal(1) X Version 11 R4(September 1990) xcal(1)
presented in a default order: day, month string and
year. The order is controlled by the Order resource,
this contains the default string "wdmy".
Order This resource gives the order that various arguments
are presented to the printf using the format string
defined above. Legal combinations using day, month
and year are: dmy, ymd, mdy, ydm. The name of today
can be inserted at the start of the string by using
one of the formats: wdmy, wymd, wmdy, wydm. It can be
entered at the end by using on of the formats: dmyw,
ymdw, mdyw, ydmw. In case you are wondering the `w'
stands for `day' of the week. Beware that altering
this resource from the default may force you to change
the format string, see the previous resource. The
default is wdmy.
DateYearIsTwoDigits
The display of the year in the date strip is
controlled the format above. If this resource is true
then the year will be displayed as a two digit number;
if false the whole four digits will be displayed.
Default: False.
EditYearIsTwoDigits
The display of the year in the edit boxes is
controlled by the format above. If this resource is
true then the year will be displayed as a two digit
number; if false the whole four digits will be
displayed. Default: False.
MemoYearIsTwoDigits
The display of the year in the memo box is controlled
the format above. If this resource is true then the
year will be displayed as a two digit number; if false
the whole four digits will be displayed. Default:
False.
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.
TodayForeground the foreground colour when marking today, default
White.
Page 6 10/89
xcal(1) X Version 11 R4(September 1990) xcal(1)
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 information 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 automatically 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.
InitialMemo If True then the memo window is automatically
displayed on startup. 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
setting 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 system. Default:
True.
Update When scanning for alarms in the current day file Xcal
inspects it at program startup time and also when it
is edited using the normal built-in editing mechanism.
However, if some external program changes the todays
file xcal will not see the new contents and new alarms
will not be set. Setting this resource to non-zero
10/89 Page 7
xcal(1) X Version 11 R4(September 1990) xcal(1)
will force xcal to scan the file every `update'
seconds 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 allowing 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 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.
Page 8 10/89
xcal(1) X Version 11 R4(September 1990) xcal(1)
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 portions.
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 .
Sunday Monday and so on. The long names of the days: Sunday,
Monday etc. These are used in titles: the top level
widget, the title of an edit window and the memo
frame.
Sun Mon and so on. The short names of the days - used in
date strips.
Weekly The word `Weekly' used in various places.
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.
xw<Day> A data file for the weekly code, one per day.
memo The memo file.
The standard resource database can be found in /usr/lib/X11/app-
defaults/Xcal. Assuming that this is where the system admin installed
it.
10/89 Page 9
xcal(1) X Version 11 R4(September 1990) xcal(1)
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.
Alarms set at 0000 probably won't work.
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 calendar(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.
Page 10 10/89