whiptail.1

   1 .TH WHIPTAIL 1 "13 October 2006" "Whiptail Version 0.52.4"
   2 .SH NAME
   3 whiptail \- display dialog boxes from shell scripts
   4 .SH SYNOPSIS
   5 .B whiptail
   6 [
   7 .B \-\-title
   8 .I title
   9 ]
  10 [
  11 .B \-\-backtitle
  12 .I backtitle
  13 ]
  14 [
  15 .B \-\-clear
  16 ]
  17 [
  18 .B \-\-default\-item
  19 .I string
  20 ]
  21 [
  22 .B \-\-defaultno
  23 ]
  24 [
  25 .B \-\-fb
  26 ]
  27 [
  28 .B \-\-nocancel
  29 ]
  30 [
  31 .B \-\-yes\-button
  32 .I text
  33 ]
  34 [
  35 .B \-\-no\-button
  36 .I text
  37 ]
  38 [
  39 .B \-\-ok\-button
  40 .I text
  41 ]
  42 [
  43 .B \-\-cancel\-button
  44 .I text
  45 ]
  46 [
  47 .B \-\-noitem
  48 [
  49 ]
  50 .B \-\-output\-fd
  51 .I fd
  52 ]
  53 [
  54 .B \-\-separate\-output
  55 ]
  56 [
  57 .B \-\-scrolltext
  58 ]
  59 [
  60 .B \-\-topleft
  61 ]
  62 .B box-options
  63 .SH DESCRIPTION
  64 .B whiptail
  65 is a program that will let you present a variety of questions or
  66 display messages using dialog boxes from a shell script. Currently,
  67 these types of dialog boxes are implemented:
  68 .LP
  69 .BR yes/no " box," " menu" " box," " input" " box,"
  70 .BR message " box," " text" " box," " info" " box,"
  71 .BR checklist " box," " radiolist" " box" " gauge" " box, and"
  72 .BR password " box."
  73 .SH OPTIONS
  74 .TP
  75 .B \-\-clear
  76 The screen will be cleared to the
  77 .BR "screen attribute" " on exit."
  78 This doesn't work in an xterm (and descendants) if alternate screen
  79 switching is enabled, because in that case slang writes to (and clears)
  80 an alternate screen.
  81 .TP
  82 .B \-\-defaultno
  83 The dialog box will open with the cursor over the
  84 .BR No " button."
  85 .TP
  86 .BI \-\-default\-item " string"
  87 Set  the default item in a menu box.
  88 Normally the first item in the box is the default.
  89 .TP
  90 .B \-\-fb
  91 Use full buttons. (By default,
  92 .B whiptail
  93 uses compact buttons).
  94 .TP
  95 .B \-\-nocancel
  96 The dialog box won't have a
  97 .BR Cancel " button".
  98 .TP
  99 .BI \-\-yes\-button " text"
 100 Set the text of the
 101 .BR Yes " button."
 102 .TP
 103 .BI \-\-no\-button " text"
 104 Set the text of the
 105 .BR No " button."
 106 .TP
 107 .BI \-\-ok\-button " text"
 108 Set the text of the
 109 .BR Ok " button."
 110 .TP
 111 .BI \-\-cancel\-button " text"
 112 Set the text of the
 113 .BR Cancel " button."
 114 .TP
 115 .B \-\-noitem
 116 The menu, checklist and radiolist widgets will display tags only, not
 117 the item strings.
 118 .TP
 119 .BI \-\-separate\-output
 120 For checklist widgets, output result one line at a time, with no
 121 quoting.  This facilitates parsing by another program.
 122 .TP
 123 .BI \-\-output\-fd  " fd"
 124 Direct output to the given file descriptor.  Most
 125 .B whiptail
 126 scripts
 127 write to standard error, but  error  messages  may  also  be
 128 written there, depending on your script.
 129 .TP
 130 .BI \-\-title " title"
 131 Specifies a
 132 .I title
 133 string to be displayed at the top of the dialog box.
 134 .TP
 135 .BI \-\-backtitle " backtitle"
 136 Specifies a
 137 .I backtitle
 138 string to be displayed on the backdrop, at the top of the screen.
 139 .TP
 140 .BI \-\-scrolltext
 141 Force the display of a vertical scrollbar.
 142 .TP
 143 .BI \-\-topleft
 144 Put window in top-left corner.
 145 .TP
 146 .B Box Options
 147 .TP
 148 .BI \-\-yesno " text height width"
 149 .RB A " yes/no" " dialog box of size"
 150 .I height
 151 rows by
 152 .I width
 153 columns will be displayed. The string specified by
 154 .I text
 155 is displayed inside the dialog box. If this string is too long to be fit
 156 in one line, it will be automatically divided into multiple lines at
 157 appropriate places. The
 158 .I text
 159 string may also contain the sub-string
 160 .I
 161 "\en"
 162 or newline characters
 163 .I `\en'
 164 to control line breaking explicitly.  This dialog box is useful for
 165 asking questions that require the user to answer either yes or no.
 166 .RB "The dialog box has a" " Yes" " button and a " No
 167 button, in which the user can switch between by pressing the
 168 .IR TAB " key."
 169 .TP
 170 .BI \-\-msgbox " text height width"
 171 .RB A " message" " box is very similar to a" " yes/no" " box."
 172 The only difference between a
 173 .B message
 174 box and a
 175 .B yes/no
 176 box is that a
 177 .B message
 178 box has only a single
 179 .B OK
 180 button. You can use this dialog box to display any message you like.
 181 After reading the message, the user can press the
 182 .I ENTER
 183 key so that
 184 .B whiptail
 185 will exit and the calling shell script can continue its operation.
 186 .TP
 187 .BI \-\-infobox " text height width"
 188 .RB An " info" " box is basically a" " message" " box."
 189 However, in this case,
 190 .B whiptail
 191 will exit immediately after displaying the message to the user. The
 192 screen is not cleared when
 193 .B whiptail
 194 exits, so that the message will remain on the screen until the calling
 195 shell script clears it later. This is useful when you want to inform
 196 the user that some operations are carrying on that may require some
 197 time to finish.
 198 .TP
 199 .BI \-\-inputbox " text height width [init]"
 200 .RB "An " input " box is useful when you want to ask questions that"
 201 require the user to input a string as the answer. If init is supplied
 202 it is used to initialize the input string.
 203 When inputing the
 204 string, the
 205 .I BACKSPACE
 206 key can be used to correct typing errors. If the input string is longer than
 207 the width of the dialog box, the input field will be scrolled. On exit,
 208 the input string will be printed on
 209 .IR stderr "."
 210 .TP
 211 .BI \-\-passwordbox " text height width [init]"
 212 .RB "A " password " box is similar to an input box, except the text the user"
 213 enters is not displayed. This is useful when prompting for passwords or other
 214 sensitive information. Be aware that if anything is passed in "init", it
 215 will be visible in the system's process table to casual snoopers. Also, it
 216 is very confusing to the user to provide them with a default password they
 217 cannot see. For these reasons, using "init" is highly discouraged.
 218 .TP
 219 .BI \-\-textbox " file height width"
 220 .RB A " text" " box lets you display the contents of a text file in a"
 221 dialog box. It is like a simple text file viewer. The user can move
 222 through the file by using the
 223 .IR UP/DOWN ", " PGUP/PGDN
 224 .RI and " HOME/END" " keys available on most keyboards."
 225 If the lines are too long to be displayed in the box, the
 226 .I LEFT/RIGHT
 227 keys can be used to scroll the text region horizontally. For more
 228 convenience, forward and backward searching functions are also provided.
 229 .IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
 230 As its name suggests, a
 231 .B menu
 232 box is a dialog box that can be used to present a list of choices in
 233 the form of a menu for the user to choose. Each menu entry consists of a
 234 .IR tag " string and an " item " string. The"
 235 .I tag
 236 gives the entry a name to distinguish it from the other entries in the
 237 menu. The
 238 .I item
 239 is a short description of the option that the entry represents. The
 240 user can move between the menu entries by pressing the
 241 .I UP/DOWN
 242 keys, the first letter of the
 243 .I tag
 244 as a hot-key. There are
 245 .I menu-height
 246 entries displayed in the menu at one time, but the menu will be
 247 scrolled if there are more entries than that. When
 248 .B whiptail
 249 exits, the
 250 .I tag
 251 of the chosen menu entry will be printed on
 252 .IR stderr "."
 253 .IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
 254 .RB "A " checklist " box is similar to a " menu " box in that there are"
 255 multiple entries presented in the form of a menu.
 256 You can select and deselect items using the SPACE key.
 257 The initial on/off state of each entry is specified by
 258 .IR status "."
 259 On exit, a list of the
 260 .I tag
 261 strings of those entries that are turned on will be printed on
 262 .IR stderr "."
 263
 264 .IP "\fB\-\-radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
 265 .RB "A " radiolist " box is similar to a " menu " box.  The only difference is"
 266 that you can indicate which entry is currently selected, by setting its
 267 .IR status " to " on "."
 268
 269 .IP "\fB\-\-gauge \fItext height width percent\fR"
 270 .RB "A " gauge " box displays a meter along the bottom of the box.
 271 The meter indicates a percentage.  New percentages are read from
 272 standard input, one integer per line.  The meter is updated
 273 to reflect each new percentage.  If stdin is XXX, then subsequent
 274 lines up to another XXX are used for a new prompt.
 275 The gauge exits when EOF is reached on stdin.
 276
 277 .SH NOTES
 278 whiptail interprets arguments starting with a dash "\-" as being arguments.
 279 To avoid this, and start some text in, for example, a menubox item, with a
 280 dash, whiptail honours the getopt convention of accepting the special
 281 argument "\-\-" which means that all following arguments with dashes are to
 282 be treated verbatim and not parsed as options.
 283 .SH DIAGNOSTICS
 284 Exit status is 0 if
 285 .BR whiptail " is exited by pressing the " Yes " or " OK
 286 button, and 1 if the
 287 .BR No " or " Cancel
 288 button is pressed. Otherwise, if errors occur inside
 289 .B whiptail
 290 or
 291 .B whiptail
 292 is exited by pressing the
 293 .I ESC
 294 key, the exit status is -1.
 295 .SH AUTHOR
 296 Based on the man page for dialog(1) by:
 297 .LP
 298 Savio Lam (lam836@cs.cuhk.hk) - version 0.3
 299 .LP
 300 Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for version 0.4
 301 .LP
 302 Modifications for whiptail by:
 303 .LP
 304 Enrique Zanardi (ezanard@debian.org)
 305 .LP
 306 Alastair McKinstry (mckinstry@debian.org)