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:
yes/no box, menu box, input box,
message box, text box, info box,
checklist box, program box,
ftree and tree boxes.
OPTIONS
--clear
The screen will be cleared to the
screen attribute on exit.
--create-rc file
Since dialog supports run-time configuration,
this can be used to dump a sample configuration file to the file specified
by
file.
--title title
Specifies a
title
string to be displayed at the top of the dialog box.
--hline line
Specifies a
line
string to be displayed at the bottom of the dialog box.
--hfile file
Specifies a
file
to be displayed by pressing ? or F1.
Box Options
--yesno text height width [ yes | no ]
A yes/no dialog box of size
height
rows by
width
columns will be displayed. The string specified by
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
text
string may also contain the sub-string
"\n"
or newline characters
`\n'
to control line breaking explicitly. This dialog box is useful for
asking questions that require the user to answer either yes or no.
The dialog box has a Yes button and a No
button, in which the user can switch between by pressing the
TAB key.
A Yes button is selected by default unless no
is specified.
--msgbox text height width
A message box is very similar to a yes/no box.
The only difference between a
message
box and a
yes/no
box is that a
message
box has only a single
OK
button. You can use this dialog box to display any message you like.
After reading the message, the user can press the
ENTER
key so that
dialog
will exit and the calling shell script can continue its operation.
--infobox text height width
An info box is basically a message box.
However, in this case,
dialog
will exit immediately after displaying the message to the user. The
screen is not cleared when
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.
--inputbox text height width
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
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
stderr.
--textbox file height width
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
UP/DOWN, PGUP/PGDN
and HOME/END keys available on most keyboards.
If the lines are too long to be displayed in the box, the
LEFT/RIGHT
keys can be used to scroll the text region horizontally. For more
convenience, forward and backward searching functions are also provided.
--menu text height width menu-height [ tag item ] ...
As its name suggests, a
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
tag string and an item string. The
tag
gives the entry a name to distinguish it from the other entries in the
menu. The
item
is a short description of the option that the entry represents. The
user can move between the menu entries by pressing the
UP/DOWN
keys, the first letter of the
tag
as a hot-key, or the number keys
1-9. There are
menu-height
entries displayed in the menu at one time, but the menu will be
scrolled if there are more entries than that. When
dialog
exits, the
tag
of the chosen menu entry will be printed on
stderr.
--prgbox command height width
A program box lets you display output of command in
dialog box.
--checklist text height width list-height [ tag item status ] ...
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
status.
On exit, a list of the
tag
strings of those entries that are turned on will be printed on
stderr.
--ftree file FS text height width menu-height
ftree
box is a dialog box showing the tree described by the data from the file
file.
The data in the file should look like find(1) output. For the
find output, the field separator
FS
will be
'/'. If
height and
width are
positive numbers, they set the absolute size of the whole
ftree box. If
height and
width are negative numbers, the size of the
ftree
box will be
selected automatically.
menu-height
sets the height of the tree subwindow inside the
ftree
box and must be set.
text
is shown inside the
ftree
box above the tree subwindow and can contain newline characters
'\n'
to split lines. One can navigate in the tree by pressing
UP/DOWN or '+'/'-', PG_UP/PG_DOWN or 'b'/SPACE
and HOME/END or 'g'/'G'.
A leaf of the tree is selected by pressing
TAB or LEFT/RIGHT
the
OK
button and pressing
ENTER.
The selected leaf (to be more
exact, the full path to it from the root of the tree) is printed to
stderr.
If
Cancel
and then
ENTER
is pressed, nothing is printed to
stderr.
file
may contain data like find(1)
output, as well as like the output of find(1) with
-d
option. Some of the transient paths to the leaves of the tree may be
absent. Such data is corrected when fed from file.
--tree FS text height width menu-height [ item ] ...
tree
box is like
ftree
box with some exceptions. First, the data is not
entered from a file, but from the command line as
item item ...
Second, the data thus entered is not corrected in any way.
Thus, the data like the output of find(1) with
-d
option will look incorrectly.
RUN-TIME CONFIGURATION
1.
Create a sample configuration file by typing:
"dialog --create-rc <file>"
2.
At start,
dialog
determines the settings to use as follows:
a)
if environment variable
DIALOGRC
is set, its value determines the name of the configuration file.
b)
if the file in (a) can't be found, use the file
$HOME/.dialogrc
as the configuration file.
c)
if the file in (b) can't be found, use compiled in defaults.
3.
Edit the sample configuration file and copy it to some place that
dialog
can find, as stated in step 2 above.
ENVIRONMENT
DIALOGRC
Define this variable if you want to specify the name of the configuration file
to use.
FILES
$HOME/.dialogrc
default configuration file
DIAGNOSTICS
Exit status is 0 if
dialog is exited by pressing the Yes or OK
button, and 1 if the
No or Cancel
button is pressed. Otherwise, if errors occur inside
dialog
or
dialog
is exited by pressing the
ESC
key, the exit status is -1.
Text files containing
tab
characters may cause problems with
text
box.
Tab
characters in text files must first be expanded to spaces before being
displayed by text box.
Screen update is too slow.
The
ftree
and
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.
