dialog.1

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

.\" $Id: dialog.1,v 1.67 2003/11/26 22:40:34 tom Exp $
.TH DIALOG 1 "" "$Date: 2003/11/26 22:40:34 $"
.SH NAME
dialog \- display dialog boxes from shell scripts
.SH SYNOPSIS
\fBdialog \-\-clear\fP
.br
.BI "dialog \-\-create-rc " file
.br
\fBdialog \-\-print-maxsize\fP
.br
\fBdialog\fP
\fIcommon-options\fP
\fIbox-options\fP
.SH DESCRIPTION
\fBDialog\fP
is a program that will let you to present a variety of questions or
display messages using dialog boxes from a shell script.
These types of dialog boxes are implemented
(though not all are necessarily compiled into \fBdialog\fR):
.RS
.LP
.BR calendar ", "
.BR checklist ", "
.BR form ", "
.BR fselect ", "
.BR gauge ", "
.BR infobox ", "
.BR inputbox ", "
.BR inputmenu ", "
.BR menu ", "
.BR msgbox " (message), "
.BR password ", "
.BR radiolist ", "
.BR tailbox ", "
.BR tailboxbg ", "
.BR textbox ", "
.BR timebox ", and "
.BR yesno " (yes/no)."
.RE
.PP
You can put more than one dialog box into a script:
.TP 5
-
Use the \fB\-\-and-widget\fP token to force Dialog to proceed to the next
dialog unless you have pressed ESC to cancel, or
.TP 5
-
Simply add the tokens for the next dialog box, making a chain.
Dialog stops chaining when the return code from a dialog is nonzero,
e.g., Cancel or No (see DIAGNOSTICS).
.PP
Some widgets, e.g., checklist, will write text to dialog's output.
Normally that is the standard error, but there are options for
changing this: \fB\-\-output-fd\fP, \fB\-\-stderr\fP and \fB\-\-stdout\fP.
No text is written if the Cancel button (or ESC) is pressed;
dialog exits immediately in that case.
.
.\" ************************************************************************
.SH OPTIONS
All options begin with "\fB\-\-\fP".
A "\fB\-\-\fP" by itself is used as an escape,
i.e., the next token on the command-line is not treated as an option.
.
.SS \fBCommon Options\fP
.
.IP "\fB\-\-aspect \fIratio"
This gives you some control over the box dimensions when using auto
sizing (specifying 0 for height and width).
It represents width / height.
The default is 9, which means 9 characters wide to every 1 line high.
.
.IP "\fB\-\-backtitle \fIbacktitle"
Specifies a
\fIbacktitle\fP
string to be displayed on the backdrop, at the top of the screen.
.
.IP "\fB\-\-beep"
Sound the audible alarm
each time the screen is refreshed.
.
.IP "\fB\-\-beep-after"
Beep if input is interrupted, e.g., by a control/C.
.
.IP "\fB\-\-begin \fIy x"
Specify the position of the upper left corner of a dialog box on the screen.
.
.IP "\fB\-\-cancel-label \fIstring"
Override the label used for "Cancel" buttons.
.
.IP "\fB\-\-clear"
The screen will be cleared to the
\fBscreen attribute\fP
on exit.
This may be used alone, without other options.
.
.IP "\fB\-\-colors"
Interpret embedded "\\Z" sequences in the dialog text
by the following character,
which tells dialog to set colors or video attributes:
0 through 7 are the ANSI used in curses:
black,
red,
green,
yellow,
blue,
magenta,
cyan and
white respectively.
Bold is set by 'b', reset by 'B'.
Reverse is set by 'r', reset by 'R'.
Underline is set by 'u', reset by 'U'.
The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text
bright red.
Restore normal settings with "\\Zn".
.
.IP "\fB\-\-cr-wrap"
Interpret embedded newlines in the dialog text as a newline on the screen.
Otherwise, \fBdialog\fR will only wrap lines where needed to fit inside the text box.
Even though you can control line breaks with this,
\fBdialog\fR will still wrap any lines that are too long for the width of the box.
Without cr-wrap, the layout of your text may be formatted to look nice
in the source code of your script without affecting the way it will
look in the dialog.
.
.IP "\fB\-\-create-rc \fIfile"
When
\fBdialog\fP
supports run-time configuration,
this can be used to dump a sample configuration file to the file specified
by
.IR file "."
.
.IP "\fB\-\-defaultno"
Make the default value of the
\fByes/no\fP
box a
.BR No .
Likewise, make the default button of widgets that provide "OK" and "Cancel"
a \fBCancel\fP.
.
.IP "\fB\-\-default-item \fIstring"
Set the default item in a menu box.
Normally the first item in the box is the default.
.
.IP "\fB\-\-exit-label \fIstring"
Override the label used for "EXIT" buttons.
.
.IP "\fB\-\-extra-button"
Show an extra button, between "Ok" and "Cancel" buttons.
.
.IP "\fB\-\-extra-label \fIstring"
Override the label used for "Extra" buttons.
Note: for inputmenu widgets, this defaults to "Rename".
.
.IP "\fB\-\-help"
Prints the help message to dialog's output.
The help message is printed if no options are given.
.
.IP "\fB\-\-help-button"
Show a help-button after "Ok" and "Cancel" buttons,
i.e., in checklist, radiolist and menu boxes.
If \fB\-\-item-help\fR is also given, on exit
the return status will be the same as for the "Ok" button,
and the item-help text will be written to dialog's output after the token "HELP".
Otherwise, the return status will indicate that the Help button was pressed,
and no message printed.
.
.IP "\fB\-\-help-label \fIstring"
Override the label used for "Help" buttons.
.
.IP "\fB\-\-help-status"
If the help-button is selected,
writes the checklist or radiolist information
after the item-help "HELP" information.
This can be used to reconstruct the state of a checklist after processing
the help request.
.
.IP "\fB\-\-ignore"
Ignore options that \fBdialog\fP does not recognize.
Some well-known ones such as "\fB\-\-icon\fP" are ignored anyway,
but this is a better choice for compatibility with other implementations.
.
.IP "\fB\-\-input-fd \fIfd"
Read keyboard input from the given file descriptor.
Most \fBdialog\fR scripts read from the standard input,
but the gauge widget reads a pipe (which is always standard input).
Some configurations do not work properly when
\fBdialog\fP tries to reopen the terminal.
Use this option (with appropriate juggling of file-descriptors)
if your script must work in that type of environment.
.
.IP "\fB\-\-insecure"
Makes the password widget friendlier but less secure,
by echoing asterisks for each character.
.
.IP "\fB\-\-item-help"
Interpret the tags data for checklist, radiolist and menu boxes
adding a column which is displayed in the bottom line of the
screen, for the currently selected item.
.
.IP "\fB\-\-keep-window"
Do not remove/repaint the window on exit.
This is useful for keeping the window contents visible when several
widgets are run in the same process.
Note that curses will clear the screen when starting a new process.
.
.IP "\fB\-\-max-input \fIsize"
Limit input strings to the given size.
If not specified, the limit is 2000.
.
.IP "\fB\-\-no-cancel"
.IP "\fB\-\-nocancel"
Suppress the "Cancel" button in checklist, inputbox and menu box modes.
A script can still test if the user pressed the ESC key to cancel to quit.
.
.IP "\fB\-\-no-collapse"
Normally \fBdialog\fR converts tabs to spaces and reduces multiple
spaces to a single space for text which is displayed in a message boxes, etc.
Use this option to disable that feature.
Note that \fBdialog\fR will still wrap text, subject to the \fB\-\-cr\-wrap\fR
option.
.
.IP "\fB\-\-no-kill"
Tells
\fBdialog\fP
to put the
\fBtailboxbg\fP
box in the background,
printing its process id to dialog's output.
SIGHUP is disabled for the background process.
.
.IP "\fB\-\-no-label \fIstring"
Override the label used for "No" buttons.
.
.IP "\fB\-\-no-shadow"
Suppress shadows that would be drawn to the right and bottom of each dialog box.
.
.IP "\fB\-\-ok-label \fIstring"
Override the label used for "OK" buttons.
.
.IP "\fB\-\-output-fd \fIfd"
Direct output to the given file descriptor.
Most \fBdialog\fR scripts write to the standard error,
but error messages may also be written there, depending on your script.
.
.IP "\fB\-\-print-maxsize"
Print the maximum size of dialog boxes, i.e., the screen size,
to dialog's output.
This may be used alone, without other options.
.
.IP "\fB\-\-print-size"
Prints the size of each dialog box to dialog's output.
.
.IP "\fB\-\-print-version"
Prints \fBdialog\fR's version to dialog's output.
This may be used alone, without other options.
.
.IP "\fB\-\-separate-output"
For checklist widgets, output result one line at a time, with no quoting.
This facilitates parsing by another program.
.
.IP "\fB\-\-separator \fIstring"
.IP "\fB\-\-separate-widget \fIstring"
Specify a string that will separate the output on dialog's output from
each widget.
This is used to simplify parsing the result of a dialog with several widgets.
If this option is not given,
the default separator string is a tab character.
.
.IP "\fB\-\-shadow"
Draw a shadow to the right and bottom of each dialog box.
.
.IP "\fB\-\-size-err"
Check the resulting size of a dialog box before trying to use it,
printing the resulting size if it is larger than the screen.
(This option is obsolete, since all new-window calls are checked).
.
.IP "\fB\-\-sleep \fIsecs"
Sleep (delay) for the given number of seconds after processing a dialog box.
.
.IP "\fB\-\-stderr"
Direct output to the standard error.
This is the default, since curses normally writes screen updates to
the standard output.
.
.IP "\fB\-\-stdout"
Direct output to the standard output.
This option is provided for compatibility with Xdialog,
however using it in portable scripts is not recommended,
since curses normally writes its screen updates to the standard output.
If you use this option, \fBdialog\fR attempts to reopen the terminal
so it can write to the display.
Depending on the platform and your environment, that may fail.
.
.IP "\fB\-\-tab-correct"
Convert each tab character to one or more spaces.
Otherwise, tabs are rendered according to the curses library's interpretation.
.
.IP "\fB\-\-tab-len \fIn"
Specify the number of spaces that a tab character occupies if the
"\fB\-\-tab-correct\fP"
option is given.
The default is 8.
.
.IP "\fB\-\-timeout \fIsecs"
Timeout (exit with error code)
if no user response within the given number of seconds.
.
.IP "\fB\-\-title \fItitle"
Specifies a
\fItitle\fP
string to be displayed at the top of the dialog box.
.
.IP "\fB\-\-trim"
eliminate leading blanks,
trim literal newlines and repeated blanks from message text.
.
.IP "\fB\-\-version"
Same as "\fB\-\-print-version\fP".
.
.IP "\fB\-\-yes-label \fIstring"
Override the label used for "Yes" buttons.
.
.\" ************************************************************************
.SS Box Options
All dialog boxes have at least three parameters:
.TP 5
\fItext\fP
the caption or contents of the box.
.TP 5
\fIheight\fP
the height of the dialog box.
.TP 5
\fIwidth\fP
the width of the dialog box.
.PP
Other parameters depend on the box type.
.
.
.IP "\fB\-\-calendar \fItext height width day month year"
A \fBcalendar\fP box displays
month, day and year in separately adjustable windows.
If the values for day, month or year 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 vi-style h, j, k and l for moving around the array of days in a month.
Use tab or backtab to move between windows.
If the year is given as zero, the current date is used as an initial value.
.IP
On exit, the date is printed in the form day/month/year.
.
.
.IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
A
\fBchecklist\fP
box is similar to a
\fBmenu\fP
box; 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 "."
.IP
On exit, a list of the \fItag\fP
strings of those entries that are turned on
will be printed on dialog's output.
If the \fB\-\-separate-output\fP option is not given,
the strings will be quoted to make it simple for scripts to separate them.
.
.
.nf
.IP "\fB\-\-form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
.fi
The form dialog displays a form consisting of labels and fields,
which are positioned on a scrollable window by coordinates given in the script.
The field length \fIflen\fR and input-length \fIilen\fR tell how long
the field can be.
The former defines the length shown for a selected field,
while the latter defines the permissible length of the data entered in the
field.
If \fIflen\fR is zero, the corresponding field cannot be altered.
If \fIilen\fR is zero, it is set to \fIflen\fR.
.IP
Use up/down arrows (or control/N, control/P) to move between fields.
Use tab to move between windows.
.IP
On exit, the contents of the form-fields are written to dialog's output,
each field separated by a newline.
Input-only fields (\fIflen\fR is zero) are not written out.