1WHIPTAIL(1) General Commands Manual WHIPTAIL(1)
2
6 whiptail - display dialog boxes from shell scripts
7
9 whiptail [ --title title ] [ --backtitle backtitle ] [ --clear ] [
10 --default-item string ] [ --defaultno ] [ --fb ] [ --nocancel ] [
11 --yes-button text ] [ --no-button text ] [ --ok-button text ] [ --can‐
12 cel-button text ] [ --noitem [ ] --output-fd fd ] [ --separate-output ]
13 [ --scrolltext ] [ --topleft ] box-options
14
16 whiptail is a program that will let you present a variety of questions
17 or display messages using dialog boxes from a shell script. Currently,
18 these types of dialog boxes are implemented:
19 yes/no box, menu box, input box, message box, text box, info box,
21 checklist box, radiolist box gauge box, and password box.
22
24 --clear
25 The screen will be cleared to the screen attribute on exit.
26 This doesn't work in an xterm (and descendants) if alternate
27 screen switching is enabled, because in that case slang writes
28 to (and clears) an alternate screen.
29 --defaultno
31 The dialog box will open with the cursor over the No button.
32 --default-item string
34 Set the default item in a menu box. Normally the first item in
35 the box is the default.
36 --fb, --fullbuttons
38 Use full buttons. (By default, whiptail uses compact buttons).
39 --nocancel
41 The dialog box won't have a Cancel button.
42 --yes-button text
44 Set the text of the Yes button.
45 --no-button text
47 Set the text of the No button.
48 --ok-button text
50 Set the text of the Ok button.
51 --cancel-button text
53 Set the text of the Cancel button.
54 --noitem
56 The menu, checklist and radiolist widgets will display tags
57 only, not the item strings. The menu widget still needs some
58 items specified, but checklist and radiolist expect only tag and
59 status.
60 --notags
62 Don't display tags in the menu, checklist and radiolist widgets.
63 --separate-output
65 For checklist widgets, output result one line at a time, with no
66 quoting. This facilitates parsing by another program.
67 --output-fd fd
69 Direct output to the given file descriptor. Most whiptail
70 scripts write to standard error, but error messages may also
71 be written there, depending on your script.
72 --title title
74 Specifies a title string to be displayed at the top of the dia‐
75 log box.
76 --backtitle backtitle
78 Specifies a backtitle string to be displayed on the backdrop, at
79 the top of the screen.
80 --scrolltext
82 Force the display of a vertical scrollbar.
83 --topleft
85 Put window in top-left corner.
86 -h, --help
88 Print a help message and exit.
89 -v, --version
91 Print version information and exit.
92 Box Options
94 --yesno text height width
96 A yes/no dialog box of size height rows by width columns will be
97 displayed. The string specified by text is displayed inside the
98 dialog box. If this string is too long to be fit in one line, it
99 will be automatically divided into multiple lines at appropriate
100 places. The text string may also contain the sub-string "\n" or
101 newline characters `\n' to control line breaking explicitly.
102 This dialog box is useful for asking questions that require the
103 user to answer either yes or no. The dialog box has a Yes but‐
104 ton and a No button, in which the user can switch between by
105 pressing the TAB key.
106 --msgbox text height width
108 A message box is very similar to a yes/no box. The only differ‐
109 ence between a message box and a yes/no box is that a message
110 box has only a single OK button. You can use this dialog box to
111 display any message you like. After reading the message, the
112 user can press the ENTER key so that whiptail will exit and the
113 calling shell script can continue its operation.
114 --infobox text height width
116 An info box is basically a message box. However, in this case,
117 whiptail will exit immediately after displaying the message to
118 the user. The screen is not cleared when whiptail exits, so that
119 the message will remain on the screen until the calling shell
120 script clears it later. This is useful when you want to inform
121 the user that some operations are carrying on that may require
122 some time to finish.
123 --inputbox text height width [init]
125 An input box is useful when you want to ask questions that re‐
126 quire the user to input a string as the answer. If init is sup‐
127 plied it is used to initialize the input string. When inputing
128 the string, the BACKSPACE key can be used to correct typing er‐
129 rors. If the input string is longer than the width of the dialog
130 box, the input field will be scrolled. On exit, the input string
131 will be printed on stderr.
132 --passwordbox text height width [init]
134 A password box is similar to an input box, except the text the
135 user enters is not displayed. This is useful when prompting for
136 passwords or other sensitive information. Be aware that if any‐
137 thing is passed in "init", it will be visible in the system's
138 process table to casual snoopers. Also, it is very confusing to
139 the user to provide them with a default password they cannot
140 see. For these reasons, using "init" is highly discouraged.
141 --textbox file height width
143 A text box lets you display the contents of a text file in a di‐
144 alog box. It is like a simple text file viewer. The user can
145 move through the file by using the UP/DOWN, PGUP/PGDN and
146 HOME/END keys available on most keyboards. If the lines are too
147 long to be displayed in the box, the LEFT/RIGHT keys can be used
148 to scroll the text region horizontally. For more convenience,
149 forward and backward searching functions are also provided.
150 --menu text height width menu-height [ tag item ] ...
152 As its name suggests, a menu box is a dialog box that can be
153 used to present a list of choices in the form of a menu for the
154 user to choose. Each menu entry consists of a tag string and an
155 item string. The tag gives the entry a name to distinguish it
156 from the other entries in the menu. The item is a short descrip‐
157 tion of the option that the entry represents. The user can move
158 between the menu entries by pressing the UP/DOWN keys, the first
159 letter of the tag as a hot-key. There are menu-height entries
160 displayed in the menu at one time, but the menu will be scrolled
161 if there are more entries than that. When whiptail exits, the
162 tag of the chosen menu entry will be printed on stderr.
163 --checklist text height width list-height [ tag item status ] ...
165 A checklist box is similar to a menu box in that there are mul‐
166 tiple entries presented in the form of a menu. You can select
167 and deselect items using the SPACE key. The initial on/off
168 state of each entry is specified by status. On exit, a list of
169 the tag strings of those entries that are turned on will be
170 printed on stderr.
171 --radiolist text height width list-height [ tag item status ] ...
174 A radiolist box is similar to a menu box. The only difference
175 is that you can indicate which entry is currently selected, by
176 setting its status to on.
177 --gauge text height width percent
180 A gauge box displays a meter along the bottom of the box. The
181 meter indicates a percentage. New percentages are read from
182 standard input, one integer per line. The meter is updated to
183 reflect each new percentage. If stdin is XXX, the first follow‐
184 ing line is a percentage and subsequent lines up to another XXX
185 are used for a new prompt. The gauge exits when EOF is reached
186 on stdin.
187
190 whiptail interprets arguments starting with a dash "-" as being argu‐
191 ments. To avoid this, and start some text in, for example, a menubox
192 item, with a dash, whiptail honours the getopt convention of accepting
193 the special argument "--" which means that all following arguments with
194 dashes are to be treated verbatim and not parsed as options.
195 If the specified height, width, or menu/list-height is zero, whiptail
197 will increase the values as needed in order to display all information.
198
201 Exit status is 0 if whiptail is exited by pressing the Yes or OK but‐
202 ton, and 1 if the No or Cancel button is pressed. Otherwise, if errors
203 occur inside whiptail or whiptail is exited by pressing the ESC key,
204 the exit status is -1.
205
207 Based on the man page for dialog(1) by:
208 Savio Lam (lam836@cs.cuhk.hk) - version 0.3
210 Stuart Herbert (S.Herbert@sheffield.ac.uk) - patch for version 0.4
212 Modifications for whiptail by:
214 Enrique Zanardi (ezanard@debian.org)
216 Alastair McKinstry (mckinstry@debian.org)
218Whiptail Version 0.52.5 31 January 2007 WHIPTAIL(1)