314 lines
8.6 KiB
Groff
314 lines
8.6 KiB
Groff
.TH DIALOG 1 "2 October 1998"
|
|
.SH NAME
|
|
dialog \- display dialog boxes from shell scripts
|
|
.SH SYNOPSIS
|
|
.B dialog --clear
|
|
.br
|
|
.BI "dialog --create-rc " file
|
|
.br
|
|
.B dialog
|
|
[
|
|
.BI "\-\-title " title
|
|
]
|
|
[
|
|
.B \-\-clear
|
|
]
|
|
[
|
|
.BI "\-\-hline " line
|
|
]
|
|
[
|
|
.BI "\-\-hfile " file
|
|
]
|
|
.B box-options
|
|
.SH DESCRIPTION
|
|
.B Dialog
|
|
is a program which allows you to present a variety of questions or
|
|
display messages in dialog box form from a shell script. The following
|
|
types of dialog objects are currently supported:
|
|
.LP
|
|
.BR yes/no " box," " menu" " box," " input" " box,"
|
|
.BR message " box," " text" " box," " info" " box,"
|
|
.BR checklist " box," " program" " box,"
|
|
.BR ftree " and " tree " boxes."
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-\-clear
|
|
The screen will be cleared to the
|
|
.BR "screen attribute" " on exit."
|
|
.TP
|
|
.BI \-\-create-rc " file"
|
|
.RB "Since " dialog " supports run-time configuration,"
|
|
this can be used to dump a sample configuration file to the file specified
|
|
by
|
|
.IR file "."
|
|
.TP
|
|
.BI \-\-title " title"
|
|
Specifies a
|
|
.I title
|
|
string to be displayed at the top of the dialog box.
|
|
.TP
|
|
.BI \-\-hline " line"
|
|
Specifies a
|
|
.I line
|
|
string to be displayed at the bottom of the dialog box.
|
|
.TP
|
|
.BI \-\-hfile " file"
|
|
Specifies a
|
|
.I file
|
|
to be displayed by pressing ? or F1.
|
|
.TP
|
|
.B Box Options
|
|
.TP
|
|
.BI \-\-yesno " text height width"
|
|
.RB A " yes/no" " dialog box of size"
|
|
.I height
|
|
rows by
|
|
.I width
|
|
columns will be displayed. The string specified by
|
|
.I text
|
|
is displayed inside the dialog box. If this string is too long to fit
|
|
in one line, it will be automatically divided into multiple lines at
|
|
the appropriate points. The
|
|
.I text
|
|
string may also contain the sub-string
|
|
.I
|
|
"\en"
|
|
or newline characters
|
|
.I `\en\'
|
|
to control line breaking explicitly. This dialog box is useful for
|
|
asking questions that require the user to answer either yes or no.
|
|
.RB "The dialog box has a" " Yes" " button and a " No
|
|
button, in which the user can switch between by pressing the
|
|
.IR TAB " key."
|
|
.TP
|
|
.BI \-\-msgbox " text height width"
|
|
.RB A " message" " box is very similar to a" " yes/no" " box."
|
|
The only difference between a
|
|
.B message
|
|
box and a
|
|
.B yes/no
|
|
box is that a
|
|
.B message
|
|
box has only a single
|
|
.B OK
|
|
button. You can use this dialog box to display any message you like.
|
|
After reading the message, the user can press the
|
|
.I ENTER
|
|
key so that
|
|
.B dialog
|
|
will exit and the calling shell script can continue its operation.
|
|
.TP
|
|
.BI \-\-infobox " text height width"
|
|
.RB An " info" " box is basically a" " message" " box."
|
|
However, in this case,
|
|
.B dialog
|
|
will exit immediately after displaying the message to the user. The
|
|
screen is not cleared when
|
|
.B dialog
|
|
exits, so that the message will remain on the screen until the calling
|
|
shell script clears it later. This is useful when you want to inform
|
|
the user that some operations are carrying on that may require some
|
|
time to finish.
|
|
.TP
|
|
.BI \-\-inputbox " text height width"
|
|
.RB "An " input " box is useful when you want to ask questions that"
|
|
require the user to input a string as the answer. When inputing the
|
|
string, the
|
|
.I BACKSPACE
|
|
key can be used to correct typing errors. If the input string is longer than
|
|
can be fitted in the dialog box, the input field will be scrolled. On exit,
|
|
the input string will be printed on
|
|
.IR stderr "."
|
|
.TP
|
|
.BI \-\-textbox " file height width"
|
|
.RB A " text" " box lets you display the contents of a text file in a"
|
|
dialog box. It is like a simple text file viewer. The user can move
|
|
through the file by using the
|
|
.IR UP/DOWN ", " PGUP/PGDN
|
|
.RI and " HOME/END" " keys available on most keyboards."
|
|
If the lines are too long to be displayed in the box, the
|
|
.I LEFT/RIGHT
|
|
keys can be used to scroll the text region horizontally. For more
|
|
convenience, forward and backward searching functions are also provided.
|
|
.IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
|
|
As its name suggests, a
|
|
.B menu
|
|
box is a dialog box that can be used to present a list of choices in
|
|
the form of a menu for the user to choose. Each menu entry consists of a
|
|
.IR tag " string and an " item " string. The"
|
|
.I tag
|
|
gives the entry a name to distinguish it from the other entries in the
|
|
menu. The
|
|
.I item
|
|
is a short description of the option that the entry represents. The
|
|
user can move between the menu entries by pressing the
|
|
.I UP/DOWN
|
|
keys, the first letter of the
|
|
.I tag
|
|
as a hot-key, or the number keys
|
|
.IR 1-9 ". There are"
|
|
.I menu-height
|
|
entries displayed in the menu at one time, but the menu will be
|
|
scrolled if there are more entries than that. When
|
|
.B dialog
|
|
exits, the
|
|
.I tag
|
|
of the chosen menu entry will be printed on
|
|
.IR stderr "."
|
|
.TP
|
|
.BI \-\-prgbox " command height width"
|
|
.RB A " program" " box lets you display output of command in"
|
|
dialog box.
|
|
.IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
|
|
.RB "A " checklist " box is similar to a " menu " box in that there are"
|
|
multiple entries presented in the form of a menu. Instead of choosing
|
|
one entry among the entries, each entry can be turned on or off by the
|
|
user. The initial on/off state of each entry is specified by
|
|
.IR status "."
|
|
On exit, a list of the
|
|
.I tag
|
|
strings of those entries that are turned on will be printed on
|
|
.IR stderr "."
|
|
.IP "\fB\-\-ftree \fIfile FS text height width menu-height"
|
|
.B ftree
|
|
box is a dialog box showing the tree described by the data from the file
|
|
.IR file "."
|
|
The data in the file should look like find(1) output. For the
|
|
find output, the field separator
|
|
.I FS
|
|
will be
|
|
.IR \'/\' ". If"
|
|
.IR height " and"
|
|
.IR width " are"
|
|
positive numbers, they set the absolute size of the whole
|
|
.BR ftree " box. If"
|
|
.IR height " and"
|
|
.IR width " are negative numbers, the size of the"
|
|
.B ftree
|
|
box will be
|
|
selected automatically.
|
|
.I menu-height
|
|
sets the height of the tree subwindow inside the
|
|
.B ftree
|
|
box and must be set.
|
|
.I text
|
|
is shown inside the
|
|
.B ftree
|
|
box above the tree subwindow and can contain newline characters
|
|
.I '\en\'
|
|
to split lines. One can navigate in the tree by pressing
|
|
.IR UP/DOWN " or " \'+\'/\'-\' ", " PG_UP/PG_DOWN " or " \'b\'/SPACE
|
|
.RI "and " HOME/END " or " \'g\'/\'G\' "."
|
|
A leaf of the tree is selected by pressing
|
|
.IR TAB " or " LEFT/RIGHT
|
|
the
|
|
.B OK
|
|
button and pressing
|
|
.IR ENTER "."
|
|
The selected leaf (to be more
|
|
exact, the full path to it from the root of the tree) is printed to
|
|
.IR stderr "."
|
|
If
|
|
.B Cancel
|
|
and then
|
|
.I ENTER
|
|
is pressed, nothing is printed to
|
|
.IR stderr "."
|
|
.I file
|
|
may contain data like find(1)
|
|
output, as well as like the output of find(1) with
|
|
.I -d
|
|
option. Some of the transient paths to the leaves of the tree may be
|
|
absent. Such data is corrected when fed from file.
|
|
.IP "\fB\-\-tree \fIFS text height width menu-height \fR[ \fIitem \fR] \fI..."
|
|
.B tree
|
|
box is like
|
|
.B ftree
|
|
box with some exceptions. First, the data is not
|
|
entered from a file, but from the command line as
|
|
.I item item ...
|
|
Second, the data thus entered is not corrected in any way.
|
|
Thus, the data like the output of find(1) with
|
|
.I -d
|
|
option will look incorrectly.
|
|
.SH "RUN-TIME CONFIGURATION"
|
|
.TP 4
|
|
1.
|
|
Create a sample configuration file by typing:
|
|
.LP
|
|
.in +1i
|
|
"dialog --create-rc <file>"
|
|
.TP 4
|
|
2.
|
|
At start,
|
|
.B dialog
|
|
determines the settings to use as follows:
|
|
.RS
|
|
.TP 4
|
|
a)
|
|
if environment variable
|
|
.B DIALOGRC
|
|
is set, its value determines the name of the configuration file.
|
|
.TP 4
|
|
b)
|
|
if the file in (a) can't be found, use the file
|
|
.I $HOME/.dialogrc
|
|
as the configuration file.
|
|
.TP 4
|
|
c)
|
|
if the file in (b) can't be found, use compiled in defaults.
|
|
.RE
|
|
.TP 4
|
|
3.
|
|
Edit the sample configuration file and copy it to some place that
|
|
.B dialog
|
|
can find, as stated in step 2 above.
|
|
.SH ENVIRONMENT
|
|
.TP 15
|
|
.B DIALOGRC
|
|
Define this variable if you want to specify the name of the configuration file
|
|
to use.
|
|
.SH FILES
|
|
.TP 20
|
|
.I $HOME/.dialogrc
|
|
default configuration file
|
|
.SH DIAGNOSTICS
|
|
Exit status is 0 if
|
|
.BR dialog " is exited by pressing the " Yes " or " OK
|
|
button, and 1 if the
|
|
.BR No " or " Cancel
|
|
button is pressed. Otherwise, if errors occur inside
|
|
.B dialog
|
|
or
|
|
.B dialog
|
|
is exited by pressing the
|
|
.I ESC
|
|
key, the exit status is -1.
|
|
.SH SEE ALSO
|
|
dialog(3)
|
|
.SH BUGS
|
|
Text files containing
|
|
.I tab
|
|
characters may cause problems with
|
|
.B text
|
|
box.
|
|
.I Tab
|
|
characters in text files must first be expanded to spaces before being
|
|
.RB "displayed by " text " box."
|
|
.sp 1
|
|
Screen update is too slow.
|
|
.sp 1
|
|
The
|
|
.B ftree
|
|
and
|
|
.B tree
|
|
boxes do not allow the tree to be moved to the left or to
|
|
the right. Thus, if there are many levels of data, some of the leaves can be
|
|
rendered invisible. A standard display with 80 characters allows for 17
|
|
levels to be visible. Deeper levels are invisible. However, the navigation
|
|
in the tree and selection of leaves do work.
|
|
.SH AUTHOR
|
|
Savio Lam (lam836@cs.cuhk.hk)
|
|
.sp 1
|
|
Changes by Anatoly A. Orehovsky (tolik@mpeks.tomsk.su) (ftree and tree boxes)
|