949 lines
30 KiB
Groff
949 lines
30 KiB
Groff
.\" $Id: dialog.1,v 1.84 2005/02/07 00:33:50 tom Exp $
|
|
.\" Copyright 2005 Thomas E. Dickey
|
|
.\"
|
|
.\" This program is free software; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License
|
|
.\" as published by the Free Software Foundation; either version 2
|
|
.\" of the License, or (at your option) any later version.
|
|
.\"
|
|
.\" This program is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License
|
|
.\" along with this program; if not, write to the Free Software
|
|
.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
.de EX
|
|
.ne 8
|
|
.IP
|
|
..
|
|
.de ES
|
|
.RS +10
|
|
.nf
|
|
..
|
|
.de EE
|
|
.fi
|
|
.RE
|
|
..
|
|
.
|
|
.TH DIALOG 1 "" "$Date: 2005/02/07 00:33:50 $"
|
|
.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 pause ", "
|
|
.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 \fBdialog\fP'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;
|
|
\fBdialog\fP exits immediately in that case.
|
|
.
|
|
.\" ************************************************************************
|
|
.SH OPTIONS
|
|
All options begin with "\fB--\fP"
|
|
(two ASCII hyphens,
|
|
for the benefit of those using systems with deranged locale support).
|
|
.PP
|
|
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.
|
|
.RS
|
|
.B dialog --title -- --Not an option
|
|
.RE
|
|
.PP
|
|
The "\fB--args\fP" option tells \fBdialog\fP to list the command-line
|
|
parameters to the standard error.
|
|
This is useful when debugging complex scripts using
|
|
the "\fB--\fP" and "\fB--file\fP",
|
|
since the command-line may be rewritten as these are expanded.
|
|
.PP
|
|
The "\fB--file\fP" option tells \fBdialog\fP to read parameters from
|
|
the file named as its value.
|
|
.RS
|
|
.B dialog --file parameterfile
|
|
.RE
|
|
Blanks not within double-quotes are discarded
|
|
(use backslashes to quote single characters).
|
|
The result is inserted into the command-line,
|
|
replacing "\fB--file\fP" and its option value.
|
|
Interpretation of the command-line resumes from that point.
|
|
.
|
|
.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--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"
|
|
Clears the widget screen, keeping only the screen_color background.
|
|
Use this when you combine widgets with "\fB--and-widget\fR" to erase the
|
|
contents of a previous widget on the screen, so it won't be seen
|
|
under the contents of a following widget.
|
|
Understand this as the complement of "\fB--keep-window\fR".
|
|
To compare the effects, use these:
|
|
.
|
|
.EX
|
|
All three widgets visible, staircase effect, ordered 1,2,3:
|
|
.ES
|
|
dialog --begin 2 2 --yesno "" 0 0 \\
|
|
--and-widget --begin 4 4 --yesno "" 0 0 \\
|
|
--and-widget --begin 6 6 --yesno "" 0 0
|
|
.EE
|
|
.
|
|
.EX
|
|
Only the last widget is left visible:
|
|
.ES
|
|
dialog --clear --begin 2 2 --yesno "" 0 0 \\
|
|
--and-widget --clear --begin 4 4 --yesno "" 0 0 \\
|
|
--and-widget --begin 6 6 --yesno "" 0 0
|
|
.EE
|
|
.
|
|
.EX
|
|
All three widgets visible, staircase effect, ordered 3,2,1:
|
|
.ES
|
|
dialog --keep-window --begin 2 2 --yesno "" 0 0 \\
|
|
--and-widget --keep-window --begin 4 4 --yesno "" 0 0 \\
|
|
--and-widget --begin 6 6 --yesno "" 0 0
|
|
.EE
|
|
.
|
|
.EX
|
|
First and third widget visible, staircase effect, ordered 3,1:
|
|
.ES
|
|
dialog --keep-window --begin 2 2 --yesno "" 0 0 \\
|
|
--and-widget --clear --begin 4 4 --yesno "" 0 0 \\
|
|
--and-widget --begin 6 6 --yesno "" 0 0
|
|
.EE
|
|
.IP
|
|
Note, if you want to restore original console colors and send your
|
|
cursor home after the dialog program has exited, use the \fBclear\fR\ (1)
|
|
command.
|
|
.
|
|
.IP "\fB--colors"
|
|
Interpret embedded "\\Z" sequences in the dialog text
|
|
by the following character,
|
|
which tells \fBdialog\fP 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
|
|
bold (perhaps 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
|
|
See also the "\fB--no-collapse\fP" and "\fB--trim\fP" options.
|
|
.
|
|
.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.
|
|
If "\fB--nocancel\fP" or "\fB--visit-items\fP" are given
|
|
those options overrides this,
|
|
making the default button always "Yes" (internally the same as "OK").
|
|
.
|
|
.IP "\fB--default-item \fIstring"
|
|
Set the default item in a checklist, form or 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 \fBdialog\fP'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 \fBdialog\fP'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, radiolist or form 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"
|
|
Normally when \fBdialog\fR performs several \fBtailboxbg\fR widgets
|
|
connected by "\fB--and-widget\fR",
|
|
it clears the old widget from the screen by painting over it.
|
|
Use this option to suppress that repainting.
|
|
.IP
|
|
At exit, \fBdialog\fR repaints all of the widgets which have been
|
|
marked with "\fB--keep-window\fR", even if they are not \fBtailboxbg\fR widgets.
|
|
That causes them to be repainted in reverse order.
|
|
See the discussion of the "\fB--clear\fR" option for examples.
|
|
.
|
|
.IP "\fB--max-input \fIsize"
|
|
Limit input strings to the given size.
|
|
If not specified, the limit is 2048.
|
|
.
|
|
.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" and "\fB--trim\fR" options.
|
|
.
|
|
.IP "\fB--no-kill"
|
|
Tells
|
|
\fBdialog\fP
|
|
to put the
|
|
\fBtailboxbg\fP
|
|
box in the background,
|
|
printing its process id to \fBdialog\fP'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 \fBdialog\fP's output.
|
|
This may be used alone, without other options.
|
|
.
|
|
.IP "\fB--print-size"
|
|
Prints the size of each dialog box to \fBdialog\fP's output.
|
|
.
|
|
.IP "\fB--print-version"
|
|
Prints \fBdialog\fR's version to \fBdialog\fP'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 \fBdialog\fP'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--single-quoted"
|
|
Use single-quoting as needed (and no quotes if unneeded) for the
|
|
output of checklist's as well as the item-help text.
|
|
If this option is not set, \fBdialog\fP uses double quotes around each item.
|
|
That requires occasional use of backslashes to make the output useful in
|
|
shell scripts.
|
|
.
|
|
.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.
|
|
This is overridden if the background "\fB--tailboxbg\fP is used.
|
|
A timeout of zero seconds is ignored.
|
|
.
|
|
.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
|
|
See also the "\fB--cr-wrap\fR" and "\fB--no-collapse\fR" options.
|
|
.
|
|
.IP "\fB--version"
|
|
Same as "\fB--print-version\fP".
|
|
.
|
|
.IP "\fB--visit-items"
|
|
Modify the tab-traversal of checklist, radiobox, menubox and inputmenu
|
|
to include the list of items as one of the states.
|
|
This is useful as a visual aid,
|
|
i.e., the cursor position helps some users.
|
|
.IP
|
|
When this option is given, the cursor is initially placed on the list.
|
|
Abbreviations (the first letter of the tag) apply to the list items.
|
|
If you tab to the button row, abbreviations apply to the buttons.
|
|
.
|
|
.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 \fBdialog\fP'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.
|
|
See the "\fB--single-quoted\fP" option, which modifies the quoting behavior.
|
|
.
|
|
.
|
|
.nf
|
|
.IP "\fB--form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
|
|
.fi
|
|
The form \fBdialog\fP 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.
|
|
.RS
|
|
.TP 3
|
|
-
|
|
If \fIflen\fR is zero, the corresponding field cannot be altered.
|
|
and the contents of the field determine the displayed-length.
|
|
.TP 3
|
|
-
|
|
If \fIflen\fR is negative, the corresponding field cannot be altered,
|
|
and the negated value of \fIflen\fR is used as the displayed-length.
|
|
.TP 3
|
|
-
|
|
If \fIilen\fR is zero, it is set to \fIflen\fR.
|
|
.RE
|
|
.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 \fBdialog\fP's output,
|
|
each field separated by a newline.
|
|
The text used to fill non-editable fields
|
|
(\fIflen\fR is zero or negative)
|
|
is not written out.
|
|
.
|
|
.
|
|
.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 \fBdialog\fP'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 \fBdialog\fP'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 \fBdialog\fP'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 \fBdialog\fP'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 \fBdialog\fP will write the following on \fBdialog\fP'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 \fBdialog\fP'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 \fBdialog\fP's output.
|
|
Only an "OK" button is provided for input,
|
|
but an ESC exit status may be returned.
|
|
.
|
|
.IP "\fB\-\-pause \fItext height width seconds\fR"
|
|
A
|
|
\fBpause\fP
|
|
box displays a meter along the bottom of the box.
|
|
The meter indicates how many seconds remain until the end of the pause.
|
|
The pause exits when timeout is reached (status OK)
|
|
or the user presses the Exit button
|
|
(status CANCEL).
|
|
.
|
|
.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 \fBdialog\fP'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 \fBdialog\fP'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 \fBdialog\fP'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"),
|
|
\fBdialog\fP 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, \fBdialog\fP 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 \fBdialog\fP's output.
|
|
Only an "EXIT" button is provided for input,
|
|
but an ESC exit status may be returned.
|
|
.IP
|
|
NOTE:
|
|
Older versions of \fBdialog\fP 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, page-up, page-down
|
|
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 page-up and page-down 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 \fBdialog\fP'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 \fBdialog\fP's output.
|
|
In addition to the "Yes" and "No" exit codes (see DIAGNOSTICS)
|
|
an ESC exit status may be returned.
|
|
.IP
|
|
The codes used for "Yes" and "No" match those used for "OK" and "Cancel",
|
|
internally no distinction is made.
|
|
.
|
|
.\" ************************************************************************
|
|
.SS "Obsolete Options"
|
|
.\" from cdialog 0.9a (Pako)
|
|
.IP "\fB--beep"
|
|
This was used to tell the original cdialog that it should make a beep
|
|
when the separate processes of the tailboxbg widget would repaint the screen.
|
|
.
|
|
.\" from cdialog 0.9a (Pako)
|
|
.IP "\fB--beep-after"
|
|
Beep after a user has completed a widget by pressing one of the buttons.
|
|
.
|
|
.\" ************************************************************************
|
|
.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
|
|
\fBDIALOGOPTS\fP
|
|
Define this variable to apply any of the common options to each widget.
|
|
Most of the common options are reset before processing each widget.
|
|
If you set the options in this environment variable,
|
|
they are applied to \fBdialog\fP's state after the reset.
|
|
As in the "\fB--file\fP" option,
|
|
double-quotes and backslashes are interpreted.
|
|
.IP
|
|
The "\fB--file\fP" option is not considered a common option
|
|
(so you cannot embed it within this environment variable).
|
|
.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_ITEM_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),
|
|
Help with --item-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 \fBdialog\fP 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 \fBdialog\fP 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 (lam836@cs.cuhk.hk) - version 0.3, "dialog"
|
|
.LP
|
|
Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for version 0.4
|
|
.LP
|
|
Pako (demarco_p@abramo.it) - version 0.9a, "cdialog",
|
|
.LP
|
|
Thomas Dickey (updates for 0.9b and beyond)
|
|
.SH CONTRIBUTORS
|
|
Tobias C. Rittweiler (tobrit@freebits.de)
|