readme.xrolodex

`smith.motif.tar.Z includes the source code for the book "Designing X clients with Xt/Motif," by Je

File:  README.xrolodex

/**********************************************************************
*  Copyright (c) 1991, 1992 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.
**********************************************************************/

`xrolodex.tar.Z' includes the source code for a Motif rolodex
application.  Note that you must have X and the Motif libraries
to compile `xrolodex'.  This X client is further described in the
book "Designing X clients with Xt/Motif," by Jerry D. Smith,
Morgan Kaufmann, 1992 (available @ July 1992).

Note:  There is an existing XView program named `xrolo', so please
do NOT rename `xrolodex' to `xrolo'.  Having distinct names will
eliminate confusion and allow some users to install both products.

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

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
--------            -------------    ---------------       ----
viewportMenuBar     False            {True, False}         Boolean
viewportRows        12               @ 12 or greater       integer
viewportColumns     40               @ 6 or greater        integer
indexRows           15               positive integer      integer
indexColumns        30               positive integer      integer
centerDialogs       True             {True, False}         Boolean
entryDelimiter      "####\n"         any char. string      string
directoryMask       $HOME/*.xrolo    any char. string      string

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.

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.

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 displays the first line
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.

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

"New/Ins" clears the edit window and allows you to enter a new
rolodex entry.  `xrolodex' *automatically* saves the contents of the
current rolodex entry in the file (if modifications have been
made) any time that you preform an operation that switches to
another rolodex entry, e.g., "Next", "Index", etc.

"New/Add" is similar to "New/Ins", except that it inserts/adds the
entry *after* the current entry.  The insert/add operations are con-
sistent with text editors, such as `vi', where "insert" means before
the current character and "add" means after the current character.
Also, "New/Add" makes it possible to add an entry to the very end
of the rolodex database.

You can select "Copy" to enter a duplicate of any entry into the
rolodex file.  This provide a convenient mechanism for creating a new
entry by copying an existing rolodex entry, and then making changes
to the new entry.  As an alternative, you could use "Copy" (from the
viewport "Edit" menu) to copy an entry's text to the clipboard,
select "New" to create an empty entry, and then "Paste" the text
from the clipboard--pressing "Copy" is considerably faster.

"Delete" deletes the current rolodex entry.  `xrolodex' provides a
single level of undo capability for "Delete"ions with the "Undelete"
button.  "Undelete" recovers the deleted entry at the current
position in the rolodex file.

Programmers
-----------
There is a simple makefile in `xrolo.make', so that you can simple copy
the entire project into a working directory and type `make -f xrolo.make',
if you don't want to install `xrolodex' in the MIT or Motif X source tree.

This source code has been tested extensively in a Sun SPARCstation, MIT X
environment with Motif 1.1.x under CodeCenter/Saber-C.  There are
no known errors/problems.

THIS APPLICATION CURRENTLY USES THE DEFAULT XT ERROR HANDLER AND CAN
TERMINATE UNEXPECTEDLY--WITH UNSAVED CHANGES IN THE EDIT WINDOW.
YOU MAY WANT TO ADD A CUSTOMIZED ERROR HANDLER.

Jerry Smith
Iris Computing Laboratories
[e-mail]