DASH(1) DASH(1)
August 8, 1991
NAME
dash - Athena Dashboard
SYNOPSIS
dash [-toolkitoption ...] [-menus file] [-appdefs file]
[-userdefs file] [_rude] [_verify] [-kill] [-restart]
[-run] [-nofork] [-send] [-show option ... ]
[-hide option ... ] [_options ...]
DESCRIPTION
By default, dash places a menu bar at the top of the screen which
contains much useful information on using Athena. Some of the items in
the menu are merely informational - clicking on the items themselves
will do nothing, while clicking on the `?' next to them will offer
information. These items are followed by ellipsis (...) in their name.
Other items will do things when you click on them, such as "New xterm
window" under the special menu. These items also offer information if
you click on their `?'s. Still other items are submenus. They have an
arrow next to them where other items have `?'s, and clicking on the
arrow will show more items. New Athena users should find this program
massively useful for finding things, while more experienced Athena
users may still like the program because of its customizability.
More generally, dash puts up user-defined widgets on the display
screen which place much less of a load on the system than their X
Toolkit or Motif counterparts. Dash can create menus, analog and
digital clocks, buttons, icons, and other widgets which will be added
in the future. Replacing other screen accessory programs with dash
widgets can significantly increase system performance, especially on
older systems with less real memory.
For example, dash can emulate the xlogout program on a vax in 220K of
memory space as opposed to 440K for the X Toolkit version of xlogout.
Much more significantly, dash can replace several screen accessories
at a fraction of the cost of running each separately, as each added
widget adds only a few kilobytes of memory to dash's running size.
Dash configured to put a clock and logout button on the screen will
use 222K on a vax, compared to the 760K required to run xclock and
xlogout together. On older workstations which often have only four
megabytes of memory, the difference in system response time is
immediately noticeable.
Dash's menu widget is of special note. It allows the user to specify
a list of desired menu items and their general desired locations, and
will assemble a menu hierarchy from this description, rather than
requiring the user to specify a complex hierarchy. See the MENU
FORMAT section below for details and an example on specifying menu
widgets.
- 1 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
TOOLKIT OPTIONS
Dash accepts many of the standard X Toolkit command line options:
_reverse
_rv
This option causes dash to come up in reverse video if you
specify -rv, normal video if you specify +rv (the default).
-background color
-bg color
This option specifies the default background color for all
dash widgets.
-bordercolor color
-bd color
This option specifies the default border color for all dash
widgets.
-borderwidth number
-bw number
This option specifies the border width for all dash widgets
in pixels.
-display display
This option specifies which display dash is to run on. The
default is to use the DISPLAY environment variable.
-foreground color
-fg color
This option specifies the default foreground color for all
dash widgets.
-font fontname
-fn fontname
This option specifies the default font for labels on dash
menus and buttons.
-name string
This option specifies the application name under which
resources are to be obtained, rather than the default
executable file name. String should not contain ``.'' or
``*'' characters.
-xrm resourcestring
This option specifies a resource string to be used. This is
especially useful for setting resources that do not have
separate command line options. See X(1).
DASH OPTIONS
Dash accepts the following additional options:
- 2 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
-appdefs file
This option specifies a file to use for the application
default resources instead of the default
/usr/athena/lib/X11/app-defaults/Dash.
-userdefs file
This option specifies a file to use for the user default
resources instead of the default ~/.dashrc.
-menus menufile
This option causes dash to read menu entries from menufile
instead of the default menus file listed in the "*Menu.file"
resource. If more specific menu file resources are specifed,
they will not be overriden by this option.
_rude Specifies whether or not dash grabs the mouse pointer
whenever one of its menus is opened. -rude causes the
pointer to be grabbed and is the default. +rude leaves the
pointer free while menus are open; this allows to you work in
other windows without closing dash menus first.
_verify Specifies whether or not dash attempts to verify all menu-
selected actions (i.e. callbacks) by popping up a dialog box
which asks the user to confirm or cancel the action. +verify
will cause dash to turn off verification for all menu item
callbacks. -verify will cause dash to verify any menu item
callback. Menu items configured with the -verify field (see
MENU FORMAT) are never verified regardless of this resource.
Note that -verify as a command line option turns verification
on for all items, while -verify in a menu configuration will
turn verification off for a specific item and override the
command line option. Yes, this is confusing, but Unix and
toolkit conventions dictate the meaning of the + and -
command line options.
By default, typing "dash" causes dash to start up showing a menu bar.
However, if there is already a dash running, it will tell that one to
display a menu bar instead. The following options can be used to
specify whether such messages are sent, or what messages should be
sent.
-nofork By default, dash will fork itself and detach from the
terminal it was started it, so that it does not need to be
backgrounded. Using -nofork will cause dash to not fork and
remain in the foreground.
-kill This sends a signal to the currently running dash telling it
to exit.
-restart This is the same as -kill, except that after sending the kill
it continues to run, and becomes the currently running dash.
- 3 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
This is useful if you want dash to be running with resources
you have just changed.
-send Dash usually checks to see of there is already a dash
running. If so, it sends a signal. If not, it starts on its
own. The -send option specifies that dash should only send
signals. If there is no dash running, one should not be
started.
-run This option tells dash to ignore any other dash's that may
already be running, and start up no matter what.
-hide option ...
-show option ...
_option ...
These options are the reason that dash's signal sending
ability exists. With them, you may tell an already running
dash to hide or show objects that it is or isn't showing.
This is good, because if dash were started as a logout
button, and you wanted it also to be a menu bar, you might
just start up a second invocation of dash, consuming more
workstation memory. Instead, you can tell the dash that is
already running to do display the menu bar, and save
resources. For example, "dash -show clock" will send a signal
to an already running dash to create a clock. If no dash is
already running, it will start a new dash running the clock
instead. Similarly, "dash -hide clock" will cause an already
running dash to hide its clock, if one was showing.
"dash -clock" is equivalent to "dash -show clock," while
"dash +clock" is the same as "dash -hide clock." Option may
be any of: default, user, athena, menubar, logout, clock.
"default" is equivalent to "athena user," and "athena" is
equivalent to "menubar." Invoking dash without any of these
options is equivalent to invoking it with "-default" or "-
show default". Thus, if there is dash running as only a
logout button, simply typing "dash" will cause it to display
a menu bar as well.
RESOURCES
Dash understands many, although not all, of the core X Toolkit
resources (see X(1)) and many additions which will be documented in
the near future. For now these resources which significantly affect
dash's behavior are listed for reference:
overrideRedirect
Specifies whether windows created by dash are created with
override redirect set. Most window managers will not decorate
or allow the user to drag around windows with this set.
- 4 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
Override redirect is set by default on dash's menu bar, but
not on any of the rest if its windows. If you wish to try it
without this set, try specifying
"*menuTree.window.overrideRedirect: False" in resources.
rude Specifies whether dash keeps the mouse grabbed when one of
its menus is opened. The default is "True". Specfiying
"dash*rude:False" will allow you for example to click away
zephyrgrams while leaving a menu open.
verify Specifies whether menu item callbacks are executed with or
without a popup verification window first. Default is
"True". Menu items configured with the -verify field (see
MENU FORMAT) are never verified regardless of this resource.
autoRaise
Specifies whether a dash menu widget will automatically be
brought to the front of the screen whenever the mouse enters
it. When "False", the user must click in the menubar in
order to get it to raise itself. Default is "False".
DASH WIDGETS
The widgets which dash can create are still growing, and could use
extensive documentation of their own in the future. Especially
important are the Tree widget and Form widget, which are used to
create other widgets in and organized manner. Until extensive
documentation is available, an example of correct use of trees and
forms can be found in /usr/athena/lib/X11/app-defaults/Dash, which
creates a small tree of widgets and includes several which are
commented out for reference.
The list of currently available widgets is: Tree, Form, Window,
DigitalClock, AnalogClock, Menu, Icon, Button, Label, NULL.
MENU FORMAT
Dash has a unique menu format which allows one to create lists of
menus and menu items and allow dash to assemble them in the
appropriate hierarchy. The same item can appear in more than one
menu. Items can have both help panels which provide information upon
selection, and callbacks which perform actions upon selection.
The format of a menu file consists of entries each terminated with a
';' character, and each containing one or more of the following
fields. Multiple entries and fields may exist for the same object --
subsequent definitions of individual fields will override previous
- 5 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
ones.
menu name:
Name will be created as a menu or submenu, and may have menus
or items under it in the final menu hierarchy. A menu entry
should also have a label, a parent, and a child defined (see
below).
item name:
Name will be created as an item which goes onto one or more
menus, and may have help associated with it. An item entry
should also have a label and a parent defined.
help name:
If item name exists, a help entry for it will be created
which will appear next to name on any menus on the screen.
If the help entry rather than the item is selected, the
helptext (see below) will appear in a window next to the menu
on the screen.
label Used with a menu or item (see above) entry, specifies what
label the menu or item will be given on the screen.
helptext Used with a help entry, specifies what help text will appear
when the help entry is selected.
[parent, parent ... ][parent ...]
Used with a menu or item entry, specifies what menus are
allowed to be parents of the entry in the hierarchy. The
entry will become a child of the first available parent
specified in each set of brackets (see example below). A
[NULL] parent specifes that the entry should be at the top
level of the menu hierarchy. If no parents are specifed for
the entry, it will not appear on the screen. A maximum of
five to ten types of parents may be specified.
{children, ...}
Used with a menu or item entry, specifies what menus or items
are allowed to be children of the entry in the hierarchy.
If no entries have parent fields which match, the entry will
not appear on the screen. A maximum of five types of children
may be specified.
- 6 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
callback(),...
Used with an item entry, specifies a callback or callbacks to
be called when the entry is selected. If no callbacks are
specified, nothing will happen when the entry is selected.
See CALLBACKS below.
-h Used with a menu entry, specifies that this menu is to be
displayed horizontally on the screen.
-v Used with a menu entry, specifies that this menu is to be
displayed vertically on the screen. This is the default.
_verify Used with an item entry, specifies whether this item should
or should not try to verify its selection by popping up a
dialog box on the screen, which is the default.
_decmips
_rt
_vax
_rsaix
Used with an item entry, specifies that this item is or is
not available specifically on decmips, rt, vax, or rsaix
workstation platforms. Default is + for all platforms. If
an item is specified as not available for the platform on
which dash is running, it will appear dimmed on the screen.
CALLBACKS
The following callbacks are available for binding to items (see
above). Arguments should be strings enclosed in double quotes.
createTree(treename)
Creates a tree of widgets named treename.
createMapTree(treename)
Creates a tree of widgets named treename if one does not
already exist, or maps it if it does.
destroyTree(treename)
Destroys the first tree with name treename created by
create(Map)Tree that it finds.
- 7 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
quit() Causes dash to exit.
toggleHelp(label)
Causes dash to toggle whether or not help entries are
displayed, and to replace the label of the calling item with
label. Entries which use this callback must also specify
-verify (see above).
toggleVerify(label)
Causes dash to toggle whether or not callbacks for all items
are verified with a popup dialog box, and to replace the
label of the calling item with label. Entries which use this
callback must also specify -verify (see above).
logout() Causes dash to log the user out.
mapTree(treename)
Causes the widget tree named treename created by createTree
to be visible on the screen.
unmapTree(treename)
Causes the widget tree named treename created by createTree
to disappear from the screen.
printMenu()
Causes dash to print out the current assembled menu hierarchy
for the menu tree of which the calling entry is a member.
Entries which use this callback must also specify -verify
(see above).
sh(command)
Causes dash to fork and execute a Bourne shell with the
command line command. See sh(1).
exec(command)
Causes dash to fork and execute command. In the string passed
to exec, ~ will be interpreted from the HOME environment
variable, and %M will be expanded to one of vax, rt, or
decmips, as appropriate.
cd(directory)
Causes dash to make the working directory for the next exec
- 8 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
callback directory. Directory may contain %M.
attach(filesystem)
Causes dash to attach filesystem. See attach(1).
add(filesystem)
Causes dash to "add" filesystem, which means that filesystem
is attached, and filesystem/%Mbin is added to the directory
search path for the next exec callback.
setup(filesystem)
Causes dash to attach filesystem and set the environment
variable SUBJECT to filesystem for the next exec call. To
implement the equivalent of the setup command with this, try
using something like:
setup("16.00"),exec("xterm -n Todor")
addMenus(filename)
Causes dash to open filename and add its contents to the menu
hierarchy of the calling item. Entries which use this
callback must also specify -verify (see above). Filename
should have an entry specifying that the menu item
responsible for loading it become -vax -rt -decmips, to
prevent the user from trying to add it again.
restart(command)
With no arguments, causes dash to reread its configuration
and restart. With an argument, causes dash to exit and exec
command instead. Restart may contain %M.
EXAMPLES
The file /usr/athena/lib/X11/app-defaults/Dash provides perhaps the
best known working examples of working dash configuration resources.
In particular, the basic structure of trees and forms, not documented
here, can be gleaned by examining the beginning of the file.
The file /usr/athena/lib/Dash.menus contains an extensive listing good
working menu format sample. The following sample menu file
demonstrates most of the features of the menu syntax as a user might
wish to use to add to the Athena default:
menu top: "top" {topthings} [NULL] +h;
menu toys: "toys" [topthings/10] {toythings} ;
- 9 - Formatted: April 18, 2024
DASH(1) DASH(1)
August 8, 1991
menu work: "work" [topthings/10] {workthings} ;
menu gnu: "GNU" [topthings/10] {gnuthings} ;
item quit: "Quit" [topthings/15] quit() -verify ;
item tetris: "tetris" [toythings] add("games"),exec("Tetris") ;
item xchess: "chess" [toythings][gnuthings] add("gnu"),exec("xchess")
;
item gdb: "debugger" [workthings][gnuthings] add("gnu"),exec("xterm -e
gdb");
item emacs: "emacs" [workthings,gnuthings] exec("emacs") -verify;
help tetris:
"You'd better not have any work to do
if you're going to play this thing.";
help tetris: "Ignore previous warning -- PLAY!";
item xchess: -decmips;
help quit:
"Bye!";
FILES
/usr/athena/bin/dash dash
/usr/athena/lib/X11/app-defaults/Dash application defaults
~/.dashrc user defaults
/usr/athena/lib/Dash.menus Athena default menus
SEE ALSO
X(1)
BUGS
Some things don't interpret "~" and "%M" that probably should.
Quotes may not be passed in callback strings.
Attempting to place menu bars other than at +0+0 causes the program to
get confused when submenus try to go off the side of the screen.
CUSTOMIZATION AND DOCUMENTATION
A detailed document on using and customizing the Athena Dashboard is
pending from Athena. It will explain the detailed subject of setting
up complicated widget hierarchies. It may also include documentation
of features that there was no time to include in this manual page.
AUTHORS
Craig Fields, Paul Boutin, and Chris VanHaren, MIT Project Athena
Copyright (c) 1990,1991 Massachusetts Institute of Technology
- 10 - Formatted: April 18, 2024
