|
Packit |
4d380f |
.TH WHIPTAIL 1 "31 January 2007" "Whiptail Version 0.52.5"
|
|
Packit |
4d380f |
.SH NAME
|
|
Packit |
4d380f |
whiptail \- display dialog boxes from shell scripts
|
|
Packit |
4d380f |
.SH SYNOPSIS
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-title
|
|
Packit |
4d380f |
.I title
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-backtitle
|
|
Packit |
4d380f |
.I backtitle
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-clear
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-default\-item
|
|
Packit |
4d380f |
.I string
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-defaultno
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-fb
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-nocancel
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-yes\-button
|
|
Packit |
4d380f |
.I text
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-no\-button
|
|
Packit |
4d380f |
.I text
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-ok\-button
|
|
Packit |
4d380f |
.I text
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-cancel\-button
|
|
Packit |
4d380f |
.I text
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-noitem
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
.B \-\-output\-fd
|
|
Packit |
4d380f |
.I fd
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-separate\-output
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-scrolltext
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
[
|
|
Packit |
4d380f |
.B \-\-topleft
|
|
Packit |
4d380f |
]
|
|
Packit |
4d380f |
.B box-options
|
|
Packit |
4d380f |
.SH DESCRIPTION
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
is a program that will let you present a variety of questions or
|
|
Packit |
4d380f |
display messages using dialog boxes from a shell script. Currently,
|
|
Packit |
4d380f |
these types of dialog boxes are implemented:
|
|
Packit |
4d380f |
.LP
|
|
Packit |
4d380f |
.BR yes/no " box," " menu" " box," " input" " box,"
|
|
Packit |
4d380f |
.BR message " box," " text" " box," " info" " box,"
|
|
Packit |
4d380f |
.BR checklist " box," " radiolist" " box" " gauge" " box, and"
|
|
Packit |
4d380f |
.BR password " box."
|
|
Packit |
4d380f |
.SH OPTIONS
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.B \-\-clear
|
|
Packit |
4d380f |
The screen will be cleared to the
|
|
Packit |
4d380f |
.BR "screen attribute" " on exit."
|
|
Packit |
4d380f |
This doesn't work in an xterm (and descendants) if alternate screen
|
|
Packit |
4d380f |
switching is enabled, because in that case slang writes to (and clears)
|
|
Packit |
4d380f |
an alternate screen.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.B \-\-defaultno
|
|
Packit |
4d380f |
The dialog box will open with the cursor over the
|
|
Packit |
4d380f |
.BR No " button."
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-default\-item " string"
|
|
Packit |
4d380f |
Set the default item in a menu box.
|
|
Packit |
4d380f |
Normally the first item in the box is the default.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
\fB\-\-fb\fR, \fB\-\-fullbuttons\fR
|
|
Packit |
4d380f |
Use full buttons. (By default,
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
uses compact buttons).
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.B \-\-nocancel
|
|
Packit |
4d380f |
The dialog box won't have a
|
|
Packit |
4d380f |
.BR Cancel " button".
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-yes\-button " text"
|
|
Packit |
4d380f |
Set the text of the
|
|
Packit |
4d380f |
.BR Yes " button."
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-no\-button " text"
|
|
Packit |
4d380f |
Set the text of the
|
|
Packit |
4d380f |
.BR No " button."
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-ok\-button " text"
|
|
Packit |
4d380f |
Set the text of the
|
|
Packit |
4d380f |
.BR Ok " button."
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-cancel\-button " text"
|
|
Packit |
4d380f |
Set the text of the
|
|
Packit |
4d380f |
.BR Cancel " button."
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.B \-\-noitem
|
|
Packit |
4d380f |
The menu, checklist and radiolist widgets will display tags only, not
|
|
Packit |
4d380f |
the item strings. The menu widget still needs some items specified,
|
|
Packit |
4d380f |
but checklist and radiolist expect only tag and status.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.B \-\-notags
|
|
Packit |
4d380f |
Don't display tags in the menu, checklist and radiolist widgets.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-separate\-output
|
|
Packit |
4d380f |
For checklist widgets, output result one line at a time, with no
|
|
Packit |
4d380f |
quoting. This facilitates parsing by another program.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-output\-fd " fd"
|
|
Packit |
4d380f |
Direct output to the given file descriptor. Most
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
scripts
|
|
Packit |
4d380f |
write to standard error, but error messages may also be
|
|
Packit |
4d380f |
written there, depending on your script.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-title " title"
|
|
Packit |
4d380f |
Specifies a
|
|
Packit |
4d380f |
.I title
|
|
Packit |
4d380f |
string to be displayed at the top of the dialog box.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-backtitle " backtitle"
|
|
Packit |
4d380f |
Specifies a
|
|
Packit |
4d380f |
.I backtitle
|
|
Packit |
4d380f |
string to be displayed on the backdrop, at the top of the screen.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-scrolltext
|
|
Packit |
4d380f |
Force the display of a vertical scrollbar.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-topleft
|
|
Packit |
4d380f |
Put window in top-left corner.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
\fB\-h\fR, \fB\-\-help\fR
|
|
Packit |
4d380f |
Print a help message and exit.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
\fB\-v\fR, \fB\-\-version\fR
|
|
Packit |
4d380f |
Print version information and exit.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.B Box Options
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-yesno " text height width"
|
|
Packit |
4d380f |
.RB A " yes/no" " dialog box of size"
|
|
Packit |
4d380f |
.I height
|
|
Packit |
4d380f |
rows by
|
|
Packit |
4d380f |
.I width
|
|
Packit |
4d380f |
columns will be displayed. The string specified by
|
|
Packit |
4d380f |
.I text
|
|
Packit |
4d380f |
is displayed inside the dialog box. If this string is too long to be fit
|
|
Packit |
4d380f |
in one line, it will be automatically divided into multiple lines at
|
|
Packit |
4d380f |
appropriate places. The
|
|
Packit |
4d380f |
.I text
|
|
Packit |
4d380f |
string may also contain the sub-string
|
|
Packit |
4d380f |
.I
|
|
Packit |
4d380f |
"\en"
|
|
Packit |
4d380f |
or newline characters
|
|
Packit |
4d380f |
.I `\en'
|
|
Packit |
4d380f |
to control line breaking explicitly. This dialog box is useful for
|
|
Packit |
4d380f |
asking questions that require the user to answer either yes or no.
|
|
Packit |
4d380f |
.RB "The dialog box has a" " Yes" " button and a " No
|
|
Packit |
4d380f |
button, in which the user can switch between by pressing the
|
|
Packit |
4d380f |
.IR TAB " key."
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-msgbox " text height width"
|
|
Packit |
4d380f |
.RB A " message" " box is very similar to a" " yes/no" " box."
|
|
Packit |
4d380f |
The only difference between a
|
|
Packit |
4d380f |
.B message
|
|
Packit |
4d380f |
box and a
|
|
Packit |
4d380f |
.B yes/no
|
|
Packit |
4d380f |
box is that a
|
|
Packit |
4d380f |
.B message
|
|
Packit |
4d380f |
box has only a single
|
|
Packit |
4d380f |
.B OK
|
|
Packit |
4d380f |
button. You can use this dialog box to display any message you like.
|
|
Packit |
4d380f |
After reading the message, the user can press the
|
|
Packit |
4d380f |
.I ENTER
|
|
Packit |
4d380f |
key so that
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
will exit and the calling shell script can continue its operation.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-infobox " text height width"
|
|
Packit |
4d380f |
.RB An " info" " box is basically a" " message" " box."
|
|
Packit |
4d380f |
However, in this case,
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
will exit immediately after displaying the message to the user. The
|
|
Packit |
4d380f |
screen is not cleared when
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
exits, so that the message will remain on the screen until the calling
|
|
Packit |
4d380f |
shell script clears it later. This is useful when you want to inform
|
|
Packit |
4d380f |
the user that some operations are carrying on that may require some
|
|
Packit |
4d380f |
time to finish.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-inputbox " text height width [init]"
|
|
Packit |
4d380f |
.RB "An " input " box is useful when you want to ask questions that"
|
|
Packit |
4d380f |
require the user to input a string as the answer. If init is supplied
|
|
Packit |
4d380f |
it is used to initialize the input string.
|
|
Packit |
4d380f |
When inputing the
|
|
Packit |
4d380f |
string, the
|
|
Packit |
4d380f |
.I BACKSPACE
|
|
Packit |
4d380f |
key can be used to correct typing errors. If the input string is longer than
|
|
Packit |
4d380f |
the width of the dialog box, the input field will be scrolled. On exit,
|
|
Packit |
4d380f |
the input string will be printed on
|
|
Packit |
4d380f |
.IR stderr "."
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-passwordbox " text height width [init]"
|
|
Packit |
4d380f |
.RB "A " password " box is similar to an input box, except the text the user"
|
|
Packit |
4d380f |
enters is not displayed. This is useful when prompting for passwords or other
|
|
Packit |
4d380f |
sensitive information. Be aware that if anything is passed in "init", it
|
|
Packit |
4d380f |
will be visible in the system's process table to casual snoopers. Also, it
|
|
Packit |
4d380f |
is very confusing to the user to provide them with a default password they
|
|
Packit |
4d380f |
cannot see. For these reasons, using "init" is highly discouraged.
|
|
Packit |
4d380f |
.TP
|
|
Packit |
4d380f |
.BI \-\-textbox " file height width"
|
|
Packit |
4d380f |
.RB A " text" " box lets you display the contents of a text file in a"
|
|
Packit |
4d380f |
dialog box. It is like a simple text file viewer. The user can move
|
|
Packit |
4d380f |
through the file by using the
|
|
Packit |
4d380f |
.IR UP/DOWN ", " PGUP/PGDN
|
|
Packit |
4d380f |
.RI and " HOME/END" " keys available on most keyboards."
|
|
Packit |
4d380f |
If the lines are too long to be displayed in the box, the
|
|
Packit |
4d380f |
.I LEFT/RIGHT
|
|
Packit |
4d380f |
keys can be used to scroll the text region horizontally. For more
|
|
Packit |
4d380f |
convenience, forward and backward searching functions are also provided.
|
|
Packit |
4d380f |
.IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
|
|
Packit |
4d380f |
As its name suggests, a
|
|
Packit |
4d380f |
.B menu
|
|
Packit |
4d380f |
box is a dialog box that can be used to present a list of choices in
|
|
Packit |
4d380f |
the form of a menu for the user to choose. Each menu entry consists of a
|
|
Packit |
4d380f |
.IR tag " string and an " item " string. The"
|
|
Packit |
4d380f |
.I tag
|
|
Packit |
4d380f |
gives the entry a name to distinguish it from the other entries in the
|
|
Packit |
4d380f |
menu. The
|
|
Packit |
4d380f |
.I item
|
|
Packit |
4d380f |
is a short description of the option that the entry represents. The
|
|
Packit |
4d380f |
user can move between the menu entries by pressing the
|
|
Packit |
4d380f |
.I UP/DOWN
|
|
Packit |
4d380f |
keys, the first letter of the
|
|
Packit |
4d380f |
.I tag
|
|
Packit |
4d380f |
as a hot-key. There are
|
|
Packit |
4d380f |
.I menu-height
|
|
Packit |
4d380f |
entries displayed in the menu at one time, but the menu will be
|
|
Packit |
4d380f |
scrolled if there are more entries than that. When
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
exits, the
|
|
Packit |
4d380f |
.I tag
|
|
Packit |
4d380f |
of the chosen menu entry will be printed on
|
|
Packit |
4d380f |
.IR stderr "."
|
|
Packit |
4d380f |
.IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
|
|
Packit |
4d380f |
.RB "A " checklist " box is similar to a " menu " box in that there are"
|
|
Packit |
4d380f |
multiple entries presented in the form of a menu.
|
|
Packit |
4d380f |
You can select and deselect items using the SPACE key.
|
|
Packit |
4d380f |
The initial on/off state of each entry is specified by
|
|
Packit |
4d380f |
.IR status "."
|
|
Packit |
4d380f |
On exit, a list of the
|
|
Packit |
4d380f |
.I tag
|
|
Packit |
4d380f |
strings of those entries that are turned on will be printed on
|
|
Packit |
4d380f |
.IR stderr "."
|
|
Packit |
4d380f |
|
|
Packit |
4d380f |
.IP "\fB\-\-radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
|
|
Packit |
4d380f |
.RB "A " radiolist " box is similar to a " menu " box. The only difference is"
|
|
Packit |
4d380f |
that you can indicate which entry is currently selected, by setting its
|
|
Packit |
4d380f |
.IR status " to " on "."
|
|
Packit |
4d380f |
|
|
Packit |
4d380f |
.IP "\fB\-\-gauge \fItext height width percent\fR"
|
|
Packit |
4d380f |
.RB "A " gauge " box displays a meter along the bottom of the box.
|
|
Packit |
4d380f |
The meter indicates a percentage. New percentages are read from
|
|
Packit |
4d380f |
standard input, one integer per line. The meter is updated
|
|
Packit |
4d380f |
to reflect each new percentage. If stdin is XXX, the first following line is
|
|
Packit |
4d380f |
a percentage and subsequent lines up to another XXX are used for a new prompt.
|
|
Packit |
4d380f |
The gauge exits when EOF is reached on stdin.
|
|
Packit |
4d380f |
|
|
Packit |
4d380f |
.SH NOTES
|
|
Packit |
4d380f |
whiptail interprets arguments starting with a dash "\-" as being arguments.
|
|
Packit |
4d380f |
To avoid this, and start some text in, for example, a menubox item, with a
|
|
Packit |
4d380f |
dash, whiptail honours the getopt convention of accepting the special
|
|
Packit |
4d380f |
argument "\-\-" which means that all following arguments with dashes are to
|
|
Packit |
4d380f |
be treated verbatim and not parsed as options.
|
|
Packit |
4d380f |
.SH DIAGNOSTICS
|
|
Packit |
4d380f |
Exit status is 0 if
|
|
Packit |
4d380f |
.BR whiptail " is exited by pressing the " Yes " or " OK
|
|
Packit |
4d380f |
button, and 1 if the
|
|
Packit |
4d380f |
.BR No " or " Cancel
|
|
Packit |
4d380f |
button is pressed. Otherwise, if errors occur inside
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
or
|
|
Packit |
4d380f |
.B whiptail
|
|
Packit |
4d380f |
is exited by pressing the
|
|
Packit |
4d380f |
.I ESC
|
|
Packit |
4d380f |
key, the exit status is -1.
|
|
Packit |
4d380f |
.SH AUTHOR
|
|
Packit |
4d380f |
Based on the man page for dialog(1) by:
|
|
Packit |
4d380f |
.LP
|
|
Packit |
4d380f |
Savio Lam (lam836@cs.cuhk.hk) - version 0.3
|
|
Packit |
4d380f |
.LP
|
|
Packit |
4d380f |
Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for version 0.4
|
|
Packit |
4d380f |
.LP
|
|
Packit |
4d380f |
Modifications for whiptail by:
|
|
Packit |
4d380f |
.LP
|
|
Packit |
4d380f |
Enrique Zanardi (ezanard@debian.org)
|
|
Packit |
4d380f |
.LP
|
|
Packit |
4d380f |
Alastair McKinstry (mckinstry@debian.org)
|