SGI Freeware 1998 June/SGI Freeware 1998 June.iso/dist/fw_ATxgopher.idb/usr/freeware/doc/xgopher/Customization.z/Customization

Text File | 1998-01-21 | 15.2 KB | 356 lines

Customizing Xgopher
-------------------
This document describes how an end user may change color, fonts, and
other some behavior of Xgopher.  It also documents some other parameters
that may be configured at installation time.

When we refer to setting an X resource we allow the readers to choose
the methods that they are most familiar with already.  There are many
ways to set resources for X Window System applications.  We refer you
to a standard reference for X such as "X Window System User's Guide" by
Quercia and O'Reilly, published by O'Reilly & Associates, Inc.

We also use the term "application defaults" as another way to refer to
the resources of an application.



Color
-----

When displayed on a black and white X display Xgopher will normally
have a white background and a black foreground.  That is, text, borders,
and lines will be black on white.  If you prefer the opposite visual
effect, you may use the standard X Toolkit option -rv on the command
line or "reverseVideo: True" in your resources file.  The reverse
video option is processed by all clients, including Xgopher, that use
the X Toolkit for argument processing.  The effect of this option is
to reverse all occurrences of the colors black and white.  (Some clients,
such as Xterm, do not process -rv correctly.)

A suggested color scheme is distributed with Xgopher.  The easiest way
to change colors is just to modify these supplied resources.  Most
of those color resources are specified for an entire class of widget.
For example, rather than setting the color of each button individually,
the resources file contains the line

    Xgopher*Command*background:  LemonChiffon

Which sets the background for all widgets which are of class "Command"
(the push button) or are subclasses of Command.  Note that class names
are capitalized.

The internal border color resource (internalBorderColor) is not well
known.  It separates the panes of the "paned" widget, the one used for
the main Xgopher panel.  If you change the color of other lines and
borders, be sure to change this one also.



Font
----

The fonts in the distributed resources file may be changed also.  Most
of the Xgopher displays will size themselves according to the font
selected.  The main Xgopher panel is an exception.  If you change the
font size considerably from the default you may need to change the
following resources:

    Xgopher*directoryForm.preferredPaneSize:  300
    Xgopher*bookmarkForm.preferredPaneSize:   125
    Xgopher*status.width:           500
    Xgopher*directoryTitle.width:   500
    Xgopher*bookmarkTitle.width:    500
    Xgopher*directory.width:        500
    Xgopher*bookmark.width:         500

The first two are the height in pixels of the initial directory and
bookmark areas of the main panel.  The last 5 should all be the same
and are the width of the main panel in pixels.  You will probably have
to determine these numbers from inspection after changing the fonts.

In the resources file are suggested alternative fonts for a larger
display to be read by more than one person at a time.  At the University
of Illinois we use Xgopher on a 19-inch display with a touch screen
instead of a mouse.  Here the font used for directory presentation is
a 24-point font to allow reasonably accurate selection with a fingertip.
This makes the main panel almost the height of the screen,



Text and Labels
---------------

Every button, menu item, and label have there text value defined in the
resources file.  Some messages and most errors are constructed in the
code itself and would be more difficult to change by the end user.
The labels can be changed to make them more terse, more verbose, or
non-English.  Xgopher does not use any I18N functions, so you are still
restricted pretty much to the ISO Latin-1 character set.  This allows for
most European languages to be used, but not many others.



Translations
------------

The X Toolkit defines a mapping from keyboard and mouse events to
application-defined actions.  Some of these are built in to standard
components, for example, "clicking" mouse button 1 inside a command
(push button) widget will activate that function.  You may redefine
this behavior if you wish.  Volume 4 of the O'Reilly series on the
X window system provides a reference for this ("X Toolkit Intrinsics
Programming Manual", by Nye and O'Reilly, O'Reilly & Associates, Inc).

For a one-button mouse or touch screen, the default scrollbar behavior
is not usable.  The following translations work better:

  *Scrollbar.Translations: \
      <Btn1Down>:   StartScroll(Continuous)MoveThumb()NotifyThumb()\n\
      <Btn1Motion>: MoveThumb()NotifyThumb()\n\
      <BtnUp>:   NotifyScroll(Proportional)EndScroll()\n\
      <Key>F35:  StartScroll(Forward)NotifyScroll(Proportional)EndScroll()\n\
      <Key>F29:  StartScroll(Backward)NotifyScroll(Proportional)EndScroll()\n

The first three lines allow button one alone to move up or down in the
scrolling region by clicking or by dragging the "thumb".  The last two
lines define the keys on a Sun SparcStation 1 keyboard labeled "PgDn"
and "PgUp" to be used instead of the mouse to scroll down or up.

Xgopher also defines some of its own actions that you may define a
translation for.  Most of the text entry panels that accept only a
single line of input define an action for the "Ok" function.  The default
translations for each of these defines a "return" ("enter") key press
to invoke the "Ok" action.  If you press "return" on the file-save,
index-search, or cso-name-server panels after entering text, it is the
same as pressing the "Ok" (or "do query") function.

On the main Xgopher panel there is an "up" action defined equal to
the "previous directory" button.  Pressing the "u" key while the X
pointer is anywhere on the main panel will invoke this function.

All of the above translations may be eliminated or changed by modifying
the translations in the resources file.



Size and constraint resources
-----------------------------

Most of the resources in Xgopher are for setting the size or placement
constraints on individual components of the user interface.  The
constraint widgets should not be changed by most people.  To change
one of these may have consequences beyond that of changing a color for
example.  Most of the constraint resources have been moved into the program
(out of harm's way).

The size resources described in the above section on fonts may be safely
changed, but usually are only changed to accommodate a larger or smaller
character size.



Window Manager Behavior
-----------------------

The Xgopher pixmap supplied in the file bitmaps/xgopher.xbm can be used
as the icon for the Xgopher application when using one of the common
window managers.  If xgopher.xbm is installed into the directory
<pathname>, you can use it as the icon for all Xgopher windows by
including the folling line in your resource file:

    Xgopher*iconPixmap:     <pathname>/xgopher.xbm

(Adjust the path name to reflect the actual path name of the bitmap
file.)  Individual types of Xgopher windows can be similarly configured
to have distinct bitmaps, but these are not supplied with Xgopher.

While not strictly an Xgopher customization option, the window manager
may be configured to better interface with Xgopher.  Since Xgopher uses
several top-level windows and transient windows some of these options may
make Xgopher easier to use.  The two window managers in most common use
are twm (and its descendents) and mwm.

Each of these has an option that will either automatically place a newly
created window on the screen or allow the user to move and position
an outline of the window first.

Another option available is whether to "decorate" transient windows.
These are short-lived windows usually asking for information (e.g.,
file-save or index-search).  The decorations are the title bar and various
menu/kill/iconify type of buttons that usually are placed on or near the
title bar.

You can use a window manager option to set the icon pixmap instead of
the Xgopher*iconPixmap resource described above.
The  bitmap image is supplied in the directory ./bitmaps/xgopher.xbm
and is suitable for use as a window manager icon.  If xgopher.xbm
is installed into the directory <pathname>, you can use it as an
icon bitmap under mwm by including the lines in your mwm resource
file:

    Mwm*useClientIcon:              True
    Mwm*Xgopher*iconImage:          <pathname>/xgopher.xbm

Similar resources apply to twm.  In your .twmrc file, use:

    # if the directory containing xgopher.xbm is not already
    # in your bitmapFilePath, add:
    IconDirectory                   "<pathname>/bitmaps"
    Icons
    {
        "Xgopher"       "xgopher.xbm"
    }

For both mwm and twm other resources may also affect your icon appearance.

You may want to install the icon file in the directory /usr/lib/X11/Xgopher/,
or wherever the help file is already stored.  If you do put the icon bitmap
somewhere, you may want to modify the Xgopher man page to provide this
information to other users.

Finally, most window manager provide a main window menu that includes
functions to move, resize, iconify, and terminate a window.  The
termination function is processed specially by both the window manager
and the application.  Xgopher complies with the window manager protocol
that allows the window manager to ask the client to shut down rather
than just suddenly and ungracefully killing the client application.

mwm's "f.kill" function will correctly inform Xgopher that a "remove"
request has been made against a given window.  Xgopher will close and
remove that window.  If the window is the main panel, Xgopher will quit.

twm's "f.delete" behaves in a manner similar to mwm's f.kill function.
It is deficient in that for clients that do not honor the ICCCM
conventions, f.delete will have no effect except to provide an audible
beep.  twm's "f.destroy" function is quite harsh.  There is no intercepting
its action.  It will simply destroy the entire application, no matter
which window of the application was selected.  f.delete should be normally
used in a windows main menu.  f.destroy should be used in only when
absolutely necessary.



Image display
-------------

Xgopher displays an image file by invoking another command which must
be already installed or available on your system (on the same host
as is running the Xgopher program).  Normally, this auxiliary program
is xloadimage.  You can change this and use another program by changing
the resource:

    Xgopher.imageCommand: xloadimage

to use some other command.  If you have a program called "xv", another
image display program, installed, that is a good alternative.



Telnet and tn3270 sessions
--------------------------

Xgopher provides a telnet or tn3270 session by invoking another command
which must be already installed or available on your system (on the same
host as is running the Xgopher program).  Normally, two additional
programs are required: xterm and telnet (or xterm and tn3270).  xterm
provides a new terminal emulator window with vt100 (or ansi) terminal
behavior.  Telnet or tn3270 are simply run as programs in that window.
You can change this and use another program by changing the resources:

    Xgopher.telnetCommand: xterm -e telnet
    Xgopher.tn3270Command: xterm -e tn3270

to use some other command.  If you are using an IBM Risc System/6000, then
you really should use aixterm to run tn3270 as xterm and tn3270 do not
coexist very well with the default keyboard mappings.  For IBM RS/6000:

    Xgopher.tn3270Command: aixterm -e tn3270

If you have another telnet-capable program installed on your system,
you may change these commands to use your own program.  One alternative
for tn3270 sessions is a program called X3270.  If provides at least
a better visual emulation of an IBM 3278 terminal than does tn3270
in an xterm window.



Better Scrollbars
-----------------

There is a modified scrollbar available for the Athena widget library
that gives much better scrollbars than the standard Athena widget library
does.  This improved scrollbar has arrow heads at each end of the bar
that you can click to scroll up or down in addition to other scrollbar
dragging actions for scrolling.  It is amazing how much these arrows add
to the user interface.

This scrollbar widget was developed by Mitch Trachtenberg, bases on
the Athena scrollbar widget and should be "plug compatible".
However, it is not easy for me to support this widget directly in
Xgopher.  The reason is that many computer systems have their
Athena widget library generated as a shared object, or otherwise
have the library already internally linked.  So, even if I provide
the new scrollbar source file, and load it, the other Athena widgets
(text and viewport) are already closely tied to the supplied scrollbar
and will not use the new one.  The only sure way to use this new
scrollbar is to re-build your Athena widget library using the 2 new
files supplied by Mitch Trachtenberg.  It is okay to just re-archive
your old ".o" files for Xaw.

I cannot support the use of this package, but I have tested it with
Xgopher on an IBM RS/6000, and really appreciated the appearance and
behavior.  For those installers who feel like building a new Athena
widget library, I recommend this scrollbar.

The shar file is available by anonymous ftp from:

    export.lcs.mit.edu: contrib/Xaw.Scrollbar.mta



Other Athena-Compatible Widgets
-------------------------------

There is a 3-D version of the Athena widget library from
[e-mail], also available on the X11 ftp site:

    export.lcs.mit.edu: contrib/Xaw-0.5.tar.Z

(That's the version current as of this writing at the end of 1992.)

It is "plug-compatible" with the standard Athena widget library.
You can obtain this 3D version, compile it, (possibly install it,) and
link Xgopher with this library instead of your system Xaw library.

I cannot support the use of this package, but I have tested it with
Xgopher on an IBM RS/6000.  Especially when using color, there is some
interesting visual effect, but I don't consider the added value
significant enough to recommend using the 3D library.  Much of the
problem stems from the fact that the Athena widgets are not beautiful.
They were intended by the X consortium to be an example widget set, not
necessarily a production one, and it shows (in any number of dimensions).


There is also supposed to be a "vi" (editor) compatible version of the
Athena text widget available.  I have not tested this widget.  I do not
particularly recommend its use with Xgopher because  Xgopher
is primarily a text display system rather than a text editing system.
So the most you can gain is some familiar way to navigate a displayed
text file.  However, you accomplish much of this by setting the
key translations in the resource file for the existing text widget.
The same installation considerations discussed above for the scrollbar
replacement will be applicable to this replacement text widget.
Here is the introductory paragraph from its distribution:

    This is a modified version of the X11R5 Text Widget.  It is designed
    to drop into the X11R5 source tree and replace the original X11R5
    Text Widget.  It will behave identically to the original, unless
    the resource startMode is set to "vi", in which case it will give
    you vi-like modal editing.  By Eric Bina.

    On export.lcs.mit.edu (00-index.txt):
      -rw-rw-rw-  1 ftp         95091 Oct 22  1991 ViText.tar.Z