xcal(1) X Version 11 R5 xcal(1)
September 1990
NAME
xcal - calendar with alarms and a notebook for X11
SYNTAX
xcal [ -debug ][ -alarmscan ][ -format fmt ][ -editformat fmt ][
-stripformat fmt ][ -clocktick tick ][ -u username ]
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 that 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
layout. You can set the time in the window too, if you wish (see the
format resource). Access to further levels in xcal is made by
clicking a mouse button in the command box. The command box is split
into several areas and clicking on one of these will popup a window
supporting a new function.
Clicking with mouse button one on the question mark in the command box
pops up a help window. Xcal comes with many help buttons. When you
are convinced they are no longer any use to you, they can all be
turned off using an X resource. A small button containing a `mouse'
bitmap can be pressed with mouse button one 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. The panel also contains a text
scratchpad, `the memo panel'. This allows the editing of a memo file.
The calendar functions are accessed by clicking a 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.
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
dialogue 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 date label 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. If the file exists when the strip is
started, its data is displayed as the label in the command button
- 1 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
on the right-hand side of the month strip. The file is created
and edited 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. You can also add data to the
file by selecting a string on the screen and clicking with the
middle button on the right-hand side of the month strip. The
string is appended to the file for the day. This short-hand
allows one entry to be loaded into several day files. The width
of the month strip is computed from the width of the header.
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). The colours and fonts used in the strip is
controllable by resources. The widget that comprises each line
in the strip is tagged with the short form name of the day, so
it's easy to vary the strip display showing weekends differently
from the weekdays. 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 the 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 that pops up
when the alarm fires. You can also arrange for countdown alarms
to fire, so that you can be told that something is about to
happen. These dialogue boxes 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. When specifying alarms, 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
You can make a time like 2:30 mean 14:30 by setting the resource
AlarmWarp to be true. If this is the case, an alarm hour will be
promoted to a PM time if it is found to be between the range of
zero and the value of the resource minAlarmWarp. 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' The exclamation mark
can also be replaced by the string `%cron'. 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
- 2 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
accessed by pressing the non-date portion of the command window.
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 it back down again. The
top half of the panel displays the information held in the diary
for today; pressing the Edit button here will start an edit box
for today. 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
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
Version 4 of Xcal permits one user to view another's calendar by
giving the -u option followed by the user's login name. The user's
calendar storage area is assumed to be called `Calendar' in their home
directory. The facilities are somewhat rudimentary. First, the main
date box will have the user's login name appended to the date format
string. When a month strip is generated, you will be given read-only
access to their calendar files, assuming that the file permissions
allow you to read them. This is intended to be one step better than
using cat on their calendar files. The -debug switch causes contents
of the initial date window to be incremented very frequently, this
allows some testing of the program. The -alarmscan switch prints
debugging information about the alarm system on standard output. The
argument following the -format is a date format used to display dates
in the top level window (see below, the Format resource). Changing
this to include a time format will make xcal display a clock in your
top level window. The argument following the -stripfmt argument is a
date format used to display month names and years in the monthly
calendar strip. (see the resource StripFmt). Similarly, the -editfmt
argument is the format for dates used in an edit window (see the
Editfmt resource). The -clocktick argument is used to set the clock
update time of the main date window, should a time be displayed as
well as the date. See the Clocktick resource.
- 3 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
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.
OtherUser the name of the user whose calendar files will be
inspected. This is usually set by the -u option.
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.
Default: False.
Format This is a format string used to create the contents
of the top command button and the memo box. The
format is aimed at the system routine: strftime. I
have chosen to use the system routine because it
makes it easier for non-english language sites to
generate their own formats. However, this means
that the names used for months and days may not be
compatible with the ones set in the resources
below. Any characters in the format string are
passed to the output unchanged unless they specify
a format. Format letters are preceded by a `%'
character and can be found in the documentation for
strftime on your system. The SunOS 4.1.3 routine
supports:
%% same as %
%a day of week using abbreviated name
%A day of week using full weekday names
%b (%h) month, using locale's abbreviated names
%B month, using locale's full names
%c date and time as %x %X
%C date and time, in local long-format date and
time representation
%d day of month (01-31)
%D date as %m/%d/%y
%e day of month (1-31; single digits are preceded by a blank)
%H hour (00-23)
%I hour (00-12)
%j day number of year (001-366)
%k hour (0-23; single digits are preceded by a blank)
- 4 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
%l hour (1-12; single digits are preceded by a blank)
%m month number (01-12)
%M minute (00-59)
%n same as \n
%p local equivalent of AM or PM
%r time as %I:%M:%S %p
%R time as %H:%M
%S seconds (00-59)
%t same as \t
%U week number of year (01-52), Sunday is the first day of the week
%W week number of year (01-52), Monday is the first day of the week
%x date, using locale's date format
%X time, using locale's time format
%y year within century (00-99)
%Y year, including century (fore example, 1988)
%Z time zone abbreviation
The default is "%A %d %B %Y", printing the day, the
date, the month and the full year. I prefer to use
"%A %e %B %Y", but this does not seem to be
portable to different systems. The format string
is scanned to determine the update frequency that
is needed to maintain a correct date image. The
default needs updating every 24 hours, if you
insert an AM/PM format then the strip will be
updated every 12 hours. Adding an hour
specification will cause an update every hour and
specifying minutes or seconds will cause
appropriate behaviour.
ClockTick If you specify a second hand in the main date
string and only want it updated every 30 seconds
(say) then setting the ClockTick resource to 30
will force an update for that period. Default: 0
(derived from the Format string).
StripFmt is used to format the date line at the top of each
strip. This uses an internal version of the
strftime routine that only supports format
characters relating to months, years and days. The
supported format characters are: %A, %a, %B, %b,
%h, %D, %d, %e, %m, %n, %t, %x, %y and %%.
Long/short day and month names are taken from the
resources. Default: "%B %y".
EditFmt provides the format string for any edit window.
This uses the same code as StripFmt. Default: "%A
%d %B %Y". Again, I prefer to use "%A %e %B %Y".
MarkToday If True then highlight today. Default True.
- 5 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
TodayBackground the background colour when marking, default Black.
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 information is
given. If False, help buttons disappear returning
screen real-estate to the user. You should resist
setting this to False in the default resources
file. Default: True.
HelpFromFile The Xcal program will usually have help strings
compiled into it. These are in English and it may
be desirable to use help data in other languages.
If this resource is true, it forces Xcal to look in
a data file for the help strings. Default: False.
HelpFile gives the name of the file used as a database for
the help system, accessed when HelpFromFile is
True. Default: /usr/lib/X11/XCal.help.
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.
- 6 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
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.
ExecAlarms if the alarm system is active, whether or not to
invoke timed-execution commands. 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 t 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
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.
- 7 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
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 printf 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 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.
MaxStripHeight controls the maximum height of a strip. A scroll
bar will be added into the date part of the scrip
of the contents are larger than this number. If
unset, this defaults to the height of the screen.
Default: unset.
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).
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
- 8 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
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.
Private Contains the string `Private calendar entry' and is
used when the -u option is in force. It is
displayed when a calendar file entry is unreadable
by the caller.
Alarmleft Contains the string `%d minutes before'.
Alarmnow Contains the string `Time is now...'.
Already Contains the string `Already editing %d %B %Y' I
prefer to use `Already editing %e %B %Y'.
AlreadyWeekly Contains the string `Already editing %A'.
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
mainHelp Optional main help 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
viewport viewport permitting scrolling of the
data data widget
"DDD" form containing day button (lots of these)
these are named for the short days of the week
label label containing dd DDD, day of the month
and day of the week
- 9 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
info command containing the file data
Note that each day button is named for the day of the week, so that
weekends can be highlighted specially using the standard resources.
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
viewport viewport permitting scrolling of the
data data widget
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
save the save button
help the help button
date the date string
text the text widget for editing
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
- 10 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
The Memo Window is:
memo the popup shell
memoPanel the panel inside the shell
title Top line form widget
quit the exit button
edit edit button - edit today's info
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
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
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
FILES
$HOME/Calendar/*
- 11 - Formatted: November 8, 2025
xcal(1) X Version 11 R5 xcal(1)
September 1990
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.
SEE ALSO
xrdb(1), xcalev(1), xcalpr(1), xcal_cal(1)
BUGS
There should be some way of removing several edit windows from the
screen at once. 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,1993 by Peter Collinson, Hillside Systems All
rights reserved.
This product includes software developed by the University of
California, Berkeley and its contributors.
At one time, 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. Thanks to Miles O'Neal from Pencom for revising
the help code to be a little more `X', although this was later revised
to use files. There are a number of other people who have sent in
revisions, some I have used, some I have not. Thanks anyway.
- 12 - Formatted: November 8, 2025
