TOOLCHEST(1X)TOOLCHEST(1X)NAMEtoolchest - utility menu program
SYNOPSIStoolchest [-horizontal | -vertical | -icon] [-decal | -nodecal]
[-hidetitle | -showtitle] [-title title] [menudescr1 [...menudescrn]]
DESCRIPTION
The toolchest program displays a list of buttons, each of which can
invoke a useful command or present a submenu of additional buttons. The
standard set of menu buttons in the IRIX Interactive Desktop toolchest is
Desktop, Selected, Find, System, and Help. Each menu provides lists of
useful commands for running top-level window management programs (in
conjunction with 4Dwm), desk utilities, search utilities, system
administration functions, or documentation-displaying programs.
Options
-horizontal
This option specifies that the toolchest should display the top
level horizontally, rather than vertically.
-vertical
This option specifies that the toolchest should display the top
level vertically. This is the default, but the option can be
used to override saved resources.
-icon This option specifies that only an icon should be displayed when
the toolchest is not in use, rather than displaying the top level
of the toolchest. This option provides for display of the top
level vertically only.
-decal This option specifies that the toolchest should display decals.
For a vertical toolchest, a decal is displayed on each top level
button that contains a menu. For a horizontal toolchest, one
decal is displayed to the left of the toolchest. For an icon
toolchest, no decals are ever displayed. This option is on by
default.
-nodecal
This option specifies that the toolchest should not display
decals.
-hidetitle
This option eliminates the title bar of the toolchest. This was
the default in earlier releases but with the availability of
desks, the titlebar is enabled by default and shows the name of
the current desk.
Page 1
TOOLCHEST(1X)TOOLCHEST(1X)-showtitle
This option shows the titlebar of the toolchest. This option is
on by default.
-title This option sets the title in the toolchest. If it is not set,
the name "Toolchest" is used.
Users can change which buttons and/or menus are displayed by the
toolchest program, as well as the command lines which will be launched by
button selections.
The toolchest program reads a description of its buttons and menus from a
menu description file when the program starts. The standard menu set is
described by the system toolchest file /usr/lib/X11/system.chestrc, but
users can customize their toolchest menu by providing either an auxiliary
toolchest file named .auxchestrc or a user-customized toolchest file
named .chestrc in their home directory. The system toolchest file
includes the auxiliary file, and thus adds its contents to the default
system menu, while the user-customized toolchest file overrides the
system toolchest file. It is suggested that the auxiliary toolchest file
be used for customization if possible, as future changes to the system
toolchest will then be incorporated automatically. If a user-customized
toolchest file is to be used, it is suggested that the system toolchest
file be copied to $HOME/.chestrc as a starting point and then the user
can modify the .chestrc file. See the comments below on the include and
sinclude keywords for a discussion of how to set up an include file.
In addition to including the auxiliary toolchest file, the system
toolchest file will also include all files ending with .chest in the
directory /usr/lib/X11/app-chests.
Remote toolchests launched via /usr/sbin/accessworkstation or from the
Toolchest>Desktop>AccessFiles>(As Another User/By Remote Login) use the
resource file /usr/lib/X11/remote.chestrc to show a limited number of
menu choices.
Invoking toolchest with no arguments causes the user or system menu
description file to be read. When one or more file names are specified
to toolchest, the menu set is completely described by the list of files.
Instead of files, directory names may also be specified, in which case
all files in that directory that end with .chest are included, in
alphabetical order. Specifying command line arguments is most useful in
designing the menu layout; once this has been done, the user can
concatenate the files named on the command line into a single file, name
it .auxchestrc and put it in their home directory.
The menu tree is always rooted at a menu named "ToolChest"; thus the Menu
ToolChest { ... } must be provided somewhere in the toolchest
description. For example, if a menu named "Tools" with menu items "Jot"
and "Gmemusage" needs to be added to the toolchest, the following should
go in .auxchestrc :
Page 2
TOOLCHEST(1X)TOOLCHEST(1X)
Menu Tools
{
no-label f.separator
"Jot" f.checkexec.sh.le "/usr/sbin/jot"
"Gmemusage" f.checkexec.sh.le "/usr/sbin/gmemusage"
}
Menu ToolChest
{
no-label f.separator
"Tools" f.menu Tools
}
Toolchest buttons and menus may be operated with either left or right
mouse buttons (mouse buttons 1 or 3).
The default shell to run the commands is determined in the same way as is
used by mwm and 4Dwm. If the environment $MWMSHELL is defined, toolchest
uses that. Otherwise, if the $SHELL is defined, it uses that.
Otherwise, it uses /bin/sh. In the interests of performance, however,
alternate "shell" versions of the execute commands are provided that
force the use of /bin/sh regardless of the shell specified through the
environment. Since /bin/sh is faster than some other shells, this can
speed up launching commands. These alternate forms, used in the system
toolchest, are described below, and are highly recommended unless you
have commands that are shell specific.
Resources
"Toolchest" is the resource class name for toolchest. "toolchest" is the
resource instance name for toolchest and takes precedence over
"Toolchest" when used to specify resources. However, for historical
reasons, when invoked at system startup (from the Xsession file),
toolchest is invoked with the -name ToolChest option. This causes it to
have an instance name of "ToolChest" instead of "toolchest".
The syntax for specifying the resources is
Toolchest*resource_id: value
where resource_id can be any of the following:
icon If this resource is true then only an icon should be displayed
when the toolchest is not in use, rather than displaying the top
level of the toolchest. This provides for display of the top
level vertically only.
horizontal
If this resource is true then the toolchest should display the
top level horizontally, rather than vertically. This resource
Page 3
TOOLCHEST(1X)TOOLCHEST(1X)
may be changed from the Windows customization panel windows.
showDecal
If this resource is true, then decals are shown on the toolchest.
Since this resource defaults to true, decals can be turned off by
setting it to false.
hideTitle
This option eliminates the title bar of the toolchest. This was
the default in earlier releases but with the availability of
desks, the titlebar is enabled by default and shows the name of
the current desk.
decalForeground
This resource specifies the foreground color of the decals.
audioFeedback
If set to TRUE, the toolchest gives audio cues when launching
applications. This resource is normally changed from the Desktop
customization panel desktop.
menuVisualType
This resource controls the visual in which the menus appear.
Possible values are "normal" specifying the normal planes,
"overlay" specifying overlay planes, and "popup" specifying the
popup planes. On hardware supporting only popup planes,
specifying "overlay" results in popup planes. If the requested
visual type is not supported by the hardware, a warning is issued
and a default type is used. The default is to use the popup
planes. Use of the popup planes avoids interfering with other
applications on the screen, but provides only three colors; the
bottom shadow color may be different than the color that would be
allocated in the normal planes. To have the full ability to
choose colors, set this resource to "normal".
menuVisualDepth
This resource controls the depth of the visual to be used for the
menus. The default is to choose an optimum value based on the
available hardware. If the hardware does not support the
requested depth for the requested menuVisualType, a warning is
issued and a default depth is chosen.
useTearOffs
Setting this resource to TRUE will enable Motif tear-off menus.
With tear-off menus, a dotted line is created at the top of each
pane. Clicking on the dotted line will tear off the menu pane,
and give it window manager borders. The pane will remain posted
until dismissed. If this option is used while the menus are in
the popup or overlay planes, the colors of the menu will change
whenever any other application uses the same planes. Thus if
this option is used, it is a good idea to put the menus in the
normal planes by setting menuVisualType to normal and
Page 4
TOOLCHEST(1X)TOOLCHEST(1X)
menuVisualDepth to 0.
Defaults for the above resources as well as for colors and geometry are
set up in a system wide defaults file. The file name /usr/lib/X11/app-
defaults/Toolchest represents the customary location for this file. The
actual location of the system-wide class resource file may depend on
certain environment variables. The toolchest should not be resized. Do
not set a size with geometry. The toolchest selects an optimal size
based on the font. To get a different sized toolchest, set the
Toolchest*fontList: to some other font in your resources. For example, a
smaller toolchest can be created with:
Toolchest*fontList: -adobe-helvetica-bold-r-normal--10-*
MENU DESCRIPTION FILE FORMAT
The format for the menu description file is a subset of that described
for the Motif Window Manager, mwm, with a few extensions. toolchest
recognizes the keyword menu and the operators f.menu, f.title, f.exec,
f.separator, and f.label. In addition, the new keywords remove, include,
and sinclude and the new operators f.checkexec, f.checkexpr, f.exec.sh,
f.checkexec.sh, f.checkexec.sh.le, and f.checkexpr.sh have been added.
mwm-compatible Operators
The menu keyword is followed by a menu name field, then by a set of curly
braces containing one or more menu description lines. Each such line has
a label field, an operator field, and may have a target field.
The f.title operator defines a title label to be placed in the menu.
The f.separator operator causes a horizontal line to be drawn below the
previous label.
The f.menu operator causes a subsidiary menu to be invoked when its label
is selected. The menu may also contain the keyword dynamic which is used
internally for several Desktop applications to dynamically update the
toolchest's contents. There is currently no publicly available method
for other applications to take advantage of this capability.
The f.label operator defines a label to be placed in the menu.
The f.exec operator defines a command to be executed behind a command
button. If f.exec is used, no validation on the executability will be
performed. If a more robust treatment at run-time is desired, refer to
the extension operators described below. It is also possible to improve
performance by using the shell versions of the exec operators, also
defined below. Prior to executing the command, toolchest will load the
environment defined in $HOME/.desktop-<hostname>/desktopenv. This file
can be modified by selecting Desktop>Cusomize>Utilities from the
Toolchest. Any commands that contain double or single quotes should be
protected from the shell by preceeding them with a backslash character.
Page 5
TOOLCHEST(1X)TOOLCHEST(1X)
For example, if you wish to execute the command
echo "Testing the toolchest"
then you would add an entry to the chest's resource file as follows:
"Test" f.exec "echo \"Testing the toolchest\""
Unlike in mwm, the same menu may be named twice. Subsequent references
to the menu add items to the menu. The primary purpose of declaring a
menu twice is to add items to a system menu in a private file. For
example, in the auxiliary toolchest file, a user could add a new pane to
the top level by adding items to the ToolChest menu.
Extension Keywords
Several new keywords have been added. The remove keyword removes a
button from the toolchest. It is most useful when the user wants to use
the system toolchest, but doesn't want all the entries in it. There are
two formats:
remove <name>
will remove all buttons with the given name <name>, while
remove <name> from <menu_name>
will remove the button <name> from the specified menu <menu_name>. The
latter form is recommended, as it doesn't risk removing the wrong button.
However, the former form is easier as it doesn't require figuring out the
menu name. For example, the Overview button can be removed from the main
menu either with
remove Overview from ToolChest
or with
remove Overview
If a button being removed is both preceded and followed by a separator,
one of the separators is also removed.
The include and sinclude keywords include a file or directory. They
differ only in that include reports an error if the file or directory is
not found while sinclude (for conditional include) is silent. Sinclude
is intended for shared toolchest files that can be individually
customized by optionally including other files.
If the parameter to include or sinclude is a directory, all files in the
directory that end with .chest are included in alphabetical order.
Parameters to include and sinclude may be prefaced with "~/", in which
case they are looked up in the user's home directory.
The include directives may not appear anywhere in the file; they may only
appear in places where a menu could be declared. In particular, they may
not appear within a menu declaration.
In order for an include file to have any effect, it must add to the
existing menu hierarchy. To do this, it must contain at least one
redeclaration of an already existing menu. Items in that declaration
will add to the existing menu. The declaration may also refer to new
Page 6
TOOLCHEST(1X)TOOLCHEST(1X)
menus, also included in the include file. For example, to add to the top
level toolchest, redeclare the menu "ToolChest" specifying the new
contents. These new contents will be added to the existing "ToolChest"
menu. For an sample include file see the sample .auxchestrc below.
Extension Operators
In addition to the mwm-compatible operators, a set of extension operators
are available.
The f.checkexec operator defines a command to be executed behind a
command button. When selected, it behaves exactly like f.exec above.
However, when the toolchest menus are being built, a validation check is
run. If the command (the first argument in the command string) begins
with a rooted path name (begins with "/"), then that path is checked for
the existence and executability of the file. If the file does not exist,
or if it is not executable, then this entry will be grayed out in the
toolchest. Thus, the toolchest user will not be able to pick a menu item
that will fail to execute. For example,
"Magnifier" f.checkexec "/usr/sbin/mag"
insures that /usr/sbin/mag is available to be run. If it has not been
installed, for instance, the "Magnifier" item will be grayed out.
The f.checkexpr operator defines a command to be executed behind a
command button. When selected, it behaves exactly like f.exec above.
However, when the toolchest menus are being built, a validation check is
run. The f.checkexpr operator takes two double-quote-delimited
expressions. The first expression is evaluated when the toolchest menus
are being built; if this shell command expression fails (returns a non-
zero status), then this entry will be grayed out in the toolchest. Since
an arbitrary shell expression may be provided for this evaluation, a
large degree of care may be exercised by the button programmer interested
in protecting users from environmental dependencies which may lie within
the actual command line itself. The second expression given to
f.checkexpr defines the command to be executed when its button is
selected, just as for f.checkexec and f.exec. For example, the command
"Flip Logo" f.checkexpr "test -x /usr/demos/bin/flip -a -r
/usr/demos/data/models/logo.bin" "/usr/demos/bin/flip
/usr/demos/data/models/logo.bin"
provides a test expression that insures the executability of the command
and the readability of the critical data file. If either of these files
has been deleted or lacks the required permissions, the "Flip Logo" item
will be grayed out.
For improved performance, the various forms of f.exec all have shell
versions of them, made by appending .sh to their names (i.e., f.exec.sh,
f.checkexec.sh, and f.checkexpr.sh). Use of these versions forces the
command to be run in /bin/sh instead of in $MWMSHELL or $SHELL. For
certain shells, /bin/sh is faster. It is highly recommended that these
Page 7
TOOLCHEST(1X)TOOLCHEST(1X)
shell forms be used (the system toolchest uses them). However, the older
forms are provided for compatibility with older versions of toolchest.
Note that if you wish to see the sparkle launch effect when you launch
from your menus, you need to add .le to the checkexec command. (i.e,
f.checkexec.sh.le).
Nested Menus
The name on a menu line can be referenced by a f.menu operator from
another menu description; this defines a cascading menu relationship.
Top level buttons displayed in the toolchest window are defined in the
"ToolChest" menu. Multiple references to the same menu are not
supported. Menu names should be unique. Consider the following
(partial) definition:
menu ToolChest
{
"System" f.menu system
no-label f.separator
"Windows" f.menu windows
no-label f.separator
"Tools" f.menu tools
no-label f.separator
"Demos" f.menu demos
}
menu tools
{
"Tools" f.title
"Shell" f.checkexec.sh.le "xterm"
no-label f.separator
"Showmap" f.checkexec.sh.le "/usr/sbin/showmap"
"Makemap" f.checkexec.sh "/usr/sbin/makemap"
"Clocks" f.menu clocks
}
menu clocks
{
"" f.title
"Square Clock" f.checkexec.sh.le "/usr/sbin/clock"
"Analog Clock" f.exec.sh "xclock"
"Round Clock" f.checkexec.sh.le "oclock -bg black -fg \"dark red\""
"Digital Clock" f.exec.sh "xclock -digital"
}
...
Note that the "clocks" menu is cascaded from the "tools" menu, and that
"tools" is cascaded from the "ToolChest" menu. So in this case the
toolchest has the following top level buttons:
Page 8
TOOLCHEST(1X)TOOLCHEST(1X)-----------
| System |
|---------|
| Windows |
|---------|
| Tools |
|---------|
| Demos |
-----------
and selecting the "Tools" button will pop up a menu that looks something
like this:
--------------
| Tools |
|============|
| Shell |
|------------|
| Showmap |
| Makemap |
| Clocks -> |
--------------
Sample .auxchestrc file
The following sample .auxchestrc file adds a menu of my favorite things
to the top level. This menu includes the program atlantis as well as a
games submenu.
menu ToolChest
{
"My Favorite Things" f.menu mystuff
}
menu mystuff
{
"dolphins" f.exec "/usr/demos/bin/atlantis"
"Test Program" f.exec "source ~/.variables;~/testprog"
"games" f.menu mygames
}
menu mygames
{
"flight simulator" f.exec /usr/demos/bin/flight
"arena" f.exec /usr/demos/bin/arena
}
Page 9
TOOLCHEST(1X)TOOLCHEST(1X)NOTE
When the desktop is configured off with /etc/chkconfig desktop off, an
alternate toolchest file called /usr/lib/X11/nodesktop.chestrc is used;
it contains fewer entries and functions.
For more information about the entire IRIX Interactive Desktop
environment, see the IID(1) man page.
FILES
/usr/lib/X11/system.chestrc
~/.chestrc
~/.auxchestrc
/usr/lib/X11/nodesktop.chestrc
/usr/lib/X11/app-chests/*.chest
/usr/lib/X11/app-defaults/Toolchest
/usr/lib/X11/remote.chestrc
SEE ALSOmwm(1X), 4Dwm(1X), desktop(1X), windows(1x), soundscheme(1), IID(1)
Page 10
