source: trunk/athena/bin/dash/dash.1 @ 12284

Revision 12284, 19.2 KB checked in by ghudson, 25 years ago (diff)
Move dash sources here from src/dash and autoconfiscate.
Line 
1.\" This file uses -man macros.
2.TH DASH 1 "December 14, 1994"
3.SH NAME
4dash \- Athena Dashboard
5.SH SYNOPSIS
6.TP 5
7.BR dash
8[-toolkitoption ...] [-menus \fIfile\fR] [-appdefs \fIfile\fR]
9.br
10[-userdefs \fIfile\fR] [\(+-rude] [\(+-verify] [-kill] [-restart]
11.br
12[-run] [-nofork] [-send] [-show \fIoption\fR ... ]
13.br
14[-hide \fIoption\fR ... ] [\(+-options\fR ...]
15
16.SH DESCRIPTION
17By default, \fIdash\fR places a menu bar at the top of the screen which
18contains much useful information on using Athena. Some of the items in
19the menu are merely informational - clicking on the items themselves
20will do nothing, while clicking on the `?' next to them will offer
21information. These items are followed by ellipsis (...) in their name.
22Other items will do things when you click on them, such as "New xterm window"
23under the special menu. These items also offer information if you click
24on their `?'s. Still other items are submenus. They have an arrow next
25to them where other items have `?'s, and clicking on the arrow will
26show more items. New Athena users should find this program massively
27useful for finding things, while more experienced Athena users may still
28like the program because of its customizability.
29.PP
30More generally, \fIdash\fR puts up user-defined widgets on the display
31screen which place much less of a load on the system than their X
32Toolkit or Motif counterparts.
33.I Dash
34can create menus, analog and digital clocks, buttons, icons, and other
35widgets which will be added in the future. Replacing other screen
36accessory programs with \fIdash\fR widgets can significantly increase
37system performance, especially on older systems with less real memory.
38.PP
39.I Dash's
40menu widget is of special note.  It allows the user to specify a list of
41desired menu items and their general desired locations, and will
42assemble a menu hierarchy from this description, rather than requiring
43the user to specify a complex hierarchy.  See the MENU FORMAT section
44below for details and an example on specifying menu widgets.
45
46.SH TOOLKIT OPTIONS
47.I Dash
48accepts many of the standard X Toolkit command line options:
49.TP
50.B\(+-reverse
51.br
52.ns
53.HP 9
54.B\(+-rv
55.br
56This option causes
57.I dash
58to come up in reverse video if you specify -rv, normal video if you
59specify +rv (the default).
60.TP
61.B \-background \fIcolor
62.br
63.ns
64.HP 9
65.B \-bg \fIcolor
66.br
67This option specifies the default background color for all
68.I dash
69widgets.
70.TP
71.B \-bordercolor \fIcolor
72.br
73.ns
74.HP 9
75.B \-bd \fIcolor
76.br
77This option specifies the default border color for all
78.I dash
79widgets.
80.TP
81.B \-borderwidth \fInumber
82.br
83.ns
84.HP 9
85.B \-bw \fInumber
86.br
87This option specifies the border width for all
88.I dash
89widgets in pixels.
90.HP 9
91.B \-display \fIdisplay
92.br
93This option specifies which display
94.I dash
95is to run on.  The default is to use the DISPLAY environment variable.
96.TP 9
97.B \-foreground \fIcolor
98.br
99.ns
100.HP 9
101.B \-fg \fIcolor
102.br
103This option specifies the default foreground color for all
104.I dash
105widgets.
106.TP
107.B \-font \fIfontname
108.br
109.ns
110.HP 9
111.B \-fn \fIfontname
112.br
113This option specifies the default font for labels on
114.I dash
115menus and buttons.
116.HP 9
117.B  \-name \fIstring
118.br
119This option specifies the application name under which resources are to
120be obtained, rather than the default executable file name.
121.I  String
122should not contain ``.'' or ``*'' characters.
123.HP 9
124.B \-xrm \fIresourcestring
125.br
126This option specifies a resource string to be used.  This is especially
127useful for setting resources that do not have separate command line
128options.  See \fIX\fR(1).
129.SH DASH OPTIONS
130\fIDash\fR accepts the following additional options:
131.TP 9
132.B \-appdefs \fIfile
133This option specifies a file to use for the application default
134resources instead of the default /usr/athena/lib/X11/app-defaults/Dash.
135.TP 9
136.B \-userdefs \fIfile
137This option specifies a file to use for the user default resources
138instead of the default ~/.dashrc.
139.TP 9
140.B \-menus \fImenufile
141This option causes
142.I dash
143to read menu entries from
144.I menufile
145instead of the default menus file listed in the "*Menu.file" resource.
146If more specific menu file resources are specifed, they will not be
147overriden by this option.
148.TP 9
149.B\(+-rude
150Specifies whether or not \fIdash\fR grabs the mouse pointer whenever one
151of its menus is opened.  \fI-rude\fR causes the pointer to be grabbed
152and is the default.  \fI+rude\fR leaves the pointer free while menus are
153open; this allows to you work in other windows without closing
154\fIdash\fR menus first.
155.TP 9
156.B\(+-verify
157Specifies whether or not \fIdash\fR attempts to verify all menu-selected
158actions (i.e. callbacks) by popping up a dialog box which asks the user
159to confirm or cancel the action.  \fI+verify\fR will cause \fIdash\fR to
160turn off verification for all menu item callbacks.  \fI-verify\fR will
161cause dash to verify any menu item callback. Menu items configured with
162the \fI-verify\fR field (see MENU FORMAT) are never verified regardless
163of this resource.  Note that \fI-verify\fR as a command line option
164turns verification on for all items, while \fI-verify\fR in a menu
165configuration will turn verification off for a specific item and
166override the command line option.  Yes, this is confusing, but Unix and
167toolkit conventions dictate the meaning of the + and - command line
168options.
169.PP
170.ne 2.5i
171By default, typing "dash" causes \fIdash\fR to start up showing a menu
172bar.  However, if there is already a \fIdash\fR running, it will tell
173that one to display a menu bar instead. The following options can be
174used to specify whether such messages are sent, or what messages should
175be sent.
176.TP 9
177.B \-nofork
178By default, dash will fork itself and detach from the terminal it was
179started it, so that it does not need to be backgrounded.  Using -nofork
180will cause dash to not fork and remain in the foreground.
181.TP 9
182.B \-kill
183This sends a signal to the currently running \fIdash\fR telling it to exit.
184.TP 9
185.B \-restart
186This is the same as -kill, except that after sending the kill it continues
187to run, and becomes the currently running \fIdash\fR. This is useful if
188you want \fIdash\fR to be running with resources you have just changed.
189.TP 9
190.B \-send
191\fIDash\fR usually checks to see of there is already a \fIdash\fR running.
192If so, it sends a signal. If not, it starts on its own. The -send option
193specifies that \fIdash\fR should only send signals. If there is no
194\fIdash\fR running, one should not be started.
195.TP 9
196.B \-run
197This option tells \fIdash\fR to ignore any other \fIdash\fR's that may
198already be running, and start up no matter what.
199.TP
200.B \-hide \fIoption\fR ...
201.br
202.ns
203.TP
204.B \-show \fIoption\fR ...
205.br
206.ns
207.HP 9
208.B\(+-\fIoption\fR ...
209.br
210These options are the reason that \fIdash\fR's signal sending ability
211exists. With them, you may tell an already running \fIdash\fR to hide
212or show objects that it is or isn't showing. This is good, because if
213\fIdash\fR were started as a logout button, and you wanted it also to
214be a menu bar, you might just start up a second invocation of
215\fIdash\fR, consuming more workstation memory. Instead, you can tell
216the \fIdash\fR that is already running to do display the menu bar, and
217save resources. For example, "dash -show clock" will send a signal to
218an already running \fIdash\fR to create a clock. If no dash is already
219running, it will start a new dash running the clock instead.
220Similarly, "dash -hide clock" will cause an already running dash to
221hide its clock, if one was showing.
222
223"dash -clock" is equivalent to "dash -show clock," while "dash +clock"
224is the same as "dash -hide clock." \fIOption\fR may be any of:
225default, user, athena, menubar, logout, clock. "default" is equivalent
226to "athena user," and "athena" is equivalent to "menubar." Invoking
227\fIdash\fR without any of these options is equivalent to invoking it
228with "-default" or "-show default".  Thus, if there is \fIdash\fR
229running as only a logout button, simply typing "dash" will cause it to
230display a menu bar as well.
231
232.SH "RESOURCES"
233.PP
234.I Dash
235understands many, although not all, of the core X Toolkit resources (see
236\fIX\fR(1)) and many additions which will be documented in the near
237future.  For now these resources which significantly affect \fIdash's\fR
238behavior are listed for reference:
239
240.TP 9
241.B overrideRedirect
242Specifies whether windows created by \fIdash\fR are created with
243override redirect set. Most window managers will not decorate or allow
244the user to drag around windows with this set. Override redirect is set
245by default on \fIdash\fR's menu bar, but not on any of the rest if its
246windows. If you wish to try it without this set, try specifying
247"*menuTree.window.overrideRedirect: False" in resources.
248
249.TP 9
250.B rude
251Specifies whether \fIdash\fR keeps the mouse grabbed when one of its
252menus is opened.  The default is "True".  Specfiying "dash*rude:False"
253will allow you for example to click away zephyrgrams while leaving a
254menu open.
255
256.TP 9
257.B verify
258Specifies whether menu item callbacks are executed with or without a
259popup verification window first.  Default is "True".  Menu items
260configured with the \fI-verify\fR field (see MENU FORMAT) are never
261verified regardless of this resource.
262
263.TP 9
264.B autoRaise
265Specifies whether a \fIdash\fR menu widget will automatically be brought
266to the front of the screen whenever the mouse enters it.  When "False",
267the user must click in the menubar in order to get it to raise itself.
268Default is "False".
269
270
271.SH DASH WIDGETS
272.PP
273The widgets which \fIdash\fR can create are still growing, and could use
274extensive documentation of their own in the future.  Especially
275important are the \fITree\fR widget and \fIForm\fR widget, which are
276used to create other widgets in and organized manner.  Until extensive
277documentation is available, an example of correct use of trees and forms
278can be found in /usr/athena/lib/X11/app-defaults/Dash, which creates a small
279tree of widgets and includes several which are commented out for
280reference.
281.PP
282The list of currently available widgets is: Tree, Form, Window,
283DigitalClock, AnalogClock, Menu, Icon, Button, Label, NULL.
284
285.SH "MENU FORMAT"
286.PP
287.I Dash
288has a unique menu format which allows one to create lists of menus and
289menu items and allow
290.I dash
291to assemble them in the appropriate hierarchy.  The same item can appear
292in more than one menu.  Items can have both help panels which provide
293information upon selection, and callbacks which perform actions upon
294selection.
295.PP
296The format of a menu file consists of entries each terminated with a ';'
297character, and each containing one or more of the following fields.
298Multiple entries and fields may exist for the same object -- subsequent
299definitions of individual fields will override previous ones.
300
301.TP 9
302.B menu \fIname:
303\fIName\fR will be created as a menu or submenu, and may have menus or
304items under it in the final menu hierarchy.  A \fImenu\fR entry should
305also have a \fIlabel\fR, a \fIparent\fR, and a \fIchild\fR defined (see
306below).
307.TP 9
308.B item \fIname:
309\fIName\fR will be created as an item which goes onto one or more menus,
310and may have help associated with it. An \fIitem\fR entry should also
311have a \fIlabel\fR and a \fIparent\fR defined.
312
313.TP 9
314.B help \fIname:
315If \fIitem name\fR exists, a help entry for it will be created which
316will appear next to \fIname\fR on any menus on the screen.  If the help
317entry rather than the item is selected, the helptext (see below) will
318appear in a window next to the menu on the screen.
319
320.TP 9
321.B "\fIlabel\fR"
322Used with a \fImenu\fR or \fIitem\fR (see above) entry, specifies what
323label the menu or item will be given on the screen.
324
325.TP 9
326.B  "\fIhelptext\fR"
327Used with a \fIhelp\fR entry, specifies what help text will appear when
328the help entry is selected.
329
330.TP 9
331.B [\fIparent, parent ...\fR ][\fIparent ...\fR]
332Used with a \fImenu\fR or \fIitem\fR entry, specifies what menus are
333allowed to be parents of the entry in the hierarchy.  The entry will
334become a child of the first available parent specified in each set of
335brackets (see example below).  A [NULL] parent specifes that the entry
336should be at the top level of the menu hierarchy.  If no parents are
337specifed for the entry, it will not appear on the screen. A maximum of
338five to ten types of parents may be specified.
339
340.TP 9
341.B {\fIchildren, ...\fR}
342Used with a \fImenu\fR or \fIitem\fR entry, specifies what menus or
343items are  allowed to be children of the entry in the hierarchy.  If no
344entries have \fIparent\fR fields which match, the entry will not appear
345on the screen. A maximum of five types of children may be specified.
346
347.TP 9
348.B \fIcallback\fR(),...
349Used with an \fIitem\fR entry, specifies a callback or callbacks to be
350called when the entry is selected.  If no callbacks are specified,
351nothing will happen when the entry is selected.  See CALLBACKS below.
352
353.TP 9
354.B \-h
355Used with a \fImenu\fR entry, specifies that this menu is to be
356displayed horizontally on the screen.
357
358.TP 9
359.B \-v
360Used with a \fImenu\fR entry, specifies that this menu is to be
361displayed vertically on the screen.  This is the default.
362
363.TP 9
364.B\(+-verify
365Used with an \fIitem\fR entry, specifies whether this item should or
366should not try to verify its selection by popping up a dialog box on the
367screen, which is the default.
368
369.TP
370.B\(+-sgi
371.br
372.ns
373.TP
374.B\(+-sun4
375.br
376.ns
377.TP
378.B\(+-decmips
379.br
380.ns
381.TP
382.B\(+-rsaix
383.br
384.ns
385.TP
386.B\(+-rt
387.br
388.ns
389.HP 9
390.B\(+-vax
391.br
392Used with an \fIitem\fR entry, specifies that this item is or is not
393available specifically on specified workstation platforms.
394Default is + for all platforms.  If an \fIitem\fR is specified as
395not available for the platform on which \fIdash\fR is running, it will
396appear dimmed on the screen.
397
398.SH CALLBACKS
399.PP
400The following callbacks are available for binding to \fIitems\fR (see above).
401Arguments should be strings enclosed in double quotes.
402
403.TP 9
404.B createTree(\fItreename\fR)
405Creates a tree of widgets named \fItreename\fR.
406
407.TP 9
408.B createMapTree(\fItreename\fR)
409Creates a tree of widgets named \fItreename\fR if one does not already exist,
410or maps it if it does.
411
412.TP 9
413.B destroyTree(\fItreename\fR)
414Destroys the first tree with name \fItreename\fR created by
415\fIcreate(Map)Tree\fR that it finds.
416
417.TP 9
418.B quit()
419Causes \fIdash\fR to exit.
420
421.TP 9
422.B toggleHelp(\fIlabel\fR)
423Causes \fIdash\fR to toggle whether or not help entries are displayed,
424and to replace the label of the calling item with \fIlabel\fR.  Entries
425which use this callback must also specify \fI-verify\fR (see above).
426
427.TP 9
428.B toggleVerify(\fIlabel\fR)
429Causes \fIdash\fR to toggle whether or not callbacks for all items are
430verified with a popup dialog box, and to replace the label of the
431calling item with \fIlabel\fR.  Entries which use this callback must
432also specify \fI-verify\fR (see above).
433
434.TP 9
435.B logout()
436Causes \fIdash\fR to log the user out.
437
438.TP 9
439.B mapTree(\fItreename\fR)
440Causes the widget tree named \fItreename\fR created by \fIcreateTree\fR
441to be visible on the screen.
442
443.TP 9
444.B unmapTree(\fItreename\fR)
445Causes the widget tree named \fItreename\fR created by \fIcreateTree\fR
446to disappear from the screen.
447
448.TP 9
449.B printMenu()
450Causes \fIdash\fR to print out the current assembled menu hierarchy for
451the menu tree of which the calling entry is a member.  Entries which use
452this callback must also specify \fI-verify\fR (see above).
453
454.TP 9
455.B sh(\fIcommand\fR)
456Causes \fIdash\fR to fork and execute a Bourne shell with the command
457line \fIcommand\fR.  See \fIsh\fR(1).
458
459.TP 9
460.B exec(\fIcommand\fR)
461Causes \fIdash\fR to fork and execute \fIcommand\fR. In the string
462passed to exec, ~ will be interpreted from the HOME environment
463variable. %M will be expanded to one of vax, rt, decmips, rsaix, sun4,
464or sgi as appropriate (the return value of \fImachtype\fR in the Athena
465environment, compiled into \fIdash\fR directly). %S will be expanded to
466values such as pmax_ul4, sgi_52, etc. (the return value of AFS's \fIfs\fR
467sysname, or @sys value) as determined by the environment variable
468ATHENA_SYS. Finally, %B, when used as part of a full path
469specification (such as "/mit/lockername/%B/program") will expand to
470"arch/%S/bin" if that directory exists under /mit/lockername, or else
471fall back to "%Mbin". See \fIlockers\fR(7) and \fIadd\fR(1) for more
472details on this behavior.
473
474.TP 9
475.B cd(\fIdirectory\fR)
476Causes \fIdash\fR to make the working directory for the next \fIexec\fR
477callback \fIdirectory\fR. \fIDirectory\fR may contain %M.
478
479.TP 9
480.B attach(\fIfilesystem\fR)
481Causes \fIdash\fR to attach \fIfilesystem\fR.  See \fIattach\fR(1).
482
483.TP 9
484.B add(\fIfilesystem\fR)
485Causes \fIdash\fR to "add" \fIfilesystem\fR, which means that
486\fIfilesystem\fR is attached, and \fIfilesystem\fR/%B is added to the
487directory search path for the next \fIexec\fR callback.
488
489.TP 9
490.B setup(\fIfilesystem\fR)
491Causes \fIdash\fR to attach \fIfilesystem\fR and set the environment
492variable SUBJECT to \fIfilesystem\fR for the next \fIexec\fR call. To
493implement the equivalent of the \fIsetup\fR command with this, try using something like:
494
495setup("16.00"),exec("xterm -n Todor")
496
497.TP 9
498.B addMenus(\fIfilename\fR)
499Causes \fIdash\fR to open \fIfilename\fR and add its contents to the
500menu hierarchy of the calling item.  Entries which use this callback
501must also specify \fI-verify\fR (see above). \fIFilename\fR should have
502an entry specifying that the menu item responsible for loading it become
503-vax -rt -decmips, to prevent the user from trying to add it again.
504
505.TP 9
506.B restart(\fIcommand\fR)
507With no arguments, causes \fIdash\fR to reread its configuration and
508restart.  With an argument, causes \fIdash\fR to exit and exec
509\fIcommand\fR instead. \fIRestart\fR may contain %M.
510
511
512.SH EXAMPLES
513.PP
514The file /usr/athena/lib/X11/app-defaults/Dash provides perhaps the best known
515working examples of working \fIdash\fR configuration resources.  In
516particular, the basic structure of trees and forms, not documented here,
517can be gleaned by examining the beginning of the file.
518.PP
519The file /usr/athena/lib/Dash.menus contains an extensive listing good
520working menu format sample.  The following sample menu file demonstrates
521most of the features of the menu syntax as a user might wish to use to
522add to the Athena default:
523
524.br
525.br
526menu top: "top" {topthings} [NULL]   +h;
527.br
528menu toys: "toys"  [topthings/10] {toythings} ;
529.br
530menu work: "work" [topthings/10] {workthings} ;
531.br
532menu gnu: "GNU" [topthings/10] {gnuthings} ;
533.br
534item quit: "Quit" [topthings/15] quit() -verify ;
535.br
536item tetris: "tetris" [toythings] add("games"),exec("Tetris") ;
537.br
538item xchess: "chess" [toythings][gnuthings] add("gnu"),exec("xchess") ;
539.br
540item gdb: "debugger" [workthings][gnuthings] add("gnu"),exec("xterm -e gdb");
541.br
542item emacs: "emacs" [workthings,gnuthings] exec("emacs") -verify;
543.br
544help tetris:
545.br
546"You'd better not have any work to do
547.br
548if you're going to play this thing.";
549.br
550help tetris:
551"Ignore previous warning -- PLAY!";
552.br
553item xchess: -decmips;
554.br
555help quit:
556.br
557"Bye!";
558
559.SH "FILES"
560.PP
561/usr/athena/bin/dash                     dash
562.br
563/usr/athena/lib/X11/app-defaults/Dash    application defaults
564.br
565~/.dashrc                                user defaults
566.br
567/usr/athena/lib/Dash.menus               Athena default menus
568
569.SH SEE ALSO
570X(1), add(1), lockers(7), machtype(1), fs(1)
571
572.SH "BUGS"
573.PP
574Some things don't interpret ~, %M, %S, and %B that probably should.
575
576Quotes may not be passed in callback strings.
577
578Attempting to place menu bars other than at +0+0 causes the program to
579get confused when submenus try to go off the side of the screen.
580
581.SH AUTHORS
582Craig Fields, Paul Boutin, and Chris VanHaren,  MIT Project Athena
583.br
584Copyright (c) 1990,1991 Massachusetts Institute of Technology
Note: See TracBrowser for help on using the repository browser.