ical(1)ical(1)NAMEical - An X based Calendar Program
SYNOPSIS
Ical provides an X interface for maintaining a calendar. A calendar is
basically just a set of items. An item is either an appointment, or a
notice. An appointment starts at a particular time of the day, and fin‐
ishes at a particular time of the day. A notice does not have any
starting or ending time. Notices are useful for marking certain days as
special. For example, a calendar may contain a notice for April 15th
indicating that taxes are due. When the documentation below refers to
an item, it applies both to notices and appointments. The main fea‐
tures of ical are:
* Items can be created and edited easily.
* Items can be cut, copied and pasted.
* Items can be made to repeat in various ways.
* Ical will generate alarms for upcoming appointments.
* Users can view many calendars at a time.
* Calendars can be shared by many users.
* Related items can be grouped in their own calendar.
INVOCATION
You can specify various command line options to control ical.
General Options
The following options can be used even when you are not logged in on an
X display.
-calendar file-name
The calendar is read from the specified file. See the
description of calendar files for more information.
-date date
Set the starting date for item listings or window display
to the specified date. For example: ical-date
1/aug/1997
-list Print a listing of the starting date's items and exit
immediately. See the description of listing items for
details on the actual items printed by this option. The
starting date is usually today, but may be changed with
the -date option.
-show +days
Print a listing for items in the range [starting
date...(starting date + days - 1)] and exit immediately.
See the description of listing items for details on the
actual items printed by this option. The starting date
is usually today, but may be changed with the -date
option.
-print 1|2|4|8|10|month
Generate postscript on standard output for range of days
and exit. The starting date is usually today, but may be
changed with the -date option.
X Options
The following options are valid only if you are logged in on an X dis‐
play.
-iconic
Start up with the main window iconified.
-iconposition x,y
Icon is placed at the specified position.
-popup
Popup a window containing a listing of the starting
date's items and exit as soon as the window is dismissed.
See the description of listing items for details on the
actual items printed by this option. The starting date
is usually today, but may be changed with the -date
option.
-geometry geometry
Use geometry as the geometry for the main window.
-fg color
Use color as the foreground for all windows.
-bg color
Use color as the background for all windows.
-display display
Run ical on the specified X display.
WINDOWS
The main calendar window displays the appointments and notices for a
particular date.
Date Selector
The top left portion of the window contains a date selec‐
tor. You can click on the various arrows to change the
month or the year. The day of the month can be selected
by clicking on the appropriate day in the month display.
The date selector contains various other buttons for con‐
venient date selection.
Notice Window
The bottom left portion of the window contains the
notices for the selected date. A scroll bar is provided
if all of the notices for the selected date do not fit
into the notice window.
Appointment Window
The right portion of the window contains the appointments
for the selected day. You can scroll this region by using
the scroll bar, or by dragging with the middle mouse but‐
ton in the background.
Menubar
A menubar runs along the top of the calendar window. The
File menu allows you to create and destroy application
windows.
Status Line
The bottom portion of the window contains a status line.
This status line indicates the calendar from which the
selected item comes and whether or not the selected item
repeats.
CALENDAR FILES
A calendar is stored in a calendar file. The default calendar file is
named .calendar and is kept in the user's home directory. If the CALEN‐
DAR environment variable is set, its value is used as the name of the
calendar file. The CALENDAR environment variable and the default can
both be overridden by specifying a file name on the command line as
follows --ical-calendar file-name. Ical periodically saves any modi‐
fications made to a calendar to the corresponding calendar file. It
also periodically incorporates changes made to a shared calendar file
by other instances of ical. You can explicitly trigger these periodic
saves and reads by using the File menu.
Including and Sharing Calendars
You can include other calendars into your private calendar. This facil‐
ity is mainly useful for allowing a group of people to share a common
set of items. For example, members of a particular group might have a
calendar that contains the birthdays for each member of the group. This
calendar can be included in each group member's private calendar. Use
the File menu to include and exclude shared calendars. Use the Move
Item To ... entry from the Item menu to move items between calendars.
Use the From Calendar ... entry in the List menu to list all items a
particular calendar.
ITEMS
Notices
You can enter notices by clicking in the background in the bottom-left
portion of the main calendar window. This click will create a new
notice for the selected date. You can enter text into the notice by
typing into it while it is selected (selected notices are highlighted
by being displayed in different colors). A notice can be selected for
editing by clicking with left button.
Appointments
You can enter appointments by left-clicking in the background in the
right portion of the main calendar window. This click will create a new
appointment for the selected date. The start time for this appointment
is determined by the click location. You can move the appointment by
dragging it with the middle mouse button held down. The appointment can
be resized by dragging with the right mouse button held down.
Appointment text can be edited by typing into the appointment window
while it is selected. If the appointment text you are typing in does
not fit into the appointment area, then it will overflow out of the
appointment area, but will be editable normally. If you do not like
overflowing text, you should turn off the Allow Text Overflow option in
the Options menu . With this option turned off, if the current text
completely fills the area allocated to the appointment, then any
attempts to add to the appointment text will be ignored until the
appointment is enlarged with the right mouse button. Likewise, the
right mouse button will refuse to shrink an appointment window if the
appointment text completely fills the appointment window.
Alarms
Ical generates alarms for appointments. By default, the first alarm is
generated fifteen minutes before the appointment is supposed to start
and successive alarms are generated every five minutes until the
appointment actually starts. You can change this default behavior by
selecting the Default Alarms entry from the Options menu. You can also
change the timings of these alarms on an appointment-by-appointment
basis by double-clicking on the appointment, or by selecting the
appointment and then chosing the Properties entry in the Item menu.
Repeating Items
Items can be made to repeat in various ways. Item repetition can be
controlled by using the entries in the Repeat menu. These entries make
the item repeat in certain frequently used ways. For example, the
Monthly entry makes the selected item repeat once per month and the
Weekly entry makes the selected item repeat once per week. The Edit
Monthly... and Edit Weekly... entries can be used to make items that
repeat in more complex ways: for example, an item that occurs on the
last Friday of each month, or an item that occurs on Monday, Wednesday,
and Friday every week.
In addition to making an item repeat in one of the pre-defined ways,
you can also restrict an item's starting and finishing date by select‐
ing the Set Range... entry from the Repeat menu.
Normally, a modification to a repeating item applies to all occurrences
of that item. A single occurrence of a repeating item can be modified
by selecting the occurrence and then choosing the Make Unique entry
from the Repeat menu. The selected occurrence can now be modified
independently of the repeating item.
Todo Items
Items can be marked as todo items by selecting the Todo entry in the
Item menu. A todo item is automatically moved forward to today's date
every day until the item is deleted or marked as done. An item can be
marked as done by clicking in the little check-box right next to the
displayed item.
Highlighting
By default, if any item occurs on a date, then the date is highlighted
in the date selector located in the top-left corner of the calendar
window. You can use the Highlight entries in the Item menu to control
this highlighting behavior on an item-by-item basis.
KEY BINDINGS
This section is currently incomplete.
EDITING
Dragging with the left mouse button in a selected appointment or notice
sets the X selection. The Edit menu provides commands for dealing with
the X selection.
Ical also has a clipboard that can store a single item. The Copy entry
in the Edit menu copies the selected item into the clipboard. The Cut
entry does the same, but it also deletes the item from the calendar. If
the selected item repeats, then the Cut command allows the user to
delete all occurrences of the item, or just the selected occurrence.
However, if the selected item does not belong to you, then Cut just
hides the item from you. Other people will still see the item. An
item in the clipboard can be inserted into the current day by selecting
Paste entry. The newly pasted item loses all repetition information,
and occurs just on the day in which it was pasted.
LISTING ITEMS
You can generate listings of imminent items by selecting one of the
listing options in the List menu. You can also use the command line
options -list, -show, or -popup to generate item listings. The command
line options are most useful in .login files.
By default an item is included in a listing for a particular date if it
occurs either on that date, or on the very next day. You can control
this feature of item listings with the List item entry in the Item
menu.
PRINTING
Calendar contents can be printed by selecting the Print option from the
File menu.
CUSTOMIZATION
Some of ical's behavior can be customized via the Options menu. Other
aspects of ical's behavior can be controlled via X Resources.
X Resources
Behavior
The following X resources can be used to control various aspects of
ical's behavior.
Ical.pollSeconds
Shared calendars are checked for changes made by other
people once every pollSeconds seconds. The default value
is 120. If ical appears sluggish, or if it is using too
much CPU time, increase this value.
Ical.saveSeconds
Calendar files are saved once every saveSeconds seconds.
The default value is 30. If ical appears sluggish, or if
it is using too much CPU time, increase this value.
Dimensions
The following X resources can be used to control various dimensions of
ical's appearance.
Ical.itemSelectWidth
The border width of selected items is set to the value of
this option to display the selected status of the item to
to the user. On color displays, the default value of
this option is 1 because on color displays selection is
indicated by changing the color of the selected item. On
monochrome displays, the default value of itemSelectWidth
is 4.
Ical.Dayview.geometry
X geometry specification for main calendar window. Usu‐
ally, you will just specify the window position here.
The size of the window is easier to control via the
Options menu.
Ical.Reminder.geometry
X geometry specification for alarms. Usually, you will
just specify the window position here. The window size
will be calculated automatically.
Ical.Listing.geometry
X geometry specification for item listings. Usually, you
will just specify the window position here. The window
size will be calculated automatically.
Colors
The following X resources can be used to customize ical's use of col‐
ors. If ical windows show up with illegible colors (not enough dis‐
tinction between background and foreground), it may be because your X
resources contain definitions for *foreground or *background that con‐
flict with ical colors. In general, it is a bad idea to define *fore‐
ground and *background in your resources because it will break a number
of programs. You will be better off defining resources on an applica‐
tion by application basis.
Ical*Foreground/Ical*Background
Foreground and background colors for most of ical's win‐
dows.
Ical*disabledForeground
Foreground color assigned to disabled buttons and menu
entries.
Ical.itemFg/Ical.itemBg
Foreground and background colors for unselected items.
The default foreground is black and the default back‐
ground is gray.
Ical.itemSelectFg/Ical.itemSelectBg
Foreground and background colors for selected items. The
default foreground is black and the default background is
SlateBlue1.
Ical.itemOverflowColor/Ical.itemOverflowStipple
Background color and stippling used for appointment text
that overflows out of the appointment area. On color
displays, the default overflow background is SlateBlue3
and no stippling is done (specified by an empty stipple
option). On monochrome displays, the default overflow
background is black, and the default overflow stippling
is gray50.
Ical.apptLineColor
The color for the background lines and times displayed in
the appointment window.
Ical.weekdayColor
The color used to display days of the week. The default
is black.
Ical.weekendColor
The color used to display weekends. The default is red.
Ical.interestColor
The color used to highlight interesting dates. The
default is blue.
Ical.weekendInterestColor
The color used to highlight interesting dates on weekends
and holidays. The default is purple.
Fonts
The following resources can be used to customize ical's use of fonts.
Ical.fontFamily
Preferred font family. Fonts for various purposes are
obtained from this family unless overridden with one of
the specifications below. The default font family is
times. Some other font families you can specify here are
charter, new century schoolbook, and helvetica. My per‐
sonal favorite is new century schoolbook.
Ical.fixedFontFamily
Preferred font family for fixed-width fonts. Fixed-width
fonts for various purposes are obtained from this family
unless overridden with one of the specifications below.
The default font family is courier. Some other font fam‐
ilies you can specify here are fixed and terminal.
Ical.fontSize
Font sizes used for ical. Use the value small to use
small font sizes everywhere. Any other value for this
option defaults to the normal fonts.
Ical*itemFont
Font used to display item contents.
Ical.weekdayFont
Font used for displaying days of the week.
Ical.weekendFont
Font used for displaying weekends.
Ical.interestFont
Font used to highlight interesting dates.
Ical.weekendInterestFont
Font used to highlight interesting dates on weekends and
holidays.
Ical.smallHeadingFont
Font used for small headings.
Ical.largeHeadingFont
Font used for large headings.
Ical*<class>*font:
Font used for windows of a certain class. Possible val‐
ues for <class> are Dialog, Button, Label, Menubutton,
Menu, Listbox, and Reminder.
Tcl Code
Users can also customize ical by writing tcl code and storing it in the
file ~/.tk/ical/user.tcl. The code stored in this file is executed
when ical starts up.
Ical also looks for site-specific customizations at startup. These
customizations can be placed in the file site.tcl in either the ical
library directory, or its parent directory. (By default, ical looks
for site.tcl in /usr/local/lib/ical/v[version]/, and
/usr/local/lib/ical/, but these directories may be located elsewhere on
your system.) The site specific files will be loaded in before any
user specific customization file is loaded in.
See the "Tcl Interface to Ical" document available via the Ical help
menu.
Ical can run even when X is not available, therefore customization
files should be written so that they will function even when Tk com‐
mands are not available.
MENUS
File Menu
Save Save any modifications to the appropriate calendar files.
Re-Read
Read any changes made to a shared calendar by another
user or another instance of ical. Ical will automati‐
cally invoke this function periodically. It is provided
as a menu entry only so for people who do not want to
wait for ical's periodic checks.
Print Print calendar contents. The user has the option of sav‐
ing the print-out to a file, pre viewing the print-out by
specifying a PostScript displaying program, or sending
the print-out directly to a PostScript printer by speci‐
fying a printing command.
Include Calendar
Select a calendar to include into your private calendar.
Included calendars are normally used to share calendars
between different users.
Remove Include
Remove a previously included calendar from your private
calendar.
New Window
Open a new calendar window. This new window can be used
to view the items for a different date than the original
window.
Close Window
Close the selected window.
Exit Save any changes and kill ical.
Edit Menu
Cut Item
Delete the currently selected item and store it in the
clipboard.
Copy Item
Copy selected item to the clipboard.
Paste Item
Paste item from clipboard into calendar.
Delete Text
Delete the currently selected text from the selected
item.
Insert Text
Insert the current X selection into the selected item.
Import Text
Import the current X selection as a new item into the
calendar. The date and time of this new item are parsed
from the X selection if possible.
Item Menu
Todo Toggle the item between being a todo item and not being a
todo item.
Always Highlight
The item always causes the corresponding date to be high‐
lighted. This is the default behavior.
Never Highlight
The item never causes the corresponding date to be high‐
lighted.
Highlight Future
The item causes the corresponding date to be highlighted
if and only if the date is not in the past.
Holiday
The item causes the corresponding date to be highlighted
as a holiday.
Change Alarms
This item pops up a dialog box that allows you to edit
the alarm times for an appointment.
Note that this will only change the alarm times for the selected
appointments. You can make this change for all appointments
that do not have special alarm times by using the Default Alarms
entry in the Options menu.
Early Warning
By default an item is included in a listing for a partic‐
ular date if it occurs either on that date, or on the
very next day. Sometimes, you may want to include an
item in listings for earlier dates. For example, if you
have an item reminding you of a birthday on March 17th,
you might want this item to be included in all listings
from March 7th to March 17th so that you will have enough
time to go out and buy a present. You can achieve this
effect by selecting this menu entry and then entering "10
days" into the resulting dialog.
Note that this will only change the listing behavior for the
selected item. You can make this change for all items you cre‐
ate from now on by using the Default Listings entry in the
Options menu.
Properties ...
Edit various item properties, including the calendar to
which the item belongs, highlighting information, early
warning options, alarm times, and starting and ending
times for appointments. You can also double-click on an
item to pop up the property editing dialog.
Search Forward
Search forward looking for an item that contains a user
specified string.
Search Backward
Search backward looking for an item that contains a user
specified string.
Repeat Menu
Don't Repeat
Make the selected item a non-repeating item.
Daily Make the item repeat every day.
Weekly
Make the item repeat once every week.
Monthly
Make the item repeat once every month.
Annually
Make the item repeat once every year.
Edit Weekly
Make the item repeat on a weekly basis in a complicated
fashion. For example, on Tuesday and Thursday every
week.
Edit Monthly
Make the item repeat on a monthly basis in a complicated
fashion. For example, on the third Sunday in June, or
the last working day of each month.
Set Range...
Restrict the range for a repeating item.
Last Occurrence
Make the current occurrence the last occurrence of the
selected item. I.e., remove any occurrences after the
current date.
Make Unique
If you want to modify just a single occurrence of a
repeating item, select the item occurrence you want to
modify and then activate this menu entry. Now all modi‐
fications to this item occurrence will only affect this
particular occurrence.
List Menu
One Day
List the item occurrences for one day.
Seven Days
List the item occurrences for the next seven days.
Ten Days
List the item occurrences for the next ten days.
Thirty Days
List the item occurrences for the next thirty days.
Week List the item occurrences for this week.
Month List the item occurrences for this month.
Year List the item occurrences for this year.
From Calendar ...
List all item occurrences from a selected calendar.
Option Menu
Appointment Range
Controls the subset of a day displayed by default in the
appointment listing. The factory settings display 8:00am
to 6:00pm.
Notice Window Height
This entry can be used to change the height of the notice
window.
Item Width
This entry can be used to change the width of displayed
appointments and notices.
Allow Text Overflow
If this option is selected, then you can type in any
amount of text into an appointment. The part of the text
that does not fit into the appointment will be allowed to
overflow out of the appointment. If you do not like text
overflowing out of an appointment, then you should turn
off this option.
Display Am/Pm
If this option is selected, time will be printed in
twelve hour mode with am or pm indicators. Otherwise,
time will be printed in twenty-four hour mode.
Start Week on Monday
If this option is selected, month displays will start
each week off on a Monday. Otherwise, each week will
start on a Sunday.
Default Alarms
Use this menu entry to change the time intervals at which
alarms go off. The factory settings cause alarms to be
triggered fifteen minutes before each appointment, and
then once every five minutes until the appointment actu‐
ally starts. This menu entry changes the default alarm
behavior for all appointments. You can override this
default behavior on an appointment-by-appointment basis
by selecting an appointment and then selecting the Change
Alarms entry in the item menu.
Default Listings
This menu can be used to select the default listing
behavior for newly created items. If the On Occurrence
entry is selected, then a newly created item will only be
shown in the listing of the day on which the item occurs.
If the A Day Early entry is selected, then a new item
will be shown in listings starting a day before the item
occurrence. Similarly, the other menu entries can be
selected to make new items show up in listings a number
of days before their actual occurrence. This menu
selects the default behavior for new items. Individual
item behavior can be controlled by similar entries in the
Item menu.
Help Menu
About Ical
Displays ical version number and author information.
User Guide
Displays this document.
AUTHOR
Sanjay Ghemawat (sanjay@pa.dec.com) http://www.research.digi‐
tal.com/SRC/personal/Sanjay_Ghemawat/home.html
COPYRIGHT
Copyright (c) 1993 by Sanjay Ghemawat. Permission is granted to make
and distribute verbatim copies of this manual provided the copyright
notice and this permission notice are preserved on all copies.
SEE ALSO
Ical http://www.research.digital.com/SRC/personal/Sanjay_Ghe‐
mawat/ical/home.html
ical(1)
