dialog.1

This version of dialog, formerly known as cdialog is based on the Debian package for dialog 0.9a (se

.
.
.IP "\fB\-\-fselect \fIfilepath height width\fR"
The file-selection dialog displays a text-entry window in which you can type
a filename (or directory), and above that two windows with directory
names and filenames.
.IP
Here
\fBfilepath\fP
can be a filepath in which case the file and directory windows
will display the contents of the path and the text-entry window will contain
the preselected filename.
.IP
Use tab or arrow keys to move between the windows.
Within the directory or filename windows, use the up/down arrow keys
to scroll the current selection.
Use the space-bar to copy the current selection into the text-entry
window.
.IP
Typing any printable characters switches focus to the text-entry window,
entering that character as well as scrolling the directory and filename
windows to the closest match.
.IP
Use a carriage return or the "OK" button to accept the current value
in the text-entry window and exit.
.IP
On exit, the contents of the text-entry window are written to dialog's output.
.
.
.IP "\fB\-\-gauge \fItext height width [percent]\fR"
A
\fBgauge\fP
box displays a meter along the bottom of the box.
The meter indicates the percentage.
New percentages are read from
standard input, one integer per line.
The meter is updated
to reflect each new percentage.
If the standard input reads the string "XXX",
then subsequent lines up to another "XXX" are used for a new prompt.
The gauge exits when EOF is reached on the standard input.
.IP
The \fIpercent\fR value denotes the initial percentage shown in the meter.
If not specified, it is zero.
.IP
On exit, no text is written to dialog's output.
The widget accepts no input, so the exit status is always OK.
.
.
.IP "\fB\-\-infobox \fItext height width"
An \fBinfo\fP box is basically a \fBmessage\fP box.
However, in this case, \fBdialog\fP
will exit immediately after displaying the message to the user.
The screen is not cleared when \fBdialog\fP
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.
.IP
On exit, no text is written to dialog's output.
Only an "Ok" button is provided for input,
but an ESC exit status may be returned.
.
.
.IP "\fB\-\-inputbox \fItext height width [init]"
An
\fBinput\fP
box is useful when you want to ask questions that
require the user to input a string as the answer.
If init is supplied
it is used to initialize the input string.
When entering the string,
the \fIbackspace\fP, \fIdelete\fP and cursor keys
can be used to correct typing errors.
If the input string is longer than
can fit in the dialog box, the input field will be scrolled.
.IP
On exit, the input string will be printed on dialog's output.
.
.
.IP "\fB\-\-inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box.
There are only a few differences between them:
.RS
.TP 4
1.
The entries are not automatically centered but left adjusted.
.TP
2.
An extra button (called \fIRename\fP) is implied to rename
the current item when it is pressed.
.TP
3.
It is possible to rename the current entry by pressing the
\fIRename\fP
button.
Then dialog will write the following on dialog's output.
.IP
RENAMED <tag> <item>
.RE
.
.
.IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
As its name suggests, a
\fBmenu\fP
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.
Choices are displayed in the order given.
Each menu entry consists of a \fItag\fP string and an \fIitem\fP string.
The \fItag\fP
gives the entry a name to distinguish it from the other entries in the
menu.
The \fIitem\fP is a short description of the option that the entry represents.
The user can move between the menu entries by pressing the
cursor keys, the first letter of the \fItag\fP
as a hot-key, or the number keys
.IR 1-9 ". There are"
\fImenu-height\fP
entries displayed in the menu at one time, but the menu will be
scrolled if there are more entries than that.
.IP
On exit the \fItag\fP
of the chosen menu entry will be printed on dialog's output.
If the \fB\-\-help-button\fR option is given, the corresponding help
text will be printed if the user selects the help button.
.
.IP "\fB\-\-msgbox \fItext height width"
A \fBmessage\fP box is very similar to a \fByes/no\fP box.
The only difference between a \fBmessage\fP box and a \fByes/no\fP
box is that a \fBmessage\fP box has only a single \fBOK\fP button.
You can use this dialog box to display any message you like.
After reading the message, the user can press the \fIENTER\fP key so that
\fBdialog\fP will exit and the calling shell script can continue its operation.
.IP
On exit, no text is written to dialog's output.
Only an "Ok" button is provided for input,
but an ESC exit status may be returned.
.
.IP "\fB\-\-passwordbox \fItext height width [init]"
A \fBpassword\fP box is similar to an input box,
except that the text the user enters is not displayed.
This is useful when prompting for passwords or other
sensitive information.
Be aware that if anything is passed in "init", it
will be visible in the system's process table to casual snoopers.
Also, it
is very confusing to the user to provide them with a default password they
cannot see.
For these reasons, using "init" is highly discouraged.
See "\fB\-\-insecure\fP" if you do not care about your password.
.IP
On exit, the input string will be printed on dialog's output.
.
.
.IP "\fB\-\-radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
A
\fBradiolist\fP
box is similar to a
\fBmenu\fP
box.
The only difference is
that you can indicate which entry is currently selected, by setting its
.IR status " to " on "."
.IP
On exit, the name of the selected item is written to dialog's output.
.
.
.IP "\fB\-\-tailbox file height width"
Display text from a file in a dialog box, as in a "tail -f" command.
Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
A '0' resets the scrolling.
.IP
On exit, no text is written to dialog's output.
Only an "Ok" button is provided for input,
but an ESC exit status may be returned.
.
.
.IP "\fB\-\-tailboxbg file height width"
Display text from a file in a dialog box as a background task,
as in a "tail -f &" command.
Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
A '0' resets the scrolling.
.IP
Dialog treats the background task specially if there are other
widgets (\fB\-\-and-widget\fP) on the screen concurrently.
Until those widgets are closed (e.g., an "OK"),
dialog will perform all of the tailboxbg widgets in the same process,
polling for updates.
You may use a tab to traverse between the widgets on the screen,
and close them individually, e.g., by pressing \fIENTER\fP.
Once the non-tailboxbg widgets are closed, dialog forks a copy of itself
into the background, and prints its process id if the \fB\-\-no-kill\fP option
is given.
.IP
On exit, no text is written to dialog's output.
Only an "EXIT" button is provided for input,
but an ESC exit status may be returned.
.IP
NOTE:
Older versions of dialog forked immediately and attempted to
update the screen individually.
Besides being bad for performance,
it was unworkable.
Some older scripts may not work properly with the polled scheme.
.
.
.IP "\fB\-\-textbox file height width"
A
\fBtext\fP
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
cursor, \fIPGUP/PGDN\fR
and \fIHOME/END\fR keys available on most keyboards.
If the lines are too long to be displayed in the box,
the \fILEFT/RIGHT\fP
keys can be used to scroll the text region horizontally.
You may also use vi-style keys h, j, k, l in place of the cursor keys,
and B or N in place of the pageup/pagedown keys.
Scroll up/down using vi-style 'k' and 'j', or arrow-keys.
Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
A '0' resets the left/right scrolling.
For more convenience,
vi-style forward and backward searching functions are also provided.
.IP
On exit, no text is written to dialog's output.
Only an "EXIT" button is provided for input,
but an ESC exit status may be returned.
.
.
.IP "\fB\-\-timebox \fItext height [width hour minute second]"
A dialog is displayed which allows you to select hour, minute and second.
If the values for hour, minute or second are missing or negative,
the current date's corresponding values are used.
You can increment or decrement any of those using the
left-, up-, right- and down-arrows.
Use tab or backtab to move between windows.
.IP
On exit, the result is printed in the form hour:minute:second.
.
.
.IP "\fB\-\-yesno \fItext height width"
A \fByes/no\fP dialog box of
size \fIheight\fP rows by \fIwidth\fP columns will be displayed.
The string specified by
\fItext\fP
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
appropriate places.
The
\fItext\fP
string can also contain the sub-string
.I
"\en"
or newline characters
\fI`\en'\fP
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
\fBYes\fP
button and a
\fBNo\fP
button, in which the user can switch between by pressing the
.IR TAB " key."
.IP
On exit, no text is written to dialog's output.
In addition to the "Yes" and "No" exit codes (see DIAGNOSTICS)
an ESC exit status may be returned.
.
.\" ************************************************************************
.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,
\fBdialog\fP
determines the settings to use as follows:
.RS
.TP 4
a)
if environment variable
\fBDIALOGRC\fP
is set, its value determines the name of the configuration file.
.TP 4
b)
if the file in (a) is not found, use the file
\fI$HOME/.dialogrc\fP
as the configuration file.
.TP 4
c)
if the file in (b) is not found, try using the GLOBALRC file determined at
compile-time, i.e., \fI/etc/dialogrc\fP.
.TP 4
d)
if the file in (c) is not found, use compiled in defaults.
.RE
.TP 4
3.
Edit the sample configuration file and copy it to some place that
\fBdialog\fP
can find, as stated in step 2 above.
.
.\" ************************************************************************
.SH ENVIRONMENT
.TP 15
\fBDIALOGRC\fP
Define this variable if you want to specify the name of the configuration file
to use.
.TP 15
\fBDIALOG_CANCEL\fP
.TP 15
\fBDIALOG_ERROR\fP
.TP 15
\fBDIALOG_ESC\fP
.TP 15
\fBDIALOG_EXTRA\fP
.TP 15
\fBDIALOG_HELP\fP
.TP 15
\fBDIALOG_OK\fP
Define any of these variables to change the exit code on
Cancel (1),
error (-1),
ESC (255),
Extra (3),
Help (2),
or Ok (0).
Normally shell scripts cannot distinguish between -1 and 255.
.TP 15
\fBDIALOG_TTY\fP
Set this variable to "1" to provide compatibility with older versions
of dialog which assumed that if the script redirects the standard output,
that the "\fB\-\-stdout\fP" option was given.
.SH FILES
.TP 20
\fI$HOME/.dialogrc\fP
default configuration file
.SH EXAMPLES
The dialog sources contain several samples
of how to use the different box options and how they look.
Just take a look into the directory \fBsamples/\fP of the source.
.SH DIAGNOSTICS
Exit status is subject to being overridden by environment variables.
Normally they are:
.TP 5
0
if
.BR dialog " is exited by pressing the " Yes " or " OK
button.
.TP 5
1
if the
.BR No " or " Cancel
button is pressed.
.TP 5
2
if the
.BR Help
button is pressed.
.TP 5
3
if the
.BR Extra
button is pressed.
.TP 5
-1
if errors occur inside \fBdialog\fP
or \fBdialog\fP is exited by pressing the \fIESC\fP key.
.
.\" ************************************************************************
.SH BUGS
Perhaps.
.SH AUTHOR
Savio Lam ([e-mail]) - version 0.3, "dialog"
.LP
Stuart Herbert ([e-mail]) - patch for version 0.4
.LP
Pako ([e-mail]) - version 0.9a, "cdialog",
.LP
Thomas Dickey (updates for 0.9b)
.SH CONTRIBUTORS
Tobias C. Rittweiler ([e-mail])