Xrolodex

File: README.xrolodex

Version: xrolodex 1.6

/**********************************************************************

• Copyright (c) 1991 - 1996 Iris Computing Laboratories.
• This software is provided for demonstration purposes only. As
• freely-distributed, modifiable source code, this software carries
• absolutely no warranty. Iris Computing Laboratories disclaims
• all warranties for this software, including any implied warranties
• of merchantability and fitness, and shall not be liable for
• damages of any type resulting from its use.
• Permission to use, copy, modify, and distribute this source code
• for any purpose and without fee is hereby granted, provided that
• the above copyright and this permission notice appear in all copies
• and supporting documentation, and provided that Iris Computing
• Laboratories not be named in advertising or publicity pertaining
• to the redistribution of this software without specific, written
• prior permission. **********************************************************************/

Programmers: See the comments near the end of this file regarding the makefile, Motif versions, etc.

xrolodex' is a Rolodex(R)-style application for maintaining a set of "virtual business cards." xrolodex's top-level window includes four principal components:

• an application-level menu bar,
• a label area for displaying the name of the current rolodex file,
• a control panel for entry-level rolodex manipulation, and
• an edit window (with local menu bar) for editing the currently displayed rolodex entry, also providing a basic viewport facility.

`xrolodex' has the following command-line option:

{system prompt} xrolodex [<filename>] [-iconName <icon name>]

The filename is optional. That is, you can specify a file via the file selection box that's activated by the "Open" entry in the "File" menu.

To create a new rolodex file, first use "Open" to associate the rolodex contents with a filename, and then simply type in each entry.

`xrolodex' has the following client-level resources:

Resource Default Value Range of Values Type

---

centerDialogs True {True, False} Boolean directoryMask $HOME/*.xrolo any char. string string entryDelimiter "####\n" any char. string string findSensitive False {True, False} Boolean findWraparound False {True, False} Boolean forceSave True {True, False} Boolean indexColumns 30 positive integer integer indexRow 1 positive integer integer indexRows 15 positive integer integer indexStayUp True {True, False} Boolean minimalDialogs True {True, False} Boolean sortRow 1 positive integer integer viewportColumns 40 @ 6 or greater integer viewportMenuBar False {True, False} Boolean viewportRows 12 @ 12 or greater integer

The centerDialog' resource applies to the pop-up, warning dialogs only, not the text-entry dialogs. You can control various aspects of the text-entry dialogs via the resource minimalDialogs'.

The default viewport menu is a pop-up, background menu; see the "Editor" help menu. There are approximate lower limits on the size of the viewport window because Motif will force the viewport's row-column dimensions to be large enough to fill the top-level window, which must be large enough to accommodate the top-level menu bar and the control panel.

Unless otherwise specified using the directoryMask' resource, xrolodex' uses your home directory as the reference point for the file selection box.

The findSensitive' and findWraparound' resources control the start-up states of the "Case sensitive" and "Wraparound" toggles in the "Find Entry..." window.

The `forceSave' resource controls whether the "Save" option in the "File" menu saves the rolodex file or simply ignores the save request when there have been no modifications.

The default card delimiter sequence is "####" on a separate line, that is, "####\n". There is no reason for the typical xrolodex' user to specify the delimiter option; it is transparent during normal xrolodex' use. Note, however, that you can dynamically modify the delimiter sequence from the "Options" menu.

The editor facility provides menus for copy, cut, and paste operations and for search and replace operations. Again, the editor window allows the user to edit the text within the currently displayed rolodex entry, not the entire rolodex file--the scrollbar will not navigate across entries. Entry-level rolodex operations are performed elsewhere. Since the editor maintains its internal state from one entry to the next, you can copy and paste text across entries.

With xrolodex' the rolodex database is completely free-form. There are no limitations on the number of entries, and no limitations on the character dimensions of an individual entry. Individual entries are delimited in the rolodex file by preceding each entry with "####" on a separate line--xrolodex' depends on this convention. Note that you can specify a different delimiter sequence from the command line.

Since xrolodex's rolodex file is a simple stream of bytes, experienced UNIX users can use other text processing tools to manipulate the rolodex file(s). In particular, you can use your own/preferred text editor, if you need to perform a considerable amount of editing on a particular file. With xrolodex' you can maintain as many distinct rolodex files as you'd like. The "Open..." menu option allows you to load any rolodex file via a file selection box. The file type is "*.xrolo" in the user's home directory.

During normal operations, `xrolodex' maintains a rolodex file in memory. That is, when you "open" a file, its contents are read into RAM, and all rolodex operations are applied to this "memory file." When you select "Save" from the "File" menu, the rolodex file as it exists in memory is saved to disk, replacing the original rolodex file. The first time that a file is saved after it's been loaded with "Open..." a back-up of the original file is created with ".bak" appended to the filename. For subsequent save operations (without an intervening use of "Open..."), the back-up file remains unchanged.

The "Quit" menu option terminates the application without saving pending modifications to the rolodex file. If there are unsaved changes to the file, you are prompted and given the opportunity to save changes to disk before the program terminates. The "Exit" menu option terminates the application after saving any pending modifications to the rolodex file; the save process is automatic, i.e., there is no user prompt.

There is no "New" menu entry. To create a new rolodex file, first use "Open" to associate the rolodex contents with a filename, and then simply type in each entry.

When viewing an individual rolodex entry you can change it simply by moving the mouse pointer into the rolodex entry viewport and using normal Motif editing commands--the viewport is implemented with a standard Motif text widget. If the number of lines exceeds the height of the window, you can scroll the edit window.

Within the edit window you can copy, cut, and paste text for the current rolodex entry, and you can use the "Find Selection" menu option to find the next occurence (forward) of the currently selected text. The "Search and Replace..." menu option activates a top-level window that you can use to enter search text manually. It also contains a "Replace" button so that you can "Find" a text segment and then "Replace" it. Coordinated operations with "Find" and "Replace" will allow you to make changes to the text throughout the current rolodex entry.

There are pull-down menus in the main menu bar that group together logically related operations for entry-level rolodex manipulation. At present, "Edit" contains the buttons: "New/Ins", "New/Add", "Copy", "Delete", and "Undelete". The "Find" menu presently contains the buttons: "Index..." and "Find Entry...". The latter two buttons pop up dialog boxes. These buttons are explained below.

For convenience, several of these buttons are present in the control panel as well. The control panel is to the left of the viewport and is used for moving among rolodex entries. It contains buttons for the most commonly used operations so that the user doesn't have to go to a pull-down menu. The "First", "Last", "Next", and "Previous" buttons are self-explanatory. Several other command buttons require explanation.

"Index..." activates a top-level window that, by default, displays the first line/row of every rolodex entry. With this convention in mind, you should make sure that the beginning of the first line of each entry contains meaningful information, e.g., a person's name. If you select one of the entries displayed in the index window, that rolodex entry will be displayed in the edit window/viewport. Optionally, you can set the index row with the `indexRow' resource, or modify it dynamically from the dialog box that's accessed through the "Set Index Row" submenu.

"Find Entry..." activates a top-level window in which you can enter a string. `xrolodex' will search forward or backward, beginning with the next (previous) rolodex entry, for the first entry that contains the specified text string, presenting that entry in the viewport. By default, text searches across entries are case insensitive. You can enable case sensitive searching with a toggle button from the radio box. You can also enable wraparound searches from the last to the first and the first to the last entries.

"New/Ins" clears the edit window and allows you to