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

Revision 15011, 19.3 KB checked in by ghudson, 24 years ago (diff)
Add linux.
RevLine 
[12284]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
[15011]378.B\(+-linux
379.br
380.ns
381.TP
[12284]382.B\(+-decmips
383.br
384.ns
385.TP
386.B\(+-rsaix
387.br
388.ns
389.TP
390.B\(+-rt
391.br
392.ns
393.HP 9
394.B\(+-vax
395.br
396Used with an \fIitem\fR entry, specifies that this item is or is not
397available specifically on specified workstation platforms.
398Default is + for all platforms.  If an \fIitem\fR is specified as
399not available for the platform on which \fIdash\fR is running, it will
400appear dimmed on the screen.
401
402.SH CALLBACKS
403.PP
404The following callbacks are available for binding to \fIitems\fR (see above).
405Arguments should be strings enclosed in double quotes.
406
407.TP 9
408.B createTree(\fItreename\fR)
409Creates a tree of widgets named \fItreename\fR.
410
411.TP 9
412.B createMapTree(\fItreename\fR)
413Creates a tree of widgets named \fItreename\fR if one does not already exist,
414or maps it if it does.
415
416.TP 9
417.B destroyTree(\fItreename\fR)
418Destroys the first tree with name \fItreename\fR created by
419\fIcreate(Map)Tree\fR that it finds.
420
421.TP 9
422.B quit()
423Causes \fIdash\fR to exit.
424
425.TP 9
426.B toggleHelp(\fIlabel\fR)
427Causes \fIdash\fR to toggle whether or not help entries are displayed,
428and to replace the label of the calling item with \fIlabel\fR.  Entries
429which use this callback must also specify \fI-verify\fR (see above).
430
431.TP 9
432.B toggleVerify(\fIlabel\fR)
433Causes \fIdash\fR to toggle whether or not callbacks for all items are
434verified with a popup dialog box, and to replace the label of the
435calling item with \fIlabel\fR.  Entries which use this callback must
436also specify \fI-verify\fR (see above).
437
438.TP 9
439.B logout()
440Causes \fIdash\fR to log the user out.
441
442.TP 9
443.B mapTree(\fItreename\fR)
444Causes the widget tree named \fItreename\fR created by \fIcreateTree\fR
445to be visible on the screen.
446
447.TP 9
448.B unmapTree(\fItreename\fR)
449Causes the widget tree named \fItreename\fR created by \fIcreateTree\fR
450to disappear from the screen.
451
452.TP 9
453.B printMenu()
454Causes \fIdash\fR to print out the current assembled menu hierarchy for
455the menu tree of which the calling entry is a member.  Entries which use
456this callback must also specify \fI-verify\fR (see above).
457
458.TP 9
459.B sh(\fIcommand\fR)
460Causes \fIdash\fR to fork and execute a Bourne shell with the command
461line \fIcommand\fR.  See \fIsh\fR(1).
462
463.TP 9
464.B exec(\fIcommand\fR)
465Causes \fIdash\fR to fork and execute \fIcommand\fR. In the string
466passed to exec, ~ will be interpreted from the HOME environment
467variable. %M will be expanded to one of vax, rt, decmips, rsaix, sun4,
468or sgi as appropriate (the return value of \fImachtype\fR in the Athena
469environment, compiled into \fIdash\fR directly). %S will be expanded to
470values such as pmax_ul4, sgi_52, etc. (the return value of AFS's \fIfs\fR
471sysname, or @sys value) as determined by the environment variable
472ATHENA_SYS. Finally, %B, when used as part of a full path
473specification (such as "/mit/lockername/%B/program") will expand to
474"arch/%S/bin" if that directory exists under /mit/lockername, or else
475fall back to "%Mbin". See \fIlockers\fR(7) and \fIadd\fR(1) for more
476details on this behavior.
477
478.TP 9
479.B cd(\fIdirectory\fR)
480Causes \fIdash\fR to make the working directory for the next \fIexec\fR
481callback \fIdirectory\fR. \fIDirectory\fR may contain %M.
482
483.TP 9
484.B attach(\fIfilesystem\fR)
485Causes \fIdash\fR to attach \fIfilesystem\fR.  See \fIattach\fR(1).
486
487.TP 9
488.B add(\fIfilesystem\fR)
489Causes \fIdash\fR to "add" \fIfilesystem\fR, which means that
490\fIfilesystem\fR is attached, and \fIfilesystem\fR/%B is added to the
491directory search path for the next \fIexec\fR callback.
492
493.TP 9
494.B setup(\fIfilesystem\fR)
495Causes \fIdash\fR to attach \fIfilesystem\fR and set the environment
496variable SUBJECT to \fIfilesystem\fR for the next \fIexec\fR call. To
497implement the equivalent of the \fIsetup\fR command with this, try using something like:
498
499setup("16.00"),exec("xterm -n Todor")
500
501.TP 9
502.B addMenus(\fIfilename\fR)
503Causes \fIdash\fR to open \fIfilename\fR and add its contents to the
504menu hierarchy of the calling item.  Entries which use this callback
505must also specify \fI-verify\fR (see above). \fIFilename\fR should have
506an entry specifying that the menu item responsible for loading it become
507-vax -rt -decmips, to prevent the user from trying to add it again.
508
509.TP 9
510.B restart(\fIcommand\fR)
511With no arguments, causes \fIdash\fR to reread its configuration and
512restart.  With an argument, causes \fIdash\fR to exit and exec
513\fIcommand\fR instead. \fIRestart\fR may contain %M.
514
515
516.SH EXAMPLES
517.PP
518The file /usr/athena/lib/X11/app-defaults/Dash provides perhaps the best known
519working examples of working \fIdash\fR configuration resources.  In
520particular, the basic structure of trees and forms, not documented here,
521can be gleaned by examining the beginning of the file.
522.PP
523The file /usr/athena/lib/Dash.menus contains an extensive listing good
524working menu format sample.  The following sample menu file demonstrates
525most of the features of the menu syntax as a user might wish to use to
526add to the Athena default:
527
528.br
529.br
530menu top: "top" {topthings} [NULL]   +h;
531.br
532menu toys: "toys"  [topthings/10] {toythings} ;
533.br
534menu work: "work" [topthings/10] {workthings} ;
535.br
536menu gnu: "GNU" [topthings/10] {gnuthings} ;
537.br
538item quit: "Quit" [topthings/15] quit() -verify ;
539.br
540item tetris: "tetris" [toythings] add("games"),exec("Tetris") ;
541.br
542item xchess: "chess" [toythings][gnuthings] add("gnu"),exec("xchess") ;
543.br
544item gdb: "debugger" [workthings][gnuthings] add("gnu"),exec("xterm -e gdb");
545.br
546item emacs: "emacs" [workthings,gnuthings] exec("emacs") -verify;
547.br
548help tetris:
549.br
550"You'd better not have any work to do
551.br
552if you're going to play this thing.";
553.br
554help tetris:
555"Ignore previous warning -- PLAY!";
556.br
557item xchess: -decmips;
558.br
559help quit:
560.br
561"Bye!";
562
563.SH "FILES"
564.PP
565/usr/athena/bin/dash                     dash
566.br
567/usr/athena/lib/X11/app-defaults/Dash    application defaults
568.br
569~/.dashrc                                user defaults
570.br
571/usr/athena/lib/Dash.menus               Athena default menus
572
573.SH SEE ALSO
574X(1), add(1), lockers(7), machtype(1), fs(1)
575
576.SH "BUGS"
577.PP
578Some things don't interpret ~, %M, %S, and %B that probably should.
579
580Quotes may not be passed in callback strings.
581
582Attempting to place menu bars other than at +0+0 causes the program to
583get confused when submenus try to go off the side of the screen.
584
585.SH AUTHORS
586Craig Fields, Paul Boutin, and Chris VanHaren,  MIT Project Athena
587.br
588Copyright (c) 1990,1991 Massachusetts Institute of Technology
Note: See TracBrowser for help on using the repository browser.