| xcal(1) | General Commands Manual | xcal(1) |
xcal - calendar with alarms and a notebook for X11
xcal [ -debug ][ -alarmscan ][ -format fmt ][ -editformat fmt ][ -stripformat fmt ][ -clocktick tick ][ -u username ]
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.
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 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 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.
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.
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:
%% 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) %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.
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 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
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
$HOME/Calendar/∗
The standard resource database can be found in /usr/lib/X11/app-defaults/Xcal. Assuming that this is where the system admin installed it.
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.
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.
| September 1990 | X Version 11 R5 |