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.
The screen will be cleared to the
screen attribute on exit.
Since dialog supports run-time configuration,
this can be used to dump a sample configuration file to the file specified
string to be displayed at the top of the dialog box.
string to be displayed at the bottom of the dialog box.
to be displayed by pressing ? or F1.
--yesno text height width [ yes | no ]
A yes/no dialog box of size
columns will be displayed. The string specified by
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
string may also contain the sub-string
or newline characters
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
A Yes button is selected by default unless no
--msgbox text height width
A message box is very similar to a yes/no box.
The only difference between a
box and a
box is that a
box has only a single
button. You can use this dialog box to display any message you like.
After reading the message, the user can press the
key so that
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,
will exit immediately after displaying the message to the user. The
screen is not cleared when
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
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
--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
and HOME/END keys available on most keyboards.
If the lines are too long to be displayed in the box, the
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
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
gives the entry a name to distinguish it from the other entries in the
is a short description of the option that the entry represents. The
user can move between the menu entries by pressing the
keys, the first letter of the
as a hot-key, or the number keys
1-9. There are
entries displayed in the menu at one time, but the menu will be
scrolled if there are more entries than that. When
of the chosen menu entry will be printed on
--prgbox command height width
A program box lets you display output of command in
--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
On exit, a list of the
strings of those entries that are turned on will be printed on
--ftree file FS text height width menu-height
box is a dialog box showing the tree described by the data from the file
The data in the file should look like find(1) output. For the
find output, the field separator
positive numbers, they set the absolute size of the whole
ftree box. If
width are negative numbers, the size of the
box will be
sets the height of the tree subwindow inside the
box and must be set.
is shown inside the
box above the tree subwindow and can contain newline characters
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
button and pressing
The selected leaf (to be more
exact, the full path to it from the root of the tree) is printed to
is pressed, nothing is printed to
may contain data like find(1)
output, as well as like the output of find(1) with
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 ] ...
box is like
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
option will look incorrectly.
Create a sample configuration file by typing:
"dialog --create-rc <file>"
determines the settings to use as follows:
if environment variable
is set, its value determines the name of the configuration file.
if the file in (a) can't be found, use the file
as the configuration file.
if the file in (b) can't be found, use compiled in defaults.
Edit the sample configuration file and copy it to some place that
can find, as stated in step 2 above.
Define this variable if you want to specify the name of the configuration file
default configuration file
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
is exited by pressing the
key, the exit status is -1.
Text files containing
characters may cause problems with
characters in text files must first be expanded to spaces before being
displayed by text box.
Screen update is too slow.
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.