2.8. Details of File Commands

The scenarios in this section cover full details of file-related commands, some of which have been introduced in preceding sections. There are two file command menus to be covered, one in the regular-user Calendar Tool and the other in the Calendar Tool Administration program. Regular-user file commands are covered in Sections 2.8.1 through 2.8.7. Administrator file commands are covered in 2.8.8 through 2.8.11. The concluding Sections 2.8.12 and 2.8.13, cover general topics relevant to both regular-user and administrative files.

2.8.1. Files Used by the Calendar Tool

There are two types of files used by the regular-user Calendar Tool -- calendar files and settings files. Calendar files contain the following information:

All of this information is stored in a single calendar file for each calendar created by the user. In this way, a single file encapsulates scheduled items and all other calendar-specific information that the user has defined for that calendar. "For that calendar" means that each calendar has its own setting information, but no settings for other calendars that may be open at the same time. In particular, the calendar-specific information for the state of open windows means the windows open for a particular calendar, not for any other open calendars. The calendar-specific nature of the different types of information is explained further in the sections cited parenthetically in the immediately preceding list.

The other type of Calendar Tool file contains settings that exist independent from any individual calendar. These settings are used as the defaults when a new calendar is created and to record setting values that apply to a whole Calendar Tool session, not just an individual calendar. The contents of a settings file are the following:

The calendar-specific settings in a settings file are a separate version the same information that is contained in each calendar. Their existence in the settings file is for permanently recording settings used in new calendars, and to allow settings to be conveniently copied among different calendars. The session-wide settings define information that applies across all calendars during a Calendar Tool execution session. Section 2.8.5. describes how settings files are saved and loaded.

Calendar and settings files may be stored in any file directory accessible to the user. However, there is a specific directory called the Calendar Tool user directory used for the following purposes:

Whenever the Calendar Tool is invoked, it opens a single settings file to initialize the session-wide settings for the ensuing session. The name of this file is "Settings", and it must be located in the Calendar Tool user directory at the time the `New' command is executed. The user directory also has a default location, determined at installation time as described in Section .

The user can save additional copies of setting files, which are useful for copying settings from one calendar to another. However, the user cannot change the name or location of the default file named "Settings" that the Calendar Tool opens initially at start up. The user can change the location of her own Calendar Tool user directory, as an option. Doing so is described in Section 2.7.6.

There are no naming requirements for calendar or settings files, other than the requirement for the fixed name and location of the "Settings" file. In particular, there are no requirements for filename extensions. If the user chooses to give calendar files an extension, or if a particular operating environment recommends or requires that application files have known extensions, then the recommended extension for calendar and settings files is ".cal". If this extension conflicts with that used by some other application, then the installation process can assign a particular extension to be used in a particular operating environment.

The internal data format of calendar and settings files is not specified in these requirements, and therefore left to the implementors. In particular, there are no requirements that these files be editable as plain text or other external data format understandable to application programs other than the Calendar Tool. It is required that the Calendar Tool be able to identify calendar and settings file as such, so they can be distinguished from each other and from other types of files. The specific means to accomplish this identification is left to the implementors.

2.8.2. New and Open

When the user executes the `New' command in the `File' menu, the system responds by creating a new calendar and displaying its initial view. The default initial view is at the month level, with today's date highlighted. The user can change the default initial view for new calendars with the view option described in Section 2.7.6.

The name of a new calendar is "unnamed", until the user saves it with a different name. Each successive application of New, with no intervening save, creates a calendar named "unnamed[N]", for N = 2 to the number of unnamed calendars.

A new calendar has no scheduled items except for system-defined events. The user can change the visibility of system-defined events with the option setting described in Section 2.7.4.3. The setting effects only whether system-defined events are visible in calendar displays, not their physical presence in the calendar. Section describes exactly what the system-defined events are.

The calendar-specific settings for each new calendar are those defined in the Settings file in the Calendar Tool user directory. If there is no Settings file, settings have the built-in default values defined when the Calendar Tool is installed. Table 15 shows the built-in default settings for all new calendars, in the absence of a Settings file.



Type of setting Initial value Where illustrated
categories only holidays defined Figure 7
custom lists none defined Figures 37 and 38
filter settings and
custom filters
all items shown,
no custom filters defined
Figures 51 and 52
options various figures in Section 2.7 showing initial values in options-setting tabs
page setup and
print options
platform-dependent defaults Figures 302 and 303
windowing mode per-level Figure 71
state of open windows monthly view shown, Figure 1

Table 15: Built-in default settings for new calendars, absent a Settings file.



A new calendar becomes the current calendar, and the system performs all of the actions associated with making a calendar current. These actions are described in Section 2.3.6.4. Before the user saves a new calendar, it has no associated file. This affects the behavior of file-save operations, as discussed in Section 2.8.4.

When the user selects the `Open' command in the `File menu, the system displays the dialog shown in Figure 286.


Figure 286: File open dialog.



The dialog shown in the figure reflects the state of the .CalendarTool directory after the user has saved two calendar files -- DepartmentCalendar and PersonalCalendar. The `Directory' pulldown lists the components in the file path to the current working directory. As explained in Section 2.8.1, the default directory path for the file-open dialog is the Calendar Tool user directory for the current user.

The user may type the name of the file to open or select it from the scrollable list of file names. When the user selects the pulldown arrow in the `Directory' field, the system displays the directory path, as shown in Figure 287.


Figure 287: File open dialog with directory path displayed.



The user may select from the directory list to navigate to another directory, whereupon the system displays its files and subdirectories in the scrollable list. The names of readable calendar files and readable subdirectories are shown in regular type in the file list. The names of all other files are shown in grey type, indicating they are disabled for selection. This means the user cannot open an unreadable calendar file, an unreadable directory, or any type of non-calendar file. The user can load a settings file, but this is done with the `Load Settings' command, described in Section 2.8.5

The user may navigate into a subdirectory by selecting its name in the list and pressing `OK'. The `OK' button is enabled when there are one or more subdirectories in the scrollable list. When the user presses `OK' for a selected directory, the system displays its contents in the scrollable list.

When the user selects a specific file in the list, the system enters its name in the `File' field and enables the `OK' button, if it was not already. When the user presses `OK', the system opens the selected file if it is not already open. Once opened, the system displays the file's initial view, per its most recently saved settings, including in particular the option setting for its initial view window(s) (see Section 2.7.4.3 ). The opened calendar becomes the current calendar, and the system performs all of the actions associated with making a calendar current, as described in Section 2.3.6.4. If the selected file is already open, pressing `OK' in the open dialog has the same effect as selecting the calendar's name in the `Calendars' list, described in Section 2.3.6.4. Double clicking on a calendar file name or directory name is a shortcut for selecting that name and pressing `OK'.

The user may type the name of a calendar file or directory in the `File' field. As the user types, the scrollable list is scrolled to the alphabetic position in the list nearest but not after the place where the thus-far typed name appears or would appear in the list. If the user types the complete name of an existing calendar file or readable directory, the effect is the same as when the user selects the name by clicking in the list. If the user types the name of a non-existent file, the user may press `OK', whereupon the system creates a new file of the entered name. This is effectively a short cut for executing `File->New' followed immediately by `File-Save'.

Since unreadable files, unreadable directories, and non-calendar files are disabled in the file-open dialog list, the user cannot select one of these. However, the user may type the name of an unreadable file, unreadable directory, or non-calendar file in the `File' field. If the user does so, the system disables the `OK' button, since these files or directories cannot be opened. If the user continues typing so that the name is not an unreadable calendar file, unreadable directory, or an existing non- calendar file, the system re-enables the `OK' button.

When a calendar is opened from a saved file, the name of the calendar is synonymous with its root filename. The root filename is the name of the file, less any leading file path and less any filename extension. For example, the name of the calendar stored in the file "/users/home/dcollins/.CalendarTool/DepartmentCalendar.cal" is "DepartmentCalendar". The Calendar Tool provides no command to change the name of a calendar independent from its filename. In particular, the only way the user can name an unnamed calendar is to save it to a file.

A new or just-opened calendar has today's date highlighted with a darkened border, as illustrated in Section 2.3.1. No date is selected as a viewing target, in the sense of selection defined in Section .

If an opened calendar is associated with one host in the host connection table and the `Auto-connect on file open' option is on, then the system initiates the host connection. The connect operation proceeds as described in Section 2.6.6.1, as if the user had pressed the `Connect' button in the host connection table. The auto-connect option is described in Section 2.7.5. If an opened auto-connect calendar is associated with more than one host, the system displays the dialog shown in Figure 288.


Figure 288: Select from multiple associated hosts.



The name string is the name of calendar just opened. The dialog informs the user that since the calendar is associated with more than one host, the user must run the `Admin->Connect' command in order to select the host to connect to.

The `New' and `Open' commands are always enabled in the file menu. The following is a summary of the when the `OK' button is enabled in the file-open dialog:

  1. when the user has selected the name of a readable calendar file in the scrollable list

  2. when the user has selected the name of a readable directory in the scrollable list

  3. when the user has typed anything in the `File' field, except for the complete name of an unreadable calendar file or existing non-calendar file

As explained in Section 2.3.6 zero or more new or existing calendars can be open at any time the Calendar Tool is running. That section explains the way that the windows of multiply open calendars are managed and displayed.

Since `New' and `Open' are always enabled, the user may execute these commands at any time while the Calendar Tool is running. This means that the user can have an unbounded number of calendars open. If taken to an extreme, this could conceivably cause resource problems in some operating environments, as discussed in Section

2.8.3. Close and Close All

The `Close' and `Close All' commands are enabled in the `File Menu' if there is at least one open calendar, disabled otherwise. `Close' applies to the current calendar; `Close All' applies to all open calendars.

When the user selects the `Close' command, the system performs the following pre-close steps for the calendar to be closed, i.e., the current calendar:

  1. checks if the calendar has unsaved changes

  2. checks if there are any pending edits in dialogs associated with the calendar

  3. checks if the calendar is connected to a central host computer
Once these steps are completed satisfactorily, the system proceeds to perform the close operation. Details follow.

For the first pre-close step, the system checks if the current calendar has any unsaved changes. The precise definition of an unsaved change is given in Section 2.8.4. If there are one or more unsaved changes, the system displays the dialog shown in Figure 289.


Figure 289: Offer to save calendar before closing.



The name string is the name of the current calendar to be closed. If the user presses `Yes', the system proceeds as follows:

  1. If the calendar to be closed has not yet been saved to a file, the system displays the file save-as dialog shown in Figure 292. If the user confirms a legal save-as operation in that dialog, the system proceeds to the next pre-close step. If the user presses `Cancel' in the save-as dialog, the system returns to the offer-to save dialog, where the user may press `No' or `Cancel' (or `Yes' if she wants to return again to the save-as dialog).

  2. If the calendar to be closed has previously been saved to a file, the system performs the file save operation described in Section 2.8.4, and proceeds to the next pre-close step.
If the user presses `No' in the offer-to-save dialog, the system proceeds to the next pre-close step without saving the calendar, thereby losing any unsaved changes. If the user presses `Cancel' in the offer-to- save dialog, the system cancels the close operation entirely, without saving, without performing further pre-close steps, and leaving the calendar open and unchanged. The system also removes both the offer-to-save and file-close dialogs from the screen.

If the calendar to be closed has no unsaved changes, the system proceeds to the next pre-close step, without displaying the offer-to-save dialog. Calendars with no unsaved changes are those that have been saved prior to close, as well as other-user and group calendars, since the latter two types of calendar cannot be changed.

For the second pre-close step, the system checks if there are any pending edits in calendar-specific, non-modal editing dialogs for the calendar to be closed. Section defines which Calendar Tool dialogs are of this type. A pending edit is any unconfirmed or unapplied change the user has made in one or more of these dialogs. if there any such pending edits, the system displays the dialog shown in Figure 290.


Figure 290: Warning when there are unconfirmed or unapplied dialog edits.



If the user answers `Yes' in the pending-edits dialog, the system discards any pending edits, cancels all pending dialogs, and removes the dialogs from the screen. When the system responds to the `Yes' response or if the pending-edits dialog was not displayed, the system proceeds to the last pre-close step.

If the user answers `No' in the pending-edits dialog, the system cancels the close operation without performing the last pre-close step, leaves the calendar open, and leaves all pending edit dialogs open and unchanged. If the calendar had been saved as a result of the first pre-close step, it remains saved, i.e., the save operation is not undone.

For the third and final pre-close step, the system checks if the calendar being closed is currently connected to a central host computer (see Section 2.6.6.1 ). If so, the system displays the dialog shown in Figure 291.


Figure 291: Warning when closing calendar is connected to a central host.



If the user answers `Yes' in the connected-to-host dialog, the system disconnects the host and updates the host connection table accordingly, as described in Section 2.6.6.1. When the system responds to the `Yes' response, or if the connected- to-host dialog was not displayed, the system proceeds to complete the close.

If the user answers `No' in the connected-to-host dialog, the system cancels the close operation, leaving the calendar open and connected. If the calendar had been saved as a result of the first pre-close step, it remains saved, i.e., the save operation is not undone. If any pending-edit dialogs where canceled and closed as a result of the second pre-close step, the dialogs remain so.

When the pre-close steps have been completed without a cancellation, the system completes the close operation by closing the current calendar, removing its name from the Calendars list, and removing all windows associated with the calendar from the screen, including any remaining dialogs (those without pending edits). Section 2.3.6.4 describes details of the Calendars list, calendar-to-window association, and changing the current calendar. When the close operation has been completed or canceled, the system removes all close-related dialogs from the screen.

When the user selects `Close All' in the `File' menu, the system executes a close operation for all open calendars, in the same manner as described above for `Close'. The offer-to-save dialog is displayed in turn, as necessary, prior to closing each calendar. If the user presses `Cancel' in the offer-to-save dialog for any calendar, the system cancels the close operation for that calendar and all remaining open calendars. `Cancel' does not affect any already-closed calendars for which the user previously answered `Yes' or `No' in the offer-to-save dialog; these calendars remain closed. The pending-edits and connected-to-host dialogs are also displayed in turn, as necessary. Since there is no `Cancel' button in the pending-edits or connected-to-host dialogs, the 'Close All' operation proceeds with the next calendar to be closed, whatever the user's decision is in either of these warning dialogs. A calendar remains open if the user answers`No' in either the pending-edits or connected-to-host dialog.

When the system completes a `Close' or `Close All' for the last open calendar, it closes the `Find' dialog and `Goto Date' dialog, if either or both are open. As described in Section , these two dialogs can be open only when at least one calendar is open.

Closing the last open calendar does not automatically exit the Calendar Tool. As explained in Section 2.3.6.4, the Calendar Tool runs with zero or more calendar files open.

2.8.4. Save, Save As, and Save All

A new calendar is not associated with a file until it is saved for the first time. For new not-yet-saved calendars, the `Save' and `Save As' commands have exactly the same effect. When the user selects either of these commands for a not-yet-saved calendar, the system displays the dialog shown in Figure 292.


Figure 292: Initial save dialog for a not-yet-saved calendar.



This dialog shows the initial state of the .CalendarTool directory before the user has saved any files. The Settings file is shown in the scrollable list, since it is installed by default during the normal Calendar Tool installation process, described in Section . The system does not pre-enter "unnamed" in the `File' field, to discourage the user from naming a calendar "unnamed". The system does not however prevent a recalcitrant user from doing so.

As in the file-open dialog, the user may navigate to another directory by selecting from the `Directory' pulldown list and by selecting directory names in the scrollable list. To save to a file, the user types its name in the `File' field. The system enables the `OK' button when the user begins typing, and it remains enabled unless the user does one of the following:

The system disallows saving in any of these circumstances (only the first of which happens to be possible in Figure 292 ). If the user continues typing to change these circumstances, the system re-enables the `OK' button. The system does allow saving a calendar into an existing calendar file, which case is described shortly.

Figure 293 shows the user having entered the name "DepartmentCalendar" for saving.


Figure 293: Initial save dialog filled in.



When the user presses `OK', the system saves the entire contents of the calendar onto the named file. All scheduled items and all calendar- specific settings are saved. After completing the save, the system removes the save dialog from the screen. If the user enters the name of an existing calendar file and presses `OK', the system asks for overwrite confirmation, as described below.

When saving a new calendar onto a new file, it is not possible for the saved-to calendar to yet be connected to a central host computer, since to make such a connection the calendar must already have been open. Hence in this case of saving, no copying to a central host is ever performed. Such copying is performed when saving an existing connected calendar, as described shortly.

When the current calendar is already associated with a file, the `Save' and `Save As' commands differ. The `Save' command is enabled whenever the current calendar is associated with a file, and the calendar has unsaved changes. A calendar has unsaved changes when the user has performed one or more of the following actions since the file was opened or the last confirmed save operation, whichever has occurred most recently:

  1. confirmed any scheduling or category-changing command in the `Schedule' menu

  2. confirmed any change to custom lists

  3. confirmed any change to filter settings or custom filters

  4. executed any command in the view menu that changes the state of the display screen

  5. changed the windowing mode

  6. moved, iconified, or closed any window associated with the calendar

  7. applied any option changes

  8. confirmed any change to page setup or print settings

  9. loaded settings
If the user undoes any of these actions such that the state of the calendar returns to the same state as most recently saved, then the calendar no longer has unsaved changes. The "state" of the calendar is defined as the values of all scheduled items and calendar-specific settings. It is noteworthy that the definition of unsaved change includes any an all actions that change scheduled items or calendar-specific settings.

When the user selects the enabled `Save' command in the `File' menu, the system saves the scheduled items and settings for the current calendar on the file associated with the calendar. If the file is connected to a central host computer, the system also copies the calendar file to the central host, as explained in Section 2.6.6.1. All scheduled items and calendar-specific settings are copied to the host. If a calendar is associated with a central host but not connected to it, the save operation does perform the copy.

The `Save As' command is enabled in the `File' menu whenever the current calendar is not that of another user or group. `Save As' is enabled whether or not the current calendar has unsaved changes. When the user selects `Save As' for a new calendar, the system displays the dialog shown in Figure 292, and the system actions are those described for that figure.

When the user executes `Save As' for a calendar that is associated with a file, the system displays the dialog shown in Figure 294.


Figure 294: File save-as dialog.



This is the same dialog as shown in Figure 292, except the banner is "Save Calendar As" instead of "Save New Calendar". Figure 294 shows the state of the .CalendarTool directory after the user has saved two calendars. The names of writable unopened calendar files and readable subdirectories are shown in regular type in the list. The names of all other files are shown in grey type, indicating they are disabled for selection. This means that the user cannot save to an already open calendar file, an unwritable calendar file, or to any type of existing non-calendar file. The user can navigate through directories as explained above. The user can navigate to a readable but unwritable directory to see the files there. The existence of a writable calendar file in an unreadable or unwritable directory renders the file itself unwritable.

For a calendar that has an associated file, the purpose of `Save As' is to save a copy of the calendar on a file other than the one with which the calendar is already associated. To perform the save, the user types the name of the desired file in the `File' field, or selects the name of an existing calendar file in the scrollable list. The system enables the `OK' button when the user begins typing, and it remains enabled except under the circumstances enumerated above after Figure 292. When the user selects an enabled name in the list, the system enters the name in the `File' field.

To save the calendar onto a new or existing calendar file, the user presses `OK'. If the calendar to be saved is connected to a central host, the system displays warning shown in Figure 295 before completing the save-as operation.


Figure 295: Save-as operation will cause disconnect.



The name string is the name of the host to which the current (pre-save-as) calendar is connected. If the user presses `OK' in the disconnect warning dialog, the system disconnects the calendar under its current name and proceeds with the save-as. As the dialog message explains, the user must run the `Admin->Connect' command to re-connect the calendar under its new name. If the user presses `Cancel', the system cancels the save-as operation, leaving the current calendar connected and otherwise in its pre-save-as state.

To proceed with the save-as, the system checks if the file to be saved to exists. If it does not exist, the system completes the operation by saving a complete copy of the current calendar to the new file. If the saved calendar had unsaved changes, those changes are saved in the new saved-to file, but not in the original file. The original file remains in the same state as it was prior to `Save As' being executed. The saved calendar remains the current calendar, but with the new name instead of the old name. The system changes the name of the calendar in all of the contexts in which the original name appears. These contexts are described in Section 2.3.6.

When the user executes `Save As' to an existing calendar file, the system displays the warning dialog shown in Figure 296.


Figure 296: Confirm overwrite of an existing calendar file.



If the user presses `OK', the system proceeds with the save, fully overwriting the previous contents of the file. The states of the original and saved-to files are as described above for when `Save As' saves to a new file. The system also changes the name of the current calendar in the same way as for `Save As' to a new file. If the user presses `Cancel' the system does not perform the save, returning to the `Save As' dialog where the user can enter a different file name. In either case, the system removes the overwrite warning dialog.

The user may save a new or existing calendar to a file that is listed in the host connection table (in the `Calendar' column). In such a case, the system does not initiate a connection to the associated host as a result of the save. This is the case even if the option `Auto-connect on file open' is on. This option only applies to `File->Open', not to `Save As'. To connect to a host of a saved-to calendar, the user must execute the `Admin->Connect' command.

The user can type or select the calendar's current name in the save-as dialog, although this defeats the ostensible purpose of the `Save As' command. If the user does so and presses `OK', the system saves the calendar onto the file with which is currently associated, in the same manner as if the user had executed the `Save' command.

When the user selects `Save All' in the `File' menu, the system executes a `Save' for all calendars with unsaved changes. If any of the calendars is not yet saved to a file, and the user presses `Cancel' in the save-new-calendar dialog ( Figure 292 ), the system cancels the save for that calendar only.

The following is a summary of the enabled/disabled states of the save commands:

  1. `Save' is enabled when the current calendar is new and has no associated file, i.e., it has not yet been saved. Save is enabled unconditionally for a new calendar, even if the user has performed no changes to it since it was created. In this way, the user can save a completely empty new calendar.

  2. `Save' is also enabled when the current calendar has an associated file which has unsaved changes.

  3. `Save As' is enabled whenever at least one calendar is open, and the current calendar is not that of another user or group. `Save As' is enabled whether or not the current calendar has unsaved changes.
`Save' and `Save As' are disabled otherwise.

None of the save operations affects the state of pending edit dialogs. Unconfirmed or unapplied edits are not saved, and the states of all dialogs associated with a calendar are unchanged by a save of the calendar.

As described above, the system attempts to disallow saving to an unwritable calendar file. However, if the user changes the permissions of a calendar file externally, before or during Calendar Tool execution, it is possible for the user to execute a `Save' or `Save As' to an unwritable file. The circumstances where this can happen are described in Section 2.8.12. When the user does execute a `Save' or `Save As' to an unwritable file, the system responds with an appropriate error message, as described in Section . If this error is reported for a file during a `Save All' sequence, the system continues with the `Save All' after the user dismisses the error message.

2.8.5. Loading and Saving Settings

As outlined above, Calendar Tool settings are stored in the standard Settings file, as well as in other named files in which the user chooses to save them. The commands to save and load settings allow the user to bundle different settings to be used in different types of calendars. For example, the user can define a collection of work-related settings, save them in a settings file, and then load them for use in work-related calendars. Users or administrators can share such settings files with other users, so that a particular user community has a common collection of settings. Administrators can create useful settings files for inclusion when the Calendar Tool is installed, as described in Section

Since calendar files contain their own calendar-specific settings, the sharing functionality provided by settings files could be accomplished in part by sharing just calendar files themselves. However, settings files provide the advantage of being able to copy settings from one calendar file to another, without adding or deleting scheduled items in either calendar. Also, since calendar files do not contain session-wide settings, the only way to save and load these are through independent settings files.

The system loads the standard Settings file under the following circumstances:

  1. when the user starts up the Calendar Tool from the operating environment

  2. when the user invokes the `File->Load Settings' command and selects the Settings file to be loaded
When the system loads Settings at start up, it uses the session-wide component of the settings file to initialize global options, initialize the host connection table, and to determine which calendars to open at start-up. The initialized global options are those used in the ensuing session of the Calendar Tool, and those presented to the user when she executes the `Options->Global' command. The initialized host connection table is that which is used during the ensuing session, and that which is presented to the user when she runs the `Admin->Connect' command. The list of which calendars, if any, to open at start-up is in the `names of open calendars' component of the settings file. Further discussion of the Calendar Tool start-up procedure is in Section .

The system does not use the calendar-specific component of the Settings file at start-up. Rather, for each calendar it opens at start-up, it uses the calendar-specific settings stored in that calendar's file. This includes the calendar-specific settings for viewing options and the setting for the `state of open windows' for each calendar. These settings determine which windows are opened for each start-up calendar. The calendar-specific component of the Settings file is used when the user creates a new file, as described in Section 2.8.2.

When the user runs the `Load Settings' command in the `File' menu, the system displays the dialog shown in Figure 297.


Figure 297: Load-settings dialog.



The user may select via checkboxes which parts of a settings file to load, and from which file to perform the load. All of the checkboxes are on by default. When the filter settings checkbox is on, the system automatically checks and disables the categories checkbox. This is because custom filter definitions may be defined in terms of calendar-specific categories. If the user unchecks the filters checkbox, the categories checkbox is enabled for independent checking or unchecking.

If the user invokes `Load Settings' when there is no current open calendar, the system unchecks and disables all of the calendar-specific checkboxes under `For the current calendar'. In this case, only the settings for global options and the host connection table can be loaded. If the user invokes `Load Settings' when one or more calendars is connected, the `host connection table' checkbox is unset and disabled. This means that the host connection table cannot be loaded from settings when there any active connections.

The default file in the load-settings dialog is the standard Settings, in the Calendar Tool user directory. The dialog shown Figure 297 reflects the user having previously saved two settings files in addition to the pre- installed "Settings". Only Calendar Tool settings files and directories are enabled in the scrollable file list. The user can type, navigate, and select in the dialog in the same manner as described for the `Open' dialog in Figure 286.

Figure 298 shows the user having chosen to load a subset of the settings stored the file "OfficeSettings".


Figure 298: Load-settings dialog filled in.



When the user presses `OK', the system displays the confirmation dialog shown in Figure 299.


Figure 299: Confirm load settings.



The dialog explains that loading settings may cause changes to the calendar and its display windows, and that changes will be made without further confirmation. The dialog further explains that any currently unconfirmed or unapplied settings edits will be canceled. What this means precisely is that if the user has edited by not applied or confirmed changes to settings that are being loaded, the dialogs in which the edits have been performed are canceled. This cancellation applies only to dialogs for settings checked on in the load- settings dialog. Edit dialogs for unchecked settings are not canceled. For example, if the user has edited a category definition but not yet confirmed the edits, and the `categories' checkbox is on, the system cancels the categories editing dialog and loads the settings. On the other hand, if the user has unapplied edits to calendar-specific options, but the `options' checkbox is off in the load-settings dialog, then the options dialog is unaffected by the settings load, and the dialog remains open with the still unapplied edits.

If the users answers `OK' in the load-settings dialog, the system performs the following actions:

  1. copies the values for calendar-specific settings from the settings file into the current calendar; this is done for the settings with the checkbox turned on; unchecked settings values are not copied, leaving them unchanged in the current calendar

  2. confirms and applies all setting changes

  3. performs all processing that results from changed, added, or deleted calendar- specific settings

  4. re-initializes the session's global options and host table from the settings file; this is performed when the associated checkbox is on; if either or both checkbox is off, the global settings and/or connection table are left unchanged for the current session
When the system performs copying of calendar-specific settings, the values from the settings file completely replace all of the calendar-specific settings values in the current calendar. If values copied from the settings file are the same as those in the current calendar, then those values are effectively unchanged.

The effective change of values is particularly relevant to the definition of categories, custom lists, and custom filters. If any of these definitions are exactly the same in the settings file and the current calendar, then these definitions remain effectively unchanged in the calendar. Any definitions in the settings file that are not the same as the current calendar cause a change, addition, or deletion to the calendar. Table 16 specifies precisely what constitutes the same definition, a changed definition, a definition to be added, and a definition to be deleted.



Type of Definition Same Change Addition Deletion
category same name and color same name with different color new name in settings file that is not in calendar name in calendar that is not in settings
custom list and
custom filter
same name and values same name with one or more different values new name in settings file that is not in calendar name in calendar that is not in settings

Table 16: Comparison of definitions in settings file versus current calendar.



Once calendar-specific settings values are loaded, the system confirms and applies all loaded values. In particular,

The system then performs all processing that results from changed, added, or deleted settings values. If this processing would require further user confirmation, the system proceeds as if the confirmation is affirmative (`OK' or `Yes'). The sections of the requirements that specify the processing associated with each type of calendar setting are those cited parenthetically in the list at the beginning of Section 2.8.1.

Changes to category definitions and options are the only setting changes that may result in immediate changes to scheduled items in the current calendar. The category changes that have immediate effect are those described in Section 2.5.5 that result from color changes or deletions of category definitions. Changes in meeting-scheduling options can have immediate effect if the current calendar is connected to a host and the loaded options change the setting of when pencil-ins are accepted to `whenever connected to the originating host`.

Changes to custom lists, filters, options, and windowing mode may result in changes to the appearance of scheduled items in display windows, but not in the items themselves. Changes to page setup and print settings take effect only when the user executes the `Page Setup' and `Print' commands.

When the system re-initializes the host connection table, it completely replaces the contents of current the session-wide table with the entries in the settings file. The "session-wide table" is that in use in the current Calendar Tool session, as it appears when the user runs the `Admin->Connect' command. To avoid undue disruption, the checkbox to load host connection settings is unset and disabled when one or more hosts is connected in the current Calendar Tool session. Changes to the host connection table may lead to changes in scheduled items being downloaded from the host. However, these changes are not immediate when settings a loaded, because no hosts can be connected when the host connection table is loaded from a settings file. Complete discussion of the host connection table is in Section 2.6.6.1.

It is noteworthy that two parts of the settings file are missing from the load-settings dialog. These are the the calendar-specific setting for the `state of open windows', and the session-wide setting for the `names of open calendars'. These settings are used, and are only manageably meaningful, when the settings file is loaded at start-up, or in the case of open windows, when a calendar is opened.

When the user selects the `Save Settings' command, the system responds by displaying the dialog shown in Figure 300.


Figure 300: Save-settings dialog.



The figure reflects the state of the Calendar Tool user directory before any settings files have been saved. The dialog is very similar in content to that for loading settings, with the addition of the two settings noted just above as missing from the load dialog. The user may select via checkboxes which parts of a settings file to save, and to which file to perform the save. All of the checkboxes are on by default. When the filter settings checkbox is on, the system automatically checks and disables the categories checkbox. This is because custom filter definitions may be defined in terms of calendar-specific categories. If the user unchecks the filters checkbox, the categories checkbox is enabled for independent checking or unchecking.

If the user invokes `Save Settings' when there is no current open calendar, the system unchecks and disables all of the calendar-specific checkboxes under `From the current calendar'. In this case, only the session-wide settings can be saved. If the user invokes `Save Settings' when one or more calendars is connected, the settings can still be saved, but the connected state is ignored. That is, the host connection table is always saved with the `Connected?' column blank.

The default file in the save-settings dialog is the standard Settings, in the Calendar Tool user directory. The values shown Figure Figure 300 reflect the initial state of the dialog, with the pre-installed "Settings" file, before the user has saved to any other settings files. Only Calendar Tool settings files and directories are enabled in the scrollable file list. The user can navigate and select in the dialog in the same manner as described for the `Save As' dialog in Figure 294. The `OK' button is enabled except when the user does one of the following:

The system disallows saving in any of these circumstances. If the user continues typing to change these circumstances, the system re-enables the `OK' button.

Figure 301 shows the user having chosen to save a subset of the settings to the file "OfficeSettings".


Figure 301: Save-settings dialog filled in.



When the user presses `OK', the system performs the following actions to complete the save:

  1. copies the checked calendar-specific settings from the current calendar to the selected settings file

  2. copies the checked session-wide settings to the selected settings file
  3. for the unchecked calendar-specific settings, the system does one of the following:

    1. if the saved-to settings file exists, the unchecked settings in the file are not changed

    2. if the saved-to settings file does not exits, the system copies the built-in default values to the settings file; Table 15 defines the values of built-in calendar-specific settings

  4. for unchecked session-wide settings, the system copies the built in values, which are as shown in Figure 281 for global options, and are empty for both the host connection table and list of open calendars

In saving the state of open windows, the system saves all physical details of all windows associated with the current calendar. These details are the window content, size, position, and state of iconification. In saving calendar view windows, the system uses the specific absolute dates in the display, not dates relative to today's date. For example, if there is a month view for September in an active window, the system saves the state of that window as open for that specific month. If the user subsequently opens the calendar with the saved settings in, say, October, the month view opened from the saved settings is still September. The system always highlights today's date in any calendar view that contains today's date. However, if a view saved in the settings contains today's date when it is saved, but not when the settings are later loaded, the view cannot and does not have today's date highlighted. The point again is, views saved in the `state of open windows' setting are saved with the absolute dates displayed at the time of saving, and the dates are not adjusted relative to today's date when the settings are subsequently loaded. If the user wants the initial view of a calendar to be relative to today's date, she can use a viewing option other than `per most recently saved settings', as described in Section 2.7.4.3.

The system does not display an overwrite warning if the user saves to an existing settings file. This is because the user may frequently save settings to an existing file, in particular the Settings file in the Calendar Tool directory. In this sense, overwriting an existing settings file is more a normal than exceptional activity.

When the user saves settings to the standard Settings file, the saved values become those that are used as the defaults when the Calendar Tool starts up, and as the defaults for new calendars. In this way, the current calendar serves as the basis for the standard default settings. If the user wants different values for the standard defaults, she can change the current calendar and save again to the standard Settings file.

Confirming the `Save Settings' command results in a change to the selected settings file, but not to the current calendar. Hence, the system performs none of the change-related processing associated with loading settings shown in Table 16.

Table 17 summarizes all of the ways that the user can save settings to a calendar file or to a settings file.



Command Type of saving performed
`Save' command in the `File' menu All calendar-specific settings in the current calendar are saved to the file associated with current calendar; there is no change to any settings file, and in particular, session-wide settings are not saved anywhere.
`Save As' command in the `File' menu All calendar-specific settings in the current calendar are saved to the selected calendar file; there is no change to any settings file, and in particular, session-wide settings are not saved anywhere.
`Save Settings' command in the `File' menu Checked settings are saved to the selected settings file; unchecked settings are unchanged in an existing file, defaults in a new file; no calendar file is affected.
`Save' button in the global options dialog Global options are saved to the Settings file in the user's Calendar Tool directory; all other settings are unchanged in the Settings file; no calendar file is affected.
`Save' button in the host connection dialog The host connection table is saved to the Settings file in the user's Calendar Tool directory; the `Connected?' column is fully blank in the saved table; all other settings are unchanged in the Settings file; no calendar file is affected.

Table 17: Summary of ways to save settings.



2.8.6. Page Setup and Print

Printing from the Calendar Tool is based strictly on the content visible in active Calendar Tool windows. Window content appears on the printed page exactly as it appears on the screen. "Exactly" means the content of the printed page is the same in appearance and absolute size as it appears on the screen. Scrolling lists and other scrollable components of the display are not expanded in the printed output. The printed content excludes the window banner, any bordering other than a single black line, and any content that is not visible within the window frame on the screen. This means there is no page numbering, header, footer, or other page labeling.

When the user selects the `Page Setup' command in the `File' menu, the system displays the dialog in Figure 302.


Figure 302: Page setup dialog.



The `Orientation' setting defines the width-by-height orientation of pages. With the default selection of `portrait', pages are laid out with the width dimension running horizontally and the height dimension running vertically. When `landscape' is on, the width dimension runs vertically and the height dimension horizontally.

The `Page Size' values define the size of a page in inches. The `Margins' values define the unprintable area between the edge of the page and the edge of the printed content. When possible, the Calendar Tool queries the underlying operating environment to determine page size and margin settings for the currently selected printer. When such determination is made, the system inserts the values as the defaults in the page setup dialog. If the system cannot make this determination, the default width and height values are 8.5 and 11 inches, the default margins are all .5 inch.

The user can manually adjust the page size and margin settings to accommodate the paper size and margin requirements of different printers. In doing so, it is the user's responsibility to enter page size or margin values that can be accommodated on a particular printer, such that printed content is not cropped on the page.

The `Scale' setting defines the scale of the printed content relative to the printed page. The default is 100%.

When the user selects the `Print' command in the `File' menu, the system displays the dialog in Figure 303.


Figure 303: Print dialog.



The user selects the printer to which output is directed from a list of available printers. When possible, the Calendar Tool queries the underlying operating environment to determine the identity of the user's preferred printer. When such determination is made, the system inserts the name of the printer as the default value in the `Printer' field. If the user's preferred printer cannot be determined, the field is blank.

The user can select to print the current window only, all windows of the current calendar, or all active windows. Per Section 2.3.6, an active window is any that appears in the `View->Windows' submenu. Iconified (i.e., minimized) windows are considered active. The successive print order multiple of windows is based on the top-to-bottom order of windows in the `View->Windows' submenu.

The user may select the number of copies of each window to print, the default being 1. The `Collated' checkbox is enabled if the user selects more than 1 copy. If `Collated' is off (the default), the system prints all copies of the same window in immediate succession, before printing the next window. If the user turns `Collated' on, the system prints one copy of each window in succession before beginning the next copy of the each window.

When the user presses `OK' in the print dialog, the system proceeds with the printing. If a window fits on a single page based on the page setup parameters, the system prints the window centered on the page. The system does not print more than one window per page, even if more than one window could fit on a single page. If a window is too large to fit on one page, the system prints as much per page as possible, printing the multiple pages of the same window in row-wise order. The multiple pages of a single window are all left and top justified to the defined margins, not centered as for single-page windows.

There may well be additional functionality for page set up and printing in specific operating environments. This includes the ability to set other printer parameters, preview printed pages, and define other forms of page layout. Implementors must provide all such available functionality. Implementors are required to provide only generic page layout functionality, not content-specific layout. Contentwise, layout is at most one window per page, as described above.

2.8.7. Exit

When the user selects the `Exit' command in the `File' menu, the system begins the exiting process by executing the `Close All' command. The associated processing for `Close All' ensues, including any necessary user interaction through the warning dialogs. This is described in Section 2.8.3. If the user responds at any point such that the `Close All' is canceled for all remaining calendars, the `Exit' operation is also thereby canceled.

Once the `Close All' has run to completion, the system checks if there are unsaved session-wide settings. If so, the system displays the dialog shown in Figure 304.


Figure 304: Offer to save session-wide settings before exit.



If the user answers `Yes', the system saves all session-wide settings to the Settings file in the user's Calendar Tool directory. If the user answers `No', the system does not save session-wide settings, thereby losing any unsaved changes. If the user presses `Cancel', the systems cancels the `Exit' command and removes the offer-to-save-settings dialog from the screen, leaving all calendars closed but the Calendar Tool still running.

When the user answers `Yes' or `No', or if the session-wide warning dialog was not displayed, the system proceeds with the `Exit' operation by terminating the current session of the Calendar Tool, thereby returning the user to the underlying operating environment.

2.8.8. Files Used by Calendar Tool Administration

Sections 2.6, and , contain general discussions about the data repositories on Calendar Tool central host computers. This section presents specific details of the directory and file structure of the repositories.

A central host data repository consists of the following storage components:

The internal structure of repository directories and files is implementation-dependent. The externally-visible names and organization of the files are shown in Table 18.



File or Directory Usage
Users user database file or directory
Groups group database file or directory
Locations location database file or directory
Calendars directory of user and group calendar files, with each root file name identical to the Calendar Tool user or group ID of its owner
Settings administrative settings

Table 18: Central Host Data Files.



When the Calendar Tool Administration program is installed, initial versions of the repository files and directories are created, as described in Section The file and directory names shown in Table 18 are fixed. The three databases are either single files or directories organized in some implementation-specific manner. The Calendars directory must contain one file for each user and group calendar, with user and group ID as the root filename. The internal structure of the files and possible filename extensions is left to the implementors.

The fact that the databases may be a file or a directory allows the implementors to use a database representation that is either in a single file or multiple files in a parent directory. Independent of this level of implementation detail, the implementors must meet the following specific requirements:

  1. the three databases must be in three separate files or directories

  2. the names of the files or directories must be those in Table Table 18

  3. user and group calendars must each be stored in a separate file
The purpose of these requirements is to allow the administrator readily to assess the size of databases and calendars using the normal file sizing functionality of the underlying operating environment.

The repository files and directories are themselves stored in a single directory, specified initially when the Calendar Tool Administration program is installed. This superdirectory is the root of the entire central host repository. If there are conventions in a particular operating environment for where such application-specific files should be stored within the file system, then such conventions can be followed during installation. After installation, the administrator can change the location of the repository directory, if necessary. This is done by changing the administrative option setting described in Section 2.7.7. The repository directory may contain other files at the discretion of the administrator. In particular, an administrator may choose to create settings or sample calendar files, to be distributed to users as a convenience. These files are created with the regular-user Calendar Tool, run by an administrator who has privileges to save files in the repository directory.

2.8.9. Administrative Save and Save Copy

When the administrator executes the `Save' command in the administrative file menu, the system saves all changes made to any data since the last save. Changes to "any data" mean any data added, changed, or deleted in any of the administrative dialogs discussed in Sections 2.6.2 through 2.6.5 of the requirements. As discussed in Section 2.8.8, administrative data are stored in fixed files in a fixed location; these are the files to which data are saved.

To save a copy of all repository data, the administrator uses the `Save Copy' command. In response, the system displays the dialog shown in Figure 305.


Figure 305: Save-copy dialog.



The administrator selects the parent directory into which a copy of all repository files is to be saved. The administrator can navigate and select in the dialog in the same manner as described for the `Save As' dialog in Figure 294. The `OK' button is enabled whenever a writable directory is selected in the scrolling list. For example, Figure 306 shows the administrator having selected to save a copy of the repository in the directory "/usr/local/caltool/Backup", which in his case is a subdirectory of the repository itself.


Figure 306: Save-copy dialog filled in.



When the administrator presses `OK', the system saves a complete copy of all repository files in the selected directory. A "complete copy" means that all directories and files listed in Table 18 are fully copied. No other files that happen to be within the repository superdirectory are copied. If there are one or more files or directories within the destination directory of the same name as the copied files, the system provides no overwrite warning. Existing directories are written into, existing files are fully overwritten.

The save-copy command does not affect the files in the fixed repository location, and does not change the location of the fixed repository. When the administrator subsequently executes the `Save' command, data are saved to the fixed repository.

2.8.10. Administrative Page Setup and Print

Administrative page setup and print commands provide precisely the same functionality as in the regular-user Calendar Tool, described in Section 2.8.6. As with Calendar Tool printing, output is based strictly on the content visible in active administrative windows. The page-setup and print dialogs are the same.

2.8.11. Administrative Exit

When the administrator executes the `Exit' command, the system checks if there are any unsaved changes to repository files or pending dialog edits. If either or both of these conditions is true, the system displays the dialogs of Figures 307 and 308, respectively.


Figure 307: Offer to save repository data before closing.






Figure 308: Warning when there are pending edits in administrative dialogs.



If the administrator answers affirmatively in both cases, or if the dialogs were not displayed, the system proceeds with the `Exit' by terminating the current session of the Calendar Tool Administration program, thereby returning the administrator to the underlying operating environment. Termination of the administration program does not terminate the Calendar Tool server program. The server remains running asynchronously until the administrator executes the `Stop Server' command, as described in Section 2.6.5.1.

2.8.12. External Changes to Calendar Tool Files

As explained in the preceding scenarios of this section, both the Calendar Tool and Calendar Tool Administration program normally attempt to disallow opening and saving to ineligible files. However, if a user changes or deletes files when the Calendar Tool or Calendar Tool Administration are running, normal operation may be disrupted. Section enumerates the conditions under which file-related errors can occur and the associated error messages.

2.8.13. Operating Environment Conventions

Different operating environments may have conventions for many aspects of file handling. There may be conventions for file naming, including characters allowed in file names, the length of file names, and the designation of a users "home" directory. There may be varying functionality for file-selection dialogs, filespace navigation, and other basic features of file management. Environments may also have conventions for the location of installed files and directories, such as a user's Calendar Tool directory.

Implementors may follow required or appropriate conventions, but must implement the features described in these requirements insofar as is possible. In particular, the feature of the user being able to type a file name in the file-open dialog must be retained, even if it is not standard in a particular operating environment. Also, the user must be able to change the location of the Calendar Tool user directory, even if the operating environment recommends the placement of such directories in a particular location.




Prev: options | Next: edit | Up: functional | Top: index