whiptail.1

   1 .TH WHIPTAIL 1 "31 January 2007" "Whiptail Version 0.52.5"
   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 \fB\-\-fb\fR, \fB\-\-fullbuttons\fR
  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. The menu widget still needs some items specified,
 118 but checklist and radiolist expect only tag and status.
 119 .TP
 120 .B \-\-notags
 121 Don't display tags in the menu, checklist and radiolist widgets.
 122 .TP
 123 .BI \-\-separate\-output
 124 For checklist widgets, output result one line at a time, with no
 125 quoting.  This facilitates parsing by another program.
 126 .TP
 127 .BI \-\-output\-fd  " fd"
 128 Direct output to the given file descriptor.  Most
 129 .B whiptail
 130 scripts
 131 write to standard error, but  error  messages  may  also  be
 132 written there, depending on your script.
 133 .TP
 134 .BI \-\-title " title"
 135 Specifies a
 136 .I title
 137 string to be displayed at the top of the dialog box.
 138 .TP
 139 .BI \-\-backtitle " backtitle"
 140 Specifies a
 141 .I backtitle
 142 string to be displayed on the backdrop, at the top of the screen.
 143 .TP
 144 .BI \-\-scrolltext
 145 Force the display of a vertical scrollbar.
 146 .TP
 147 .BI \-\-topleft
 148 Put window in top-left corner.
 149 .TP
 150 \fB\-h\fR, \fB\-\-help\fR
 151 Print a help message and exit.
 152 .TP
 153 \fB\-v\fR, \fB\-\-version\fR
 154 Print version information and exit.
 155 .TP
 156 .B Box Options
 157 .TP
 158 .BI \-\-yesno " text height width"
 159 .RB A " yes/no" " dialog box of size"
 160 .I height
 161 rows by
 162 .I width
 163 columns will be displayed. The string specified by
 164 .I text
 165 is displayed inside the dialog box. If this string is too long to be fit
 166 in one line, it will be automatically divided into multiple lines at
 167 appropriate places. The
 168 .I text
 169 string may also contain the sub-string
 170 .I
 171 "\en"
 172 or newline characters
 173 .I `\en'
 174 to control line breaking explicitly.  This dialog box is useful for
 175 asking questions that require the user to answer either yes or no.
 176 .RB "The dialog box has a" " Yes" " button and a " No
 177 button, in which the user can switch between by pressing the
 178 .IR TAB " key."
 179 .TP
 180 .BI \-\-msgbox " text height width"
 181 .RB A " message" " box is very similar to a" " yes/no" " box."
 182 The only difference between a
 183 .B message
 184 box and a
 185 .B yes/no
 186 box is that a
 187 .B message
 188 box has only a single
 189 .B OK
 190 button. You can use this dialog box to display any message you like.
 191 After reading the message, the user can press the
 192 .I ENTER
 193 key so that
 194 .B whiptail
 195 will exit and the calling shell script can continue its operation.
 196 .TP
 197 .BI \-\-infobox " text height width"
 198 .RB An " info" " box is basically a" " message" " box."
 199 However, in this case,
 200 .B whiptail
 201 will exit immediately after displaying the message to the user. The
 202 screen is not cleared when
 203 .B whiptail
 204 exits, so that the message will remain on the screen until the calling
 205 shell script clears it later. This is useful when you want to inform
 206 the user that some operations are carrying on that may require some
 207 time to finish.
 208 .TP
 209 .BI \-\-inputbox " text height width [init]"
 210 .RB "An " input " box is useful when you want to ask questions that"
 211 require the user to input a string as the answer. If init is supplied
 212 it is used to initialize the input string.
 213 When inputing the
 214 string, the
 215 .I BACKSPACE
 216 key can be used to correct typing errors. If the input string is longer than
 217 the width of the dialog box, the input field will be scrolled. On exit,
 218 the input string will be printed on
 219 .IR stderr "."
 220 .TP
 221 .BI \-\-passwordbox " text height width [init]"
 222 .RB "A " password " box is similar to an input box, except the text the user"
 223 enters is not displayed. This is useful when prompting for passwords or other
 224 sensitive information. Be aware that if anything is passed in "init", it
 225 will be visible in the system's process table to casual snoopers. Also, it
 226 is very confusing to the user to provide them with a default password they
 227 cannot see. For these reasons, using "init" is highly discouraged.
 228 .TP
 229 .BI \-\-textbox " file height width"
 230 .RB A " text" " box lets you display the contents of a text file in a"
 231 dialog box. It is like a simple text file viewer. The user can move
 232 through the file by using the
 233 .IR UP/DOWN ", " PGUP/PGDN
 234 .RI and " HOME/END" " keys available on most keyboards."
 235 If the lines are too long to be displayed in the box, the
 236 .I LEFT/RIGHT
 237 keys can be used to scroll the text region horizontally. For more
 238 convenience, forward and backward searching functions are also provided.
 239 .IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
 240 As its name suggests, a
 241 .B menu
 242 box is a dialog box that can be used to present a list of choices in
 243 the form of a menu for the user to choose. Each menu entry consists of a
 244 .IR tag " string and an " item " string. The"
 245 .I tag
 246 gives the entry a name to distinguish it from the other entries in the
 247 menu. The
 248 .I item
 249 is a short description of the option that the entry represents. The
 250 user can move between the menu entries by pressing the
 251 .I UP/DOWN
 252 keys, the first letter of the
 253 .I tag
 254 as a hot-key. There are
 255 .I menu-height
 256 entries displayed in the menu at one time, but the menu will be
 257 scrolled if there are more entries than that. When
 258 .B whiptail
 259 exits, the
 260 .I tag
 261 of the chosen menu entry will be printed on
 262 .IR stderr "."
 263 .IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
 264 .RB "A " checklist " box is similar to a " menu " box in that there are"
 265 multiple entries presented in the form of a menu.
 266 You can select and deselect items using the SPACE key.
 267 The initial on/off state of each entry is specified by
 268 .IR status "."
 269 On exit, a list of the
 270 .I tag
 271 strings of those entries that are turned on will be printed on
 272 .IR stderr "."
 273
 274 .IP "\fB\-\-radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
 275 .RB "A " radiolist " box is similar to a " menu " box.  The only difference is"
 276 that you can indicate which entry is currently selected, by setting its
 277 .IR status " to " on "."
 278
 279 .IP "\fB\-\-gauge \fItext height width percent\fR"
 280 .RB "A " gauge " box displays a meter along the bottom of the box.
 281 The meter indicates a percentage.  New percentages are read from
 282 standard input, one integer per line.  The meter is updated
 283 to reflect each new percentage.  If stdin is XXX, the first following line is
 284 a percentage and subsequent lines up to another XXX are used for a new prompt.
 285 The gauge exits when EOF is reached on stdin.
 286
 287 .SH NOTES
 288 whiptail interprets arguments starting with a dash "\-" as being arguments.
 289 To avoid this, and start some text in, for example, a menubox item, with a
 290 dash, whiptail honours the getopt convention of accepting the special
 291 argument "\-\-" which means that all following arguments with dashes are to
 292 be treated verbatim and not parsed as options.
 293
 294 If the specified height, width, or menu/list-height is zero,
 295 .BR whiptail
 296 will increase the values as needed in order to display all information.
 297
 298 .SH DIAGNOSTICS
 299 Exit status is 0 if
 300 .BR whiptail " is exited by pressing the " Yes " or " OK
 301 button, and 1 if the
 302 .BR No " or " Cancel
 303 button is pressed. Otherwise, if errors occur inside
 304 .B whiptail
 305 or
 306 .B whiptail
 307 is exited by pressing the
 308 .I ESC
 309 key, the exit status is -1.
 310 .SH AUTHOR
 311 Based on the man page for dialog(1) by:
 312 .LP
 313 Savio Lam (lam836@cs.cuhk.hk) - version 0.3
 314 .LP
 315 Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for version 0.4
 316 .LP
 317 Modifications for whiptail by:
 318 .LP
 319 Enrique Zanardi (ezanard@debian.org)
 320 .LP
 321 Alastair McKinstry (mckinstry@debian.org)