TOOLCHEST(1X) TOOLCHEST(1X) NAME toolchest - utility menu program SYNOPSIS toolchest [-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. -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 : 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 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 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. 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 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 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: ----------- | 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 } 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 ALSO mwm(1X), 4Dwm(1X), desktop(1X), windows(1x), soundscheme(1), IID(1) Page 10