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 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). 

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.  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 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. 

XCalToplevel application
formForm containing two buttons
todayMemo Command button
dateStrip Command button

Then we have various popups.  The Calendar Strip is:

"Mon Year"the popup shell
Monthpanel containing the strip
headerlabel containing month and year
actionform containing < quit > buttons
backcommand containing < - last month
quitcommand containing exit button
nextcommand containing > - next month
helpcommand generating help
"dd DDD"form containing day button (lots of these)
labellabel containing dd DDD, day of the month
and day of the week
infocommand containing the file data

The Edit Window is:

editthe popup shell
panelthe panel inside the shell
titlethe form containing the first line
quitthe exit button

The Help Window is:

helpthe popup shell
helpPanelthe panel inside the shell
helpFormthe form containing the title line
quitthe exit button
helpTextthe text widget showing the information

The Alarm Window is:

alarmthe popup shell
alarmPanelthe panel inside the shell
alarmFormform for top line
alarmQuitthe exit button
alarmHoldthe hold button
alarmTitlethe title on the alarm window
alarmTextthe text widget for displaying

The Memo Window is:

memothe popup shell
memoPanelthe panel inside the shell
titleTop line form widget
quitthe exit button
helpthe help button
datedisplay today’s date
displaytext from today’s date file
memoMiddleMiddle line form widget
saveSave button
memoTitletext title of middle line
memoTextText widget showing memo file

The Middle button date selection popup is:

questionthe popup shell
newdatethe dialog widget
okthe OK button
cancelthe cancel button

The Right button exit selection popup is:

questionthe popup shell
exitthe dialog widget
yesthe yes button
nothe no button

An error is shown when a multiple attempts are made to edit the same day file. 

questionthe popup shell
noeditthe dialog widget
okthe OK button

A dialog box is popped up when an attempt is made to exit from an editing box without saving the file. 

checkthe dialog widget
yesthe yes button
nothe 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 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. 

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 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. 

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 data 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 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 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. 

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 names of the days, these are currently set to a three character 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 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.

Amiga Unix  —  Last change: September 1990