This file describes additions by nbs-amrf!libes to Sun's suntools program
(version 1.2) that was distributed with 2.0.  



BRIEF DESCRIPTION

Menu selections are allowed from the keyboard.

Tools may be run setuid(0) by pressing the shift key down while the menus
are brought up.

The user may specify the primary menu name.

The user may specify the shape, and rasterop used by the root cursor.

The one incompatibility introduced is that the 9 numerical fields in the
.suntools files are now ignored.  However, these are of dubious value anyway
since they are incomplete, contradictory and their effect can be achieved by
using the -W tool arguments.



LONG DESCRIPTION

Unified key mechanism

Menu entries may be invoked from the keyboard, by creating a "key" menu
(using KEYS instead of MENU in the rootmenu).  To invoke a menu item off the
key menu, simply type the tag associated with the menu.  Keystrokes are
stored in a key stroke buffer until a key menu tag is matched or the mouse is
moved.  

For example, my root menu looks as follows:

"big shell   (b)"	/usr/bin/shelltool -Ww 80 -Wh 56 -Wp 506 0 -Wn -WL "big shell"
"console     (c)"	/usr/bin/shelltool -C -Ww 50 -Wh 12 -Wp 0 0 -Wn -WL "console" -Wt /usr/lib/fonts/fixedwidthfonts/sail.r.6
"debugger    (d)"	/usr/bin/dbxtool
"graphics    (g)"	/usr/bin/gfxtool
"rlogin"	MENU /usr2/libes/environ/rloginmenu
"fun and games"	MENU /usr2/libes/environ/toolmenu
"Coke Classic"	KEYS /usr2/libes/environ/keymenu

Note, that the key menu file is not displayed in the stack of menus, hence
the tag is simply a place-holder.  Since key associations are not displayed,
people typically include the same entries in other (visible) menus with the
key tags in parens (ala Macintosh).

My key menu is as follows:

b	/usr/bin/shelltool -Ww 80 -Wh 56 -Wp 502 0 -Wn -WL "big csh"
c	/usr/bin/shelltool -C -Ww 50 -Wh 12 -Wp 0 0 -Wn -WL "console" -Wt /usr/lib/fonts/fixedwidthfonts/sail.r.6
d	/usr/bin/dbxtool
s	/usr/bin/shelltool
"g"	/usr/bin/gfxtool
"r"	REFRESH
	EXIT_NOCONFIRM
"?"	HELP
=	VERSION
v	/usr/bin/shelltool -Wl "vex" -WL "" -WI /usr/local/icon/vax.icon
rlogin nbs-amrf
k	/usr/bin/shelltool -Wl "Kanamid at your service.  May I take your order?" -WL "" -WI /usr/local/icon/kanamid.icon rlogin kanamid

Notice that multiple keystroke tags are available.  They should be quoted if
containing blanks or other whitespace.  



New keywords

The menu above also demonstrates several other keywords that are available.

EXIT_NOCONFIRM is like EXIT, but it does not confirm that you want to exit.

HELP puts up a help box for suntools.

VERSION prints out the current version of suntools.



New environment variables

Several environment variables were added for more flexibility.

ROOTMENUNAME is a string that is used as the name of the primary menu.  As
distributed from Sun (and by default in this version), it is "Suntools".

ROOT_CURSOR is a cursor that is used as the root menu cursor.  Since this
cursor isn't used to point to anything, it seemed odd to use an arrow.  A
much more interesting cursor is the default in this version.  

ROOT_CURSOR_ROP is the rasterop function associated with the cursor.  This
should be an integer.  For example, the default raster-op in this version of
suntools is 28, which corresponds to or-ing the source and destination.  The
raster-op used in the original suntools was 24 (source).  For more
information, see <pixrect/pixrect.h>.  

ROOT_CURSOR_HOTSPOT_X sets the cursor hotspot in the x axis.
ROOT_CURSOR_HOTSPOT_Y sets the cursor hotspot in the y axis.  The default for
both of these is 8 - the middle of the cursor.  



Superuser shortcut

This feature is enabled for anyone who can supply the root password when
starting suntools, or everyone if there is no root password (as at our
installation, believe it or not).  

If there is a root password, and suntools is started with the -S flag, the
user is prompted for the root password.  If it is correct, the running
suntools will have the superuser shortcut enabled.  

When the shortcut is enabled, the user may invoke tools with setuid(0) by
pressing the shift key down before bringing up the menus (or typing a key to
the root window).  If the mouse is used to raise the menus, a little "su"
appears to the left of the menu.  

Besides being a tremendous convenience, this squeezes the tool and su
processes down into one.  We use it a lot as follows - while sitting at a
client, one key stroke brings up an su'd window on the server.  



.suntools files

While the tools understand how to interpret arguments based on the -Wxxxx
conventions, suntools provides another way of passing arguments in the
suntools startup file.  That is, there are several reserved fields available
for window position information and whether the window should be open or
closed in the suntools startup file.

The second method has two drawbacks.  First, it is incomplete.  Second, it
can contradict arguments from the first method.  Since I didn't want to waste
my time figuring out how to 1) convert the .suntools parameters into
tool-style parameters, 2) resolve contradictions between the two parameter
passing techniques and 3) I did not have the source, I decided to disallow
(actually ignore) the second method of passing arguments.

Thus if you provide information via the 9 numerical parameters, it will be
ignored.  You should use the -W style of tool parameter passing.  While this
means you may have to modify your .suntools file, the end result is much more
consistent.  (Although no less easy to read, since strings like -Wp are not
very intuitive either.)  

So for example, if you had a line in your .suntools file like:

shelltool 0 72 -1 728 -1 -1 -1 -1 emacs $HOME/sked -Wn

You should convert it to 

shelltool emacs $HOME/sked -Wp 0 72 -WP 4 4 -Wn
(or even better, use -Ww and -Wh since they do not depend on the font size.)



Please send comments, enhancements, bug reports and fixes to:

Don Libes
Met. Bldg, Rm B229
National Bureau of Standards
Gaithersburg, MD  20899
(301) 921-2461
seismo!nbs-amrf!libes
