]>
Commit | Line | Data |
---|---|---|
941c26f4 | 1 | .TH WHIPTAIL 1 "31 January 2007" "Whiptail Version 0.52.5" |
feef2cb5 | 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 | [ | |
6a612632 | 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 | [ | |
feef2cb5 | 47 | .B \-\-noitem |
48 | [ | |
49 | ] | |
50 | .B \-\-output\-fd | |
51 | .I fd | |
52 | ] | |
53 | [ | |
54 | .B \-\-separate\-output | |
55 | ] | |
56 | [ | |
57 | .B \-\-scrolltext | |
58 | ] | |
45bffa7f | 59 | [ |
60 | .B \-\-topleft | |
61 | ] | |
feef2cb5 | 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 | |
6a612632 | 86 | .BI \-\-default\-item " string" |
feef2cb5 | 87 | Set the default item in a menu box. |
88 | Normally the first item in the box is the default. | |
89 | .TP | |
6c7007a6 | 90 | \fB\-\-fb\fR, \fB\-\-fullbuttons\fR |
feef2cb5 | 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 | |
6a612632 | 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 | |
feef2cb5 | 115 | .B \-\-noitem |
116 | The menu, checklist and radiolist widgets will display tags only, not | |
27261039 ML |
117 | the item strings. The menu widget still needs some items specified, |
118 | but checklist and radiolist expect only tag and status. | |
feef2cb5 | 119 | .TP |
6c7007a6 ML |
120 | .B \-\-notags |
121 | Don't display tags in the menu, checklist and radiolist widgets. | |
122 | .TP | |
feef2cb5 | 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 | |
45bffa7f | 147 | .BI \-\-topleft |
148 | Put window in top-left corner. | |
149 | .TP | |
6c7007a6 ML |
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 | |
feef2cb5 | 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 | |
e3a4e527 ML |
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. | |
feef2cb5 | 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. | |
22f3ce53 ML |
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 | ||
feef2cb5 | 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) |