*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> toolchest (1)              



NAME    [Toc]    [Back]

     toolchest - utility menu program

SYNOPSIS    [Toc]    [Back]

     toolchest [-horizontal | -vertical	| -icon] [-decal | -nodecal]
       [-hidetitle | -showtitle] [-title title]	[menudescr1 [...menudescrn]]

DESCRIPTION    [Toc]    [Back]

     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    [Toc]    [Back]
	     This option specifies that	the toolchest should display the top
	     level horizontally, rather	than vertically.

	     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

	     This option specifies that	the toolchest should not display

	     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


	     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


     Menu Tools
	 no-label    f.separator
	 "Jot"	     f.checkexec.sh.le "/usr/sbin/jot"
	 "Gmemusage" f.checkexec.sh.le "/usr/sbin/gmemusage"

     Menu ToolChest    [Toc]    [Back]

	  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    [Toc]    [Back]
     "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.

	     If	this resource is true then the toolchest should	display	the
	     top level horizontally, rather than vertically.  This resource

									Page 3


	     may be changed from the Windows customization panel windows.

	     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.

	     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.

	     This resource specifies the foreground color of the decals.

	     If	set to TRUE, the toolchest gives audio cues when launching
	     applications.  This resource is normally changed from the Desktop
	     customization panel desktop.

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

	     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.

	     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


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


     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


     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    [Toc]    [Back]
     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


     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    [Toc]    [Back]
     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	nonzero
 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

     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


     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,

   Nested Menus    [Toc]    [Back]
     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


	       | 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    [Toc]    [Back]
     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


     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    [Toc]    [Back]


SEE ALSO    [Toc]    [Back]

     mwm(1X), 4Dwm(1X),	desktop(1X), windows(1x), soundscheme(1), IID(1)

								       PPPPaaaaggggeeee 11110000
[ Back ]
 Similar pages
Name OS Title
scu Tru64 SCSI CAM Utility Program
undocumented Linux No manpage for this program, utility or function.
lmutil IRIX generic FLEXlm utility program.
sccs HP-UX front-end utility program for SCCS commands
pam-undocumented Linux No manpage for this PAM-related program, utility or function.
stl_scp Tru64 Subset control program conventions for the setld utility (*.scp)
VkOptionMenu IRIX An option menu for use with ViewKit menu items
espreport IRIX 0espreport is a utility provided for viewing various reports from ESP on the command line. This utility bypass
espconfig IRIX 0espconfig is a utility provided for the configuration ESP from the command line. This utility bypasses the we
setmemwindow HP-UX changes the window id of a running program or starts a program in a particular memory window
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service