Debian Codegraph @

upstream/debian-trixie/man1/dialog.1

raw
1 '\" t
2 .\" $Id: dialog.1,v 1.238 2024/03/07 21:49:36 tom Exp $
3 .\" Copyright 2005-2023,2024 Thomas E. Dickey
4 .\"
5 .\" This program is free software; you can redistribute it and/or modify
6 .\" it under the terms of the GNU Lesser General Public License, version 2.1
7 .\" as published by the Free Software Foundation.
8 .\"
9 .\" This program is distributed in the hope that it will be useful, but
10 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 .\" Lesser General Public License for more details.
13 .\"
14 .\" You should have received a copy of the GNU Lesser General Public
15 .\" License along with this program; if not, write to
16 .\" Free Software Foundation, Inc.
17 .\" 51 Franklin St., Fifth Floor
18 .\" Boston, MA 02110, USA.
19 .\"
20 .\" definitions for renaming
21 .ds p dialog
22 .ds l dialog
23 .ds L Dialog
24 .ds D DIALOG
25 .\"
26 .ie n .ds CW R
27 .el \{
28 .ie \n(.g .ds CW CR
29 .el .ds CW CW
30 .\}
31 .
32 .de ES
33 .ne 8
34 .IP
35 ..
36 .de Ex
37 .RS +7
38 .PP
39 .nf
40 .ft \*(CW
41 ..
42 .de Ee
43 .fi
44 .ft R
45 .RE
46 ..
47 .\" Bulleted paragraph
48 .de bP
49 .ie n .IP \(bu 4
50 .el .IP \(bu 2
51 ..
52 .ie \n(.g \{\
53 .ds `` \(lq
54 .ds '' \(rq
55 .ds ' \(aq
56 .\}
57 .el \{\
58 .ie t .ds `` ``
59 .el .ds `` ""
60 .ie t .ds '' ''
61 .el .ds '' ""
62 .ie t .ds ' \(aq
63 .el .ds ' '
64 .\}",
65 .
66 .TH \*D "" 2024-01-01 "" "User commands"
67 .SH NAME
68 dialog \-
69 display dialog boxes from shell scripts
70 .SH SYNOPSIS
71 \fB\*p \-\-clear\fP
72 .br
73 .BI "\*p \-\-create\-rc " file
74 .br
75 \fB\*p \-\-print\-maxsize\fP
76 .br
77 \fB\*p\fP
78 \fIcommon-options\fP
79 \fIbox-options\fP
80 .SH DESCRIPTION
81 \fB\*L\fP
82 is a program that will let you present a variety of questions or
83 display messages using dialog boxes from a shell script.
84 These types of dialog boxes are implemented
85 (though not all are necessarily compiled into \fB\*p\fR):
86 .RS
87 .LP
88 .nh
89 .na
90 .BR buildlist ", "
91 .BR calendar ", "
92 .BR checklist ", "
93 .BR dselect ", "
94 .BR editbox ", "
95 .BR form ", "
96 .BR fselect ", "
97 .BR gauge ", "
98 .BR infobox ", "
99 .BR inputbox ", "
100 .BR inputmenu ", "
101 .BR menu ", "
102 .BR mixedform ", "
103 .BR mixedgauge ", "
104 .BR msgbox " (message), "
105 .BR passwordbox ", "
106 .BR passwordform ", "
107 .BR pause ", "
108 .BR prgbox ", "
109 .BR programbox ", "
110 .BR progressbox ", "
111 .BR radiolist ", "
112 .BR rangebox ", "
113 .BR tailbox ", "
114 .BR tailboxbg ", "
115 .BR textbox ", "
116 .BR timebox ", "
117 .BR treeview ", and "
118 .BR yesno " (yes/no)."
119 .ad
120 .RE
121 .PP
122 You can put more than one dialog box into a script:
123 .bP
124 Use the "\fB\-\-and\-widget\fP" token to force \fB\*p\fP to proceed to the next
125 dialog unless you have pressed ESC to cancel, or
126 .bP
127 Simply add the tokens for the next dialog box, making a chain.
128 \*L stops chaining when the return code from a dialog is nonzero,
129 e.g., Cancel or No (see DIAGNOSTICS).
130 .PP
131 Some widgets, e.g., checklist, will write text to \fB\*p\fP's output.
132 Normally that is the standard error, but there are options for
133 changing this:
134 \*(``\fB\-\-output\-fd\fP\*('',
135 \*(``\fB\-\-stderr\fP\*('' and
136 \*(``\fB\-\-stdout\fP\*(''.
137 No text is written if the Cancel button (or ESC) is pressed;
138 \fB\*p\fP exits immediately in that case.
139 .
140 .\" ************************************************************************
141 .SH OPTIONS
142 All options begin with \*(``\fB\-\-\fP\*(''
143 (two ASCII hyphens,
144 for the benefit of those using systems with deranged locale support).
145 .PP
146 A \*(``\fB\-\-\fP\*('' by itself is used as an escape,
147 i.e., the next token on the command-line is not treated as an option.
148 This is different from \fBgetopt\fP(1),
149 which uses that token to treat the remaining tokens as \fIparameters\fP
150 rather than \fIoptions\fP.
151 .RS
152 .PP
153 .B \*p \-\-title \-\- \-\-Not an option
154 .br
155 .B \*p \-\-title This \-\- \-\-title is not an option
156 .RE
157 .PP
158 \fB\*L\fP
159 uses no \fIparameters\fP,
160 and uses its own \fIoptions\fP parser.
161 .PP
162 When a common (e.g., non-widget) option is repeated,
163 the last found is the one that is used.
164 Boolean options are handled specially so they can be cancelled,
165 by adding (or omitting) a \*(``no\*('' modifier
166 after the leading \*(``\fB\-\-\fP\*(''.
167 For instance, \fB\-\-no\-shadow\fP is documented here,
168 but \fB\-\-shadow\fP also is accepted.
169 .PP
170 The \*(``\fB\-\-args\fP\*('' option tells \fB\*p\fP to list the command-line
171 parameters to the standard error.
172 This is useful when debugging complex scripts using
173 the \*(``\fB\-\-\fP\*('' and \*(``\fB\-\-file\fP\*('',
174 since the command-line may be rewritten as these are expanded.
175 .PP
176 The \*(``\fB\-\-file\fP\*('' option tells \fB\*p\fP to read parameters from
177 the file named as its value.
178 .RS
179 .B \*p \-\-file \fIparameterfile
180 .RE
181 .PP
182 Blanks not within double-quotes are discarded
183 (use backslashes to quote single characters).
184 The result is inserted into the command-line,
185 replacing \*(``\fB\-\-file\fP\*('' and its option value.
186 Interpretation of the command-line resumes from that point.
187 If \fIparameterfile\fP begins with \*(``&\*('', \fB\*p\fP
188 interprets the following text as a file descriptor number
189 rather than a filename.
190 .PP
191 Most widgets accept \fIheight\fP and \fIwidth\fP parameters,
192 which can be used to automatically size the widget to accommodate
193 multi-line message \fIprompt\fP values:
194 .bP
195 If the parameter is negative,
196 \fB\*l\fP uses the screen's size.
197 .bP
198 If the parameter is zero,
199 \fB\*l\fP uses minimum size for the widget to display the \fIprompt\fP
200 and data.
201 .bP
202 Otherwise, \fB\*l\fP uses the given size for the widget.
203 .
204 .SS "\fBCommon Options\fP"
205 Most of the common options are reset before processing each widget.
206 .
207 .IP "\fB\-\-ascii\-lines"
208 Rather than draw graphics lines around boxes,
209 draw ASCII \*(``+\*('' and \*(``-\*('' in the same place.
210 See also \*(``\fB\-\-no\-lines\fR\*(''.
211 .
212 .IP "\fB\-\-aspect \fIratio"
213 This gives you some control over the box dimensions when using auto
214 sizing (specifying 0 for height and width).
215 It represents width / height.
216 The default is 9, which means 9 characters wide to every 1 line high.
217 .
218 .IP "\fB\-\-backtitle \fIbacktitle"
219 Specifies a
220 \fIbacktitle\fP
221 string to be displayed on the backdrop, at the top of the screen.
222 .
223 .IP "\fB\-\-begin \fIy x"
224 Specify the position of the upper left corner of a dialog box on the screen.
225 .
226 .IP "\fB\-\-cancel\-label \fIstring"
227 Override the label used for \*(``Cancel\*('' buttons.
228 .
229 .IP "\fB\-\-clear"
230 Clears the widget screen, keeping only the screen_color background.
231 Use this when you combine widgets
232 with \*(``\fB\-\-and\-widget\fR\*('' to erase the
233 contents of a previous widget on the screen, so it won't be seen
234 under the contents of a following widget.
235 Understand this as the complement of \*(``\fB\-\-keep\-window\fR\*(''.
236 To compare the effects, use these:
237 .
238 .ES
239 All three widgets visible, staircase effect, ordered 1,2,3:
240 .Ex
241 \*p \e
242 \-\-begin 2 2 \-\-yesno "" 0 0 \e
243 \-\-and\-widget \-\-begin 4 4 \-\-yesno "" 0 0 \e
244 \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0
245 .Ee
246 .
247 .ES
248 Only the last widget is left visible:
249 .Ex
250 \*p \e
251 \-\-clear \-\-begin 2 2 \-\-yesno "" 0 0 \e
252 \-\-and\-widget \-\-clear \-\-begin 4 4 \-\-yesno "" 0 0 \e
253 \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0
254 .Ee
255 .
256 .ES
257 All three widgets visible, staircase effect, ordered 3,2,1:
258 .Ex
259 \*p \e
260 \-\-keep\-window \-\-begin 2 2 \-\-yesno "" 0 0 \e
261 \-\-and\-widget \-\-keep\-window \-\-begin 4 4 \-\-yesno "" 0 0 \e
262 \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0
263 .Ee
264 .
265 .ES
266 First and third widget visible, staircase effect, ordered 3,1:
267 .Ex
268 \*p \e
269 \-\-keep\-window \-\-begin 2 2 \-\-yesno "" 0 0 \e
270 \-\-and\-widget \-\-clear \-\-begin 4 4 \-\-yesno "" 0 0 \e
271 \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0
272 .Ee
273 .IP
274 Note, if you want to restore original console colors and send your
275 cursor home after the dialog program has exited, use the \fBclear\fR(1)
276 command.
277 Conversely, if you want to clear the screen and send your cursor to
278 the lower left after the \fB\*p\fP program has exited, use the
279 \fB\-\-erase\-on\-exit\fR\ option.
280 .
281 .IP "\fB\-\-color-mode \fIcode"
282 Extend the \fB\-\-colors\fP option to the content of programbox, tailbox
283 and textbox.
284 Use code \*(``2\*('' for this feature.
285 .
286 .IP "\fB\-\-colors"
287 Interpret embedded \*(``\eZ\*('' sequences in the dialog text
288 by the following character,
289 which tells \fB\*p\fP to set colors or video attributes:
290 .RS
291 .bP
292 0 through 7 are the ANSI color numbers used in curses:
293 black,
294 red,
295 green,
296 yellow,
297 blue,
298 magenta,
299 cyan and
300 white respectively.
301 .bP
302 Bold is set by 'b', reset by 'B'.
303 .bP
304 Reverse is set by 'r', reset by 'R'.
305 .bP
306 Underline is set by 'u', reset by 'U'.
307 .bP
308 The settings are cumulative, e.g., \*(``\eZb\eZ1\*('' makes the following text
309 bold (perhaps bright) red.
310 .bP
311 Restore normal settings with \*(``\eZn\*(''.
312 .RE
313 .
314 .IP "\fB\-\-column\-separator \fIstring"
315 Tell \fB\*p\fP to split data for radio/checkboxes and menus on the
316 occurrences of the given string, and to align the split data into columns.
317 .
318 .IP "\fB\-\-cr\-wrap"
319 Interpret embedded newlines in the dialog text as a newline on the screen.
320 Otherwise, \fB\*p\fR will only wrap lines
321 where needed to fit inside the text box.
322 .IP
323 Even though you can control line breaks with this,
324 \fB\*L\fR will still wrap any lines that are too long for the width of the box.
325 Without cr-wrap, the layout of your text may be formatted to look nice
326 in the source code of your script without affecting the way it will
327 look in the dialog.
328 .IP
329 The \fIcr\-wrap\fP feature is implemented subject to these conditions:
330 .RS
331 .bP
332 the string contains \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option is
333 not used, or
334 .bP
335 the \fB\-\-trim\fP option is used.
336 .RE
337 .IP
338 For more information, see \fBWhitespace Options\fP.
339 .
340 .IP "\fB\-\-create\-rc \fIfile"
341 When
342 \fB\*p\fP
343 supports run-time configuration,
344 this can be used to dump a sample configuration file to the file specified
345 by
346 .IR file "."
347 .
348 .IP "\fB\-\-cursor\-off\-label"
349 Place the terminal cursor at the end of a button instead of on the
350 first character of the button label.
351 This is useful to reduce visual confusion when the cursor coloration
352 interacts poorly with the button-label text colors.
353 .
354 .IP "\fB\-\-date\-format \fIformat"
355 If the host provides \fBstrftime\fP,
356 this option allows you to specify the format of the date printed for
357 the \fB\-\-calendar\fP widget.
358 The time of day (hour, minute, second) are the current local time.
359 .
360 .IP "\fB\-\-defaultno"
361 Make the default value of the
362 \fByes/no\fP
363 box a
364 .BR No .
365 Likewise, treat the default button of widgets that provide
366 \*(``OK\*('' and \*(``Cancel\*(''
367 as a \fICancel\fP.
368 If \*(``\fB\-\-no\-cancel\fP\*('' or \*(``\fB\-\-visit\-items\fP\*('' are given
369 those options overrides this,
370 making the default button always \*(``Yes\*(''
371 (internally the same as \*(``OK\*('').
372 .
373 .IP "\fB\-\-default\-button \fIstring"
374 Set the default (preselected) button in a widget.
375 By preselecting a button,
376 a script makes it possible for the user to simply press \fIEnter\fP
377 to proceed through a dialog with minimum interaction.
378 .IP
379 The option's value is the name of the button:
380 .IR ok ,
381 .IR yes ,
382 .IR cancel ,
383 .IR no ,
384 .IR help "\ or"
385 .IR extra .
386 .IP
387 Normally the first button in each widget is the default.
388 The first button shown is determined by the widget
389 together with the \*(``\fB\-\-no\-ok\fP\*(''
390 and \*(``\fB\-\-no\-cancel\fP\*('' options.
391 If this option is not given, there is no default button assigned.
392 .
393 .IP "\fB\-\-default\-item \fIstring"
394 Set the default item in a checklist, form or menu box.
395 Normally the first item in the box is the default.
396 .
397 .IP "\fB\-\-erase\-on\-exit"
398 When \fB\*p\fP exits, remove the dialog widget, erasing the entire
399 screen to its native background color, and place the terminal cursor
400 at the lower left corner.
401 .
402 .IP "\fB\-\-exit\-label \fIstring"
403 Override the label used for \*(``EXIT\*('' buttons.
404 .
405 .IP "\fB\-\-extra\-button"
406 Show an extra button, between \*(``OK\*('' and \*(``Cancel\*('' buttons.
407 .IP
408 The extra button appears between \*(``Yes\*('' and \*(``No\*(''
409 for the \fIyesno\fP widget.
410 .
411 .IP "\fB\-\-extra\-label \fIstring"
412 Override the label used for \*(``Extra\*('' buttons.
413 Note: for inputmenu widgets, this defaults to \*(``Rename\*(''.
414 .
415 .IP "\fB\-\-help"
416 Prints the help message to the standard output and exits.
417 The help message is also printed if no options are given,
418 or if an unrecognized option is given.
419 .
420 .IP "\fB\-\-help\-button"
421 Show a help-button after \*(``OK\*('' and \*(``Cancel\*('' buttons
422 in boxes which have a list of tagged items
423 (i.e., checklist, radiolist, menu, and treeview boxes).
424 .IP
425 The help-button appears after \*(``Yes\*('' and \*(``No\*(''
426 for the \fIyesno\fP widget.
427 .IP
428 On exit, the return status indicates that the Help button was pressed.
429 \fB\*L\fP also writes a message to its output
430 after the token \*(``HELP\*('':
431 .RS
432 .bP
433 If "\fB\-\-item\-help\fR" is also given, the item-help text is written.
434 .bP
435 Otherwise, the item's tag (the first field) is written.
436 .RE
437 .IP
438 You can use the \fB\-\-help\-tags\fP option and/or set the DIALOG_ITEM_HELP
439 environment variable to modify these messages and exit-status.
440 .IP
441 This option can be applied to other widgets,
442 which have an \*(``OK\*('' button,
443 whether or not the \*(``Cancel\*('' button is used.
444 The return status and output are not treated specially for the other widgets;
445 the help-button is just an extra button.
446 .
447 .IP "\fB\-\-help\-label \fIstring"
448 Override the label used for \*(``Help\*('' buttons.
449 .
450 .IP "\fB\-\-help\-status"
451 If the help-button is selected,
452 writes the checklist, radiolist or form information
453 after the item-help \*(``HELP\*('' information.
454 This can be used to reconstruct the state of a checklist after processing
455 the help request.
456 .
457 .IP "\fB\-\-help\-tags"
458 Modify the messages written on exit for \fB\-\-help\-button\fP
459 by making them always just the item's tag.
460 This does not affect the exit status code.
461 .
462 .IP "\fB\-\-hfile \fIfilename"
463 Display the given file using a textbox when the user presses F1.
464 .
465 .IP "\fB\-\-hline \fIstring"
466 Display the given string centered at the bottom of the widget.
467 .
468 .IP "\fB\-\-ignore"
469 Ignore options that \fB\*p\fP does not recognize.
470 Some well-known ones such as \*(``\fB\-\-icon\fP\*('' are ignored anyway,
471 but this is a better choice for compatibility with other implementations.
472 .
473 .IP "\fB\-\-input\-fd \fIfd"
474 Read keyboard input from the given file descriptor.
475 Most \fB\*p\fR scripts read from the standard input,
476 but the gauge widget reads a pipe (which is always standard input).
477 Some configurations do not work properly when
478 \fB\*p\fP tries to reopen the terminal.
479 Use this option (with appropriate juggling of file-descriptors)
480 if your script must work in that type of environment.
481 .
482 .IP "\fB\-\-insecure"
483 Makes the password widget friendlier but less secure,
484 by echoing asterisks for each character.
485 .
486 .IP "\fB\-\-iso\-week"
487 Set the starting point for the week-number
488 shown in the \*(``\fB\-\-calendar\fP\*('' option
489 according to ISO-8601, which starts numbering
490 with the first week which includes a Thursday in January.
491 .
492 .IP "\fB\-\-item\-help"
493 Interpret the tags data for checklist, radiolist and menu boxes
494 adding a column which is displayed in the bottom line of the
495 screen, for the currently selected item.
496 .
497 .IP "\fB\-\-keep\-tite"
498 When built with \fBncurses\fP,
499 \fB\*p\fP normally checks to see if it is running in an \fBxterm\fP,
500 and in that case tries to suppress the initialization strings that
501 would make it switch to the alternate screen.
502 Switching between the normal and alternate screens
503 is visually distracting in a script which runs \fB\*p\fP
504 several times.
505 Use this option to allow \fB\*p\fP to use those initialization strings.
506 .
507 .IP "\fB\-\-keep\-window"
508 Normally when \fB\*p\fR performs several \fBtailboxbg\fR widgets
509 connected by \*(``\fB\-\-and\-widget\fR\*('',
510 it clears the old widget from the screen by painting over it.
511 Use this option to suppress that repainting.
512 .IP
513 At exit, \fB\*p\fR repaints all of the widgets which have been
514 marked with \*(``\fB\-\-keep\-window\fR\*('',
515 even if they are not \fBtailboxbg\fR widgets.
516 That causes them to be repainted in reverse order.
517 See the discussion of the \*(``\fB\-\-clear\fR\*('' option for examples.
518 .
519 .IP "\fB\-\-last\-key"
520 At exit, report the last key which the user entered.
521 This is the curses key code rather than a symbol or literal character,
522 and is only reported for keys which are bound to an action.
523 It can be used by scripts to distinguish between two keys which are
524 bound to the same action.
525 .
526 .IP "\fB\-\-max\-input \fIsize"
527 Limit input strings to the given size.
528 If not specified, the limit is 2048.
529 .
530 .IP "\fB\-\-no\-cancel"
531 Suppress the \*(``Cancel\*('' button in checklist, inputbox and menu box modes.
532 A script can still test if the user pressed the ESC key to cancel to quit.
533 .
534 .IP "\fB\-\-no\-collapse"
535 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
536 spaces to a single space for text which is displayed in a message boxes, etc.
537 Use this option to disable that feature.
538 Note that \fB\*p\fR will still wrap text,
539 subject to the \*(``\fB\-\-cr\-wrap\fR\*(''
540 and \*(``\fB\-\-trim\fR\*('' options.
541 .IP
542 The \fIno\-collapse\fP feature is implemented subject to these conditions:
543 .RS
544 .bP
545 the string contains \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option is
546 not used, or
547 .bP
548 the \fB\-\-trim\fP option is not used.
549 .RE
550 .IP
551 For more information, see \fBWhitespace Options\fP.
552 .
553 .IP "\fB\-\-no\-hot\-list"
554 Tells
555 \fB\*p\fP
556 to suppress the hotkey feature for lists, e.g., the checkbox, menus.
557 .IP
558 Normally, the first uppercase character of a list entry will be highlighted,
559 and typing that character will move the focus to that entry.
560 This option suppresses both the highlighting and the movement.
561 .IP
562 Hotkeys for buttons (\*(``OK\*('' , \*(``Cancel\*('', etc.) are unaffected.
563 .
564 .IP "\fB\-\-no\-items"
565 Some widgets (checklist, inputmenu, radiolist, menu) display a list
566 with two columns (a \*(``tag\*('' and \*(``item\*('',
567 i.e., \*(``description\*('').
568 This option tells \fB\*p\fP to read shorter rows,
569 omitting the \*(``item\*('' part of the list.
570 This is occasionally useful, e.g., if the tags provide enough information.
571 .IP
572 See also \fB\-\-no\-tags\fP.
573 If both options are given, this one is ignored.
574 .
575 .IP "\fB\-\-no\-kill"
576 Tells
577 \fB\*p\fP
578 to put the
579 \fBtailboxbg\fP
580 box in the background,
581 printing its process id to \fB\*p\fP's output.
582 SIGHUP is disabled for the background process.
583 .
584 .IP "\fB\-\-no-label \fIstring"
585 Override the label used for \*(``No\*('' buttons.
586 .
587 .IP "\fB\-\-no\-lines"
588 Rather than draw lines around boxes, draw spaces in the same place.
589 See also \*(``\fB\-\-ascii\-lines\fR\*(''.
590 .
591 .IP "\fB\-\-no\-mouse"
592 Do not enable the mouse.
593 .
594 .IP "\fB\-\-no\-nl\-expand"
595 Do not convert \*(``\en\*('' substrings of the message/prompt text into
596 literal newlines.
597 .IP
598 The \fIno\-nl\-expand\fP feature is used only if
599 the string contains \*(``\en\*('' so that there is something to convert.
600 .IP
601 For more information, see \fBWhitespace Options\fP.
602 .
603 .IP "\fB\-\-no\-ok"
604 Suppress the \*(``OK\*('' button, so that it is not displayed.
605 A script can still test if the user pressed
606 the \*(``Enter\*('' key to accept the data:
607 .RS
608 .bP
609 The \*(``Enter\*('' key is always handled as the \*(``OK\*('' button
610 when the \fB\-\-no\-ok\fP option is used.
611 That is, by default it is bound to the \fILEAVE\fP virtual key.
612 .IP
613 When \fB\-\-no\-ok\fP is not used,
614 you can use the the \fITab\fP key to move the cursor through the
615 fields and buttons on the widget.
616 In that case, the \*(``Enter\*('' key activates the current button
617 if the cursor is positioned on a button.
618 .bP
619 To provide for the case where you want to activate a button
620 when using \fB\-\-no\-ok\fP,
621 there is another virtual key \fILEAVE\fP,
622 which activates the current button.
623 By default, \fB^D\fP (EOF) is bound to that key.
624 .RE
625 .
626 .IP "\fB\-\-no\-shadow"
627 Suppress shadows that would be drawn to the right and bottom of each dialog box.
628 .
629 .IP "\fB\-\-no\-tags"
630 Some widgets (checklist, inputmenu, radiolist, menu) display a list
631 with two columns (a \*(``tag\*('' and \*(``description\*('').
632 The tag is useful for scripting, but may not help the user.
633 The \fB\-\-no\-tags\fP option (from Xdialog) may be used to suppress the
634 column of tags from the display.
635 Unlike the \fB\-\-no\-items\fP option,
636 this does not affect the data which is read from the script.
637 .IP
638 Xdialog does not display the tag column for the analogous buildlist
639 and treeview widgets; \fB\*p\fP does the same.
640 .IP
641 Normally \fB\*p\fP allows you to quickly move to entries on the displayed list,
642 by matching a single character to the first character of the tag.
643 When the \fB\-\-no\-tags\fP option is given, \fB\*p\fP matches against
644 the first character of the description.
645 In either case, the matchable character is highlighted.
646 .
647 .IP "\fB\-\-ok\-label \fIstring"
648 Override the label used for \*(``OK\*('' buttons.
649 .
650 .IP "\fB\-\-output\-fd \fIfd"
651 Direct output to the given file descriptor.
652 Most \fB\*p\fR scripts write to the standard error,
653 but error messages may also be written there, depending on your script.
654 .
655 .IP "\fB\-\-separator \fIstring"
656 .IP "\fB\-\-output\-separator \fIstring"
657 Specify a string that will separate the output on \fB\*p\fP's output from
658 checklists, rather than a newline (for \fB\-\-separate\-output\fP) or a space.
659 This applies to other widgets such as forms and editboxes which normally
660 use a newline.
661 .
662 .IP "\fB\-\-print\-maxsize"
663 Print the maximum size of dialog boxes, i.e., the screen size,
664 to \fB\*p\fP's output.
665 This may be used alone, without other options.
666 .
667 .IP "\fB\-\-print\-size"
668 Prints the size of each dialog box to \fB\*p\fP's output
669 when the box is initialized.
670 .
671 .IP "\fB\-\-print\-text\-only \fIstring [ height [ width ] ]"
672 Prints the string as it would be wrapped in a message box
673 to \fB\*p\fP's output.
674 .IP
675 Because the optional \fIheight\fP and \fIwidth\fP default to zero,
676 if they are omitted, \fB\*p\fP autosizes according to the screen dimensions.
677 .
678 .IP "\fB\-\-print\-text\-size \fIstring [ height [ width ] ]"
679 Prints the size of the string as it would be wrapped in a message box,
680 to \fB\*p\fP's output,
681 as
682 .Ex
683 height width
684 .Ee
685 .IP
686 Because the optional \fIheight\fP and \fIwidth\fP parameters default to zero,
687 if they are omitted, \fB\*p\fP autosizes according to the screen dimensions.
688 .
689 .IP "\fB\-\-print\-version"
690 Prints \fB\*p\fR's version to \fB\*p\fP's output.
691 This may be used alone, without other options.
692 It does not cause \fB\*l\fP to exit by itself.
693 .
694 .IP "\fB\-\-quoted"
695 Normally \fB\*p\fP quotes the strings returned by checklist's
696 as well as the item-help text.
697 Use this option to quote all string results as needed
698 (i.e., if the string contains whitespace or a single or double-quote character).
699 .
700 .IP "\fB\-\-reorder"
701 By default, the buildlist widget uses the same order for the output (right)
702 list as for the input (left).
703 Use this option to tell \fB\*p\fP to use the order
704 in which a user adds selections to the output list.
705 .
706 .IP "\fB\-\-scrollbar"
707 For widgets holding a scrollable set of data,
708 draw a scrollbar on its right-margin.
709 This does not respond to the mouse.
710 .
711 .IP "\fB\-\-separate\-output"
712 For certain widgets (buildlist, checklist, treeview),
713 output result one line at a time, with no quoting.
714 This facilitates parsing by another program.
715 .
716 .IP "\fB\-\-separate\-widget \fIstring"
717 Specify a string that will separate the output on \fB\*p\fP's output from
718 each widget.
719 This is used to simplify parsing the result of a dialog with several widgets.
720 If this option is not given,
721 the default separator string is a tab character.
722 .
723 .IP "\fB\-\-single\-quoted"
724 Use single-quoting as needed (and no quotes if unneeded) for the
725 output of checklist's as well as the item-help text.
726 .IP
727 If this option is not set, \fB\*p\fP may use double quotes around each item.
728 In either case,
729 \fB\*p\fP adds backslashes to make the output useful in shell scripts.
730 .IP
731 Single quotes would be needed if
732 the string contains whitespace or a single or double-quote character.
733 .
734 .IP "\fB\-\-size\-err"
735 Check the resulting size of a dialog box before trying to use it,
736 printing the resulting size if it is larger than the screen.
737 (This option is obsolete, since all new-window calls are checked).
738 .
739 .IP "\fB\-\-sleep \fIsecs"
740 Sleep (delay) for the given number of seconds after processing a dialog box.
741 .
742 .IP "\fB\-\-stderr"
743 Direct output to the standard error.
744 This is the default, since curses normally writes screen updates to
745 the standard output.
746 .
747 .IP "\fB\-\-stdout"
748 Direct output to the standard output.
749 This option is provided for compatibility with Xdialog,
750 however using it in portable scripts is not recommended,
751 since curses normally writes its screen updates to the standard output.
752 If you use this option, \fB\*p\fR attempts to reopen the terminal
753 so it can write to the display.
754 Depending on the platform and your environment, that may fail.
755 .
756 .IP "\fB\-\-tab\-correct"
757 Convert each tab character to one or more spaces
758 (for the \fBtextbox\fP widget; otherwise to a single space).
759 Otherwise, tabs are rendered according to the curses library's interpretation.
760 The \fB\-\-no\-collapse\fP option disables tab expansion.
761 .
762 .IP "\fB\-\-tab\-len \fIn"
763 Specify the number of spaces that a tab character occupies if the
764 \*(``\fB\-\-tab\-correct\fP\*('' option is given.
765 The default is 8.
766 This option is only effective for the \fBtextbox\fP widget.
767 .
768 .IP "\fB\-\-time\-format \fIformat"
769 If the host provides \fBstrftime\fP,
770 this option allows you to specify the format of the time printed for
771 the \fB\-\-timebox\fP widget.
772 The day, month, year values in this case are for the current local time.
773 .
774 .IP "\fB\-\-timeout \fIsecs"
775 Timeout if no user response within the given number of seconds.
776 A timeout of zero seconds is ignored.
777 .IP
778 Normally a timeout causes an ESC character to be entered in the current widget,
779 cancelling it.
780 Other widgets may still be on the screen;
781 these are not cancelled.
782 Set the \fBDIALOG_TIMEOUT\fP environment variable to tell \fB\*l\fP to
783 directly exit instead, i.e., cancelling all widgets on the screen.
784 .IP
785 This option is ignored by the \*(``\fB\-\-pause\fP\*('' widget.
786 It is also overridden
787 if the background \*(``\fB\-\-tailboxbg\fP\*('' option is used
788 to set up multiple concurrent widgets.
789 .
790 .IP "\fB\-\-title \fItitle"
791 Specifies a
792 \fItitle\fP
793 string to be displayed at the top of the dialog box.
794 .
795 .IP "\fB\-\-trace \fIfilename"
796 logs the command-line parameters,
797 keystrokes and other information to the given file.
798 If \fB\*l\fP reads a configure file, it is logged as well.
799 Piped input to the \fIgauge\fP widget is logged.
800 Use control/T to log a picture of the current dialog window.
801 .IP
802 The \fB\*p\fR program handles some command-line parameters specially,
803 and removes them from the parameter list as they are processed.
804 For example, if the first option is \fB\-\-trace\fP,
805 then that is processed (and removed) before \fB\*p\fR initializes the display.
806 .
807 .IP "\fB\-\-week\-start \fIday"
808 sets the starting day for the week,
809 used in the \*(``\fB\-\-calendar\fP\*('' option.
810 The \fIday\fP parameter can be
811 .RS
812 .bP
813 a number (0 to 6, Sunday through Saturday using POSIX) or
814 .bP
815 the special value \*(``locale\*('' (this works with systems using glibc,
816 providing an extension to the \fBlocale\fP command,
817 the \fBfirst_weekday\fP value).
818 .bP
819 a string matching one of the abbreviations for the day of the week
820 shown in the \fBcalendar\fP widget, e.g., \*(``Mo\*('' for \*(``Monday\*(''.
821 .RE
822 .
823 .IP "\fB\-\-trim"
824 eliminate leading blanks,
825 trim literal newlines and repeated blanks from message text.
826 .IP
827 The \fItrim\fP feature is implemented subject to these conditions:
828 .RS
829 .bP
830 the string does not contain \*(``\en\*('' or
831 .bP
832 the \fB\-\-no\-nl\-expand\fP option is used.
833 .RE
834 .IP
835 For more information, see \fBWhitespace Options\fP.
836 .
837 .IP
838 See also the \*(``\fB\-\-cr\-wrap\fR\*(''
839 and \*(``\fB\-\-no\-collapse\fR\*('' options.
840 .
841 .IP "\fB\-\-version"
842 Prints \fB\*p\fR's version to the standard output, and exits.
843 See also \*(``\fB\-\-print\-version\fP\*(''.
844 .
845 .IP "\fB\-\-visit\-items"
846 Modify the tab-traversal of checklist, radiolist, menubox and inputmenu
847 to include the list of items as one of the states.
848 This is useful as a visual aid,
849 i.e., the cursor position helps some users.
850 .IP
851 When this option is given, the cursor is initially placed on the list.
852 Abbreviations (the first letter of the tag) apply to the list items.
853 If you tab to the button row, abbreviations apply to the buttons.
854 .
855 .IP "\fB\-\-yes-label \fIstring"
856 Override the label used for \*(``Yes\*('' buttons.
857 .
858 .\" ************************************************************************
859 .SS "Box Options"
860 All dialog boxes have at least three parameters:
861 .TP 7
862 \fItext\fP
863 the caption or contents of the box.
864 .TP 7
865 \fIheight\fP
866 the height of the dialog box.
867 .TP 7
868 \fIwidth\fP
869 the width of the dialog box.
870 .PP
871 Other parameters depend on the box type.
872 .
873 .
874 .IP "\fB\-\-buildlist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
875 A \fBbuildlist\fP dialog displays two lists, side-by-side.
876 The list on the left shows unselected items.
877 The list on the right shows selected items.
878 As items are selected or unselected, they move between the lists.
879 .IP
880 Use a carriage return or the \*(``OK\*('' button to accept the current value
881 in the selected-window and exit.
882 The results are written using the order displayed in the selected-window.
883 .IP
884 The initial on/off state of each entry is specified by
885 .IR status "."
886 .IP
887 The dialog behaves like a \fBmenu\fP, using the \fB\-\-visit\-items\fP
888 to control whether the cursor is allowed to visit the lists directly.
889 .RS
890 .bP
891 If \fB\-\-visit\-items\fP is not given,
892 tab-traversal uses two states (OK/Cancel).
893 .bP
894 If \fB\-\-visit\-items\fP is given,
895 tab-traversal uses four states (Left/Right/OK/Cancel).
896 .RE
897 .IP
898 Whether or not \fB\-\-visit\-items\fP is given,
899 it is possible to move the highlight between the two lists using
900 the default \*(``^\*('' (left-column) and \*(``$\*('' (right-column) keys.
901 .IP
902 On exit, a list of the \fItag\fP
903 strings of those entries that are turned on
904 will be printed on \fB\*p\fP's output.
905 .IP
906 If the "\fB\-\-separate\-output\fP" option is not given,
907 the strings will be quoted as needed
908 to make it simple for scripts to separate them.
909 By default, this uses double-quotes, as needed.
910 See the \*(``\fB\-\-single\-quoted\fP\*('' option,
911 which modifies the quoting behavior.
912 .
913 .IP "\fB\-\-calendar \fItext height width day month year"
914 A \fBcalendar\fP box displays
915 month, day and year in separately adjustable windows.
916 If the values for day, month or year are missing or negative,
917 the current date's corresponding values are used.
918 You can increment or decrement any of those using the
919 left-, up-, right-, and down-arrows.
920 Use vi-style h, j, k and l for moving around the array of days in a month.
921 Use tab or backtab to move between windows.
922 If the year is given as zero, the current date is used as an initial value.
923 .IP
924 On exit, the date is printed in the form day/month/year.
925 The format can be overridden using the \fB\-\-date\-format\fP option.
926 .
927 .IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
928 A \fBchecklist\fP box is similar to a \fBmenu\fP box;
929 there are multiple entries presented in the form of a menu.
930 Another difference is
931 that you can indicate which entry is currently selected, by setting its
932 .IR status " to " on "."
933 Instead of choosing
934 one entry among the entries, each entry can be turned on or off by the user.
935 The initial on/off state of each entry is specified by
936 .IR status "."
937 .IP
938 On exit, a list of the \fItag\fP
939 strings of those entries that are turned on
940 will be printed on \fB\*p\fP's output.
941 .IP
942 If the \*(``\fB\-\-separate\-output\fP\*('' option is not given,
943 the strings will be quoted as needed
944 to make it simple for scripts to separate them.
945 By default, this uses double-quotes (as needed).
946 See the \*(``\fB\-\-single\-quoted\fP\*('' option,
947 which modifies the quoting behavior.
948 .
949 .IP "\fB\-\-dselect \fIfilepath height width\fR"
950 The directory-selection dialog displays a text-entry window
951 in which you can type a directory,
952 and above that a windows with directory names.
953 .IP
954 Here
955 \fBfilepath\fP
956 can be a filepath in which case the directory window
957 will display the contents of the path and the text-entry window will contain
958 the preselected directory.
959 .IP
960 Use tab or arrow keys to move between the windows.
961 Within the directory window, use the up/down arrow keys
962 to scroll the current selection.
963 Use the space-bar to copy the current selection into the text-entry
964 window.
965 .IP
966 Typing any printable characters switches focus to the text-entry window,
967 entering that character as well as scrolling the directory
968 window to the closest match.
969 .IP
970 Use a carriage return or the \*(``OK\*('' button to accept the current value
971 in the text-entry window and exit.
972 .IP
973 On exit, the contents of the text-entry window are written
974 to \fB\*p\fP's output.
975 .
976 .IP "\fB\-\-editbox \fIfilepath height width\fR"
977 The edit-box dialog displays a copy of the file.
978 You may edit it using
979 the \fIbackspace\fP, \fIdelete\fP and cursor keys
980 to correct typing errors.
981 It also recognizes pageup/pagedown.
982 Unlike the \fB\-\-inputbox\fP,
983 you must tab to the \*(``OK\*('' or \*(``Cancel\*('' buttons
984 to close the dialog.
985 Pressing the \*(``Enter\*('' key within the box will split
986 the corresponding line.
987 .IP
988 On exit, the contents of the edit window are written to \fB\*p\fP's output.
989 .
990 .nf
991 .IP "\fB\-\-form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
992 .fi
993 The \fBform\fP dialog displays a form consisting of labels and fields,
994 which are positioned on a scrollable window by coordinates given in the script.
995 The field length \fIflen\fR and input-length \fIilen\fR tell how long
996 the field can be.
997 The former defines the length shown for a selected field,
998 while the latter defines the permissible length of the data entered in the
999 field.
1000 .RS
1001 .bP
1002 If \fIflen\fR is zero, the corresponding field cannot be altered.
1003 and the contents of the field determine the displayed-length.
1004 .bP
1005 If \fIflen\fR is negative, the corresponding field cannot be altered,
1006 and the negated value of \fIflen\fR is used as the displayed-length.
1007 .bP
1008 If \fIilen\fR is zero, it is set to \fIflen\fR.
1009 .RE
1010 .IP
1011 Use up/down arrows (or control/N, control/P) to move between fields.
1012 Use tab to move between windows.
1013 .IP
1014 On exit, the contents of the form-fields are written to \fB\*p\fP's output,
1015 each field separated by a newline.
1016 The text used to fill non-editable fields
1017 (\fIflen\fR is zero or negative)
1018 is not written out.
1019 .
1020 .
1021 .IP "\fB\-\-fselect \fIfilepath height width\fR"
1022 The \fBfselect\fP (file-selection) dialog displays a text-entry window
1023 in which you can type a filename (or directory),
1024 and above that two windows with directory names and filenames.
1025 .IP
1026 Here
1027 \fBfilepath\fP
1028 can be a filepath in which case the file and directory windows
1029 will display the contents of the path and the text-entry window will contain
1030 the preselected filename.
1031 .IP
1032 Use tab or arrow keys to move between the windows.
1033 Within the directory or filename windows, use the up/down arrow keys
1034 to scroll the current selection.
1035 Use the space-bar to copy the current selection into the text-entry
1036 window.
1037 .IP
1038 Typing any printable characters switches focus to the text-entry window,
1039 entering that character as well as scrolling the directory and filename
1040 windows to the closest match.
1041 .IP
1042 Typing the space character forces \fB\*p\fP to complete the current
1043 name (up to the point where there may be a match against more than one
1044 entry).
1045 .IP
1046 Use a carriage return or the \*(``OK\*('' button to accept the current value
1047 in the text-entry window and exit.
1048 .IP
1049 On exit, the contents of the text-entry window are written
1050 to \fB\*p\fP's output.
1051 .
1052 .
1053 .IP "\fB\-\-gauge \fItext height width [percent]\fR"
1054 A
1055 \fBgauge\fP
1056 box displays a meter along the bottom of the box.
1057 The meter indicates the percentage.
1058 New percentages are read from
1059 standard input, one integer per line.
1060 The meter is updated
1061 to reflect each new percentage.
1062 If the standard input reads the string \*(``XXX\*('',
1063 then the first line following is taken as an integer percentage,
1064 then subsequent lines up to another \*(``XXX\*('' are used for a new prompt.
1065 The gauge exits when EOF is reached on the standard input.
1066 .IP
1067 The \fIpercent\fR value denotes the initial percentage shown in the meter.
1068 If not specified, it is zero.
1069 .IP
1070 On exit, no text is written to \fB\*p\fP's output.
1071 The widget accepts no input, so the exit status is always OK.
1072 .
1073 .
1074 .IP "\fB\-\-infobox \fItext height width"
1075 An \fBinfo\fP box is basically a \fBmessage\fP box.
1076 However, in this case, \fB\*p\fP
1077 will exit immediately after displaying the message to the user.
1078 The screen is not cleared when \fB\*p\fP
1079 exits, so that the message will remain on the screen until the calling
1080 shell script clears it later.
1081 This is useful when you want to inform
1082 the user that some operations are carrying on that may require some
1083 time to finish.
1084 .IP
1085 On exit, no text is written to \fB\*p\fP's output.
1086 An OK exit status is returned.
1087 .
1088 .
1089 .IP "\fB\-\-inputbox \fItext height width [init]"
1090 An
1091 \fBinput\fP
1092 box is useful when you want to ask questions that
1093 require the user to input a string as the answer.
1094 If init is supplied
1095 it is used to initialize the input string.
1096 When entering the string,
1097 the \fIbackspace\fP, \fIdelete\fP and cursor keys
1098 can be used to correct typing errors.
1099 If the input string is longer than
1100 can fit in the dialog box, the input field will be scrolled.
1101 .IP
1102 On exit, the input string will be printed on \fB\*p\fP's output.
1103 .
1104 .
1105 .IP "\fB\-\-inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
1106 An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box.
1107 There are only a few differences between them:
1108 .RS
1109 .TP 4
1110 1.
1111 The entries are not automatically centered but left adjusted.
1112 .TP
1113 2.
1114 An extra button (called \fIRename\/\fP) is implied to rename
1115 the current item when it is pressed.
1116 .TP
1117 3.
1118 It is possible to rename the current entry by pressing the
1119 \fIRename\fP
1120 button.
1121 Then \fB\*p\fP will write the following on \fB\*p\fP's output.
1122 .IP
1123 RENAMED <tag> <item>
1124 .RE
1125 .
1126 .
1127 .IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
1128 As its name suggests, a
1129 \fBmenu\fP
1130 box is a dialog box that can be used to present a list of choices in
1131 the form of a menu for the user to choose.
1132 Choices are displayed in the order given.
1133 Each menu entry consists of a \fItag\fP string and an \fIitem\fP string.
1134 The \fItag\fP
1135 gives the entry a name to distinguish it from the other entries in the
1136 menu.
1137 The \fIitem\fP is a short description of the option that the entry represents.
1138 The user can move between the menu entries by pressing the
1139 cursor keys, the first letter of the \fItag\fP
1140 as a hot-key, or the number keys \fI1\fP through \fI9\fP.
1141 There are \fImenu-height\fP
1142 entries displayed in the menu at one time, but the menu will be
1143 scrolled if there are more entries than that.
1144 .IP
1145 On exit the \fItag\fP
1146 of the chosen menu entry will be printed on \fB\*p\fP's output.
1147 If the \*(``\fB\-\-help\-button\fR\*('' option is given, the corresponding help
1148 text will be printed if the user selects the help button.
1149 .
1150 .nf
1151 .IP "\fB\-\-mixedform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen itype \fR] \fI..."
1152 .fi
1153 The \fBmixedform\fP dialog displays a form consisting of labels and fields,
1154 much like the \fB\-\-form\fP dialog.
1155 It differs by adding a field-type parameter to each field's description.
1156 Each bit in the type denotes an attribute of the field:
1157 .RS
1158 .TP 5
1159 1
1160 hidden, e.g., a password field.
1161 .TP 5
1162 2
1163 readonly, e.g., a label.
1164 .RE
1165 .
1166 .IP "\fB\-\-mixedgauge \fItext height width percent \fR[ \fItag1 item1 \fR] \fI..."
1167 A \fBmixedgauge\fP box displays a meter along the bottom of the box.
1168 The meter indicates the percentage.
1169 .IP
1170 It also displays a list of the \fItag\/\fP- and \fIitem\/\fP-values at the
1171 top of the box.
1172 See \*l(3) for the tag values.
1173 .IP
1174 The \fItext\fP is shown as a caption between the list and meter.
1175 The \fIpercent\fR value denotes the initial percentage shown in the meter.
1176 .IP
1177 No provision is made for reading data from the standard input as \fB\-\-gauge\fP
1178 does.
1179 .IP
1180 On exit, no text is written to \fB\*p\fP's output.
1181 The widget accepts no input, so the exit status is always OK.
1182 .
1183 .IP "\fB\-\-msgbox \fItext height width"
1184 A \fBmessage\fP box is very similar to a \fByes/no\fP box.
1185 The only difference between a \fBmessage\fP box and a \fByes/no\fP
1186 box is that a \fBmessage\fP box has only a single \fBOK\fP button.
1187 You can use this dialog box to display any message you like.
1188 After reading the message, the user can press the \fIENTER\fP key so that
1189 \fB\*p\fP will exit and the calling shell script can continue its operation.
1190 .IP
1191 If the message is too large for the space,
1192 \fB\*p\fP may allow you to scroll it,
1193 provided that the underlying curses implementation is capable enough.
1194 In this case, a percentage is shown in the base of the widget.
1195 .IP
1196 On exit, no text is written to \fB\*p\fP's output.
1197 Only an \*(``OK\*('' button is provided for input,
1198 but an ESC exit status may be returned.
1199 .
1200 .IP "\fB\-\-pause \fItext height width seconds\fR"
1201 A
1202 \fBpause\fP
1203 box displays a meter along the bottom of the box.
1204 The meter indicates how many seconds remain until the end of the pause.
1205 The pause exits when timeout is reached
1206 or the user presses the OK button
1207 (status OK)
1208 or the user presses the CANCEL button
1209 or Esc key.
1210 .IP "\fB\-\-passwordbox \fItext height width [init]"
1211 A \fBpassword\fP box is similar to an input box,
1212 except that the text the user enters is not displayed.
1213 This is useful when prompting for passwords or other
1214 sensitive information.
1215 Be aware that if anything is passed in \*(``init\*('', it
1216 will be visible in the system's process table to casual snoopers.
1217 Also, it
1218 is very confusing to the user to provide them with a default password they
1219 cannot see.
1220 For these reasons, using \*(``init\*('' is highly discouraged.
1221 See \*(``\fB\-\-insecure\fP\*('' if you do not care about your password.
1222 .IP
1223 On exit, the input string will be printed on \fB\*p\fP's output.
1224 .
1225 .
1226 .nf
1227 .IP "\fB\-\-passwordform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
1228 .fi
1229 This is identical to \fB\-\-form\fP except that all text fields are
1230 treated as \fBpassword\fP widgets rather than \fBinputbox\fP widgets.
1231 .
1232 .
1233 .IP "\fB\-\-prgbox \fItext command height width"
1234 .IP "\fB\-\-prgbox \fIcommand height width"
1235 A \fBprgbox\fP is very similar to a \fBprogrambox\fP.
1236 .IP
1237 This dialog box is used to display the output of a command that is
1238 specified as an argument to \fBprgbox\fP.
1239 .IP
1240 After the command completes, the user can press the \fIENTER\fP key so that
1241 \fB\*l\fP will exit and the calling shell script can continue its operation.
1242 .IP
1243 If four parameters are given, it displays the text under the title,
1244 delineated from the scrolling file's contents.
1245 If only three parameters are given, this text is omitted.
1246 .
1247 .
1248 .IP "\fB\-\-programbox \fItext height width"
1249 .IP "\fB\-\-programbox \fIheight width"
1250 A \fBprogrambox\fP is very similar to a \fBprogressbox\fP.
1251 The only difference between a \fBprogram\fP box and a \fBprogress\fP
1252 box is that a \fBprogram\fP box displays an \fBOK\fP button
1253 (but only after the command completes).
1254 .IP
1255 This dialog box is used to display the piped output of a command.
1256 After the command completes, the user can press the \fIENTER\fP key so that
1257 \fB\*l\fP will exit and the calling shell script can continue its operation.
1258 .IP
1259 If three parameters are given, it displays the text under the title,
1260 delineated from the scrolling file's contents.
1261 If only two parameters are given, this text is omitted.
1262 .
1263 .
1264 .IP "\fB\-\-progressbox \fItext height width"
1265 .IP "\fB\-\-progressbox \fIheight width"
1266 A \fBprogressbox\fP is similar to an \fBtailbox\fP,
1267 except that
1268 .RS
1269 .TP 3
1270 a) rather than displaying the contents of a file,
1271 it displays the piped output of a command and
1272 .TP 3
1273 b) it will exit when it reaches the end of the file
1274 (there is no \*(``OK\*('' button).
1275 .RE
1276 .IP
1277 If three parameters are given, it displays the text under the title,
1278 delineated from the scrolling file's contents.
1279 If only two parameters are given, this text is omitted.
1280 .
1281 .
1282 .IP "\fB\-\-radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
1283 A \fBradiolist\fP box is similar to a \fBmenu\fP box.
1284 The only difference is
1285 that you can indicate which entry is currently selected, by setting its
1286 .IR status " to " on "."
1287 .IP
1288 On exit, the tag of the selected item is written to \fB\*p\fP's output.
1289 .
1290 .
1291 .nf
1292 .IP "\fB\-\-rangebox \fItext height width min-value max-value default-value"
1293 .fi
1294 Allow the user to select from a range of values, e.g., using a slider.
1295 The dialog shows the current value as a bar (like the gauge dialog).
1296 Tabs or arrow keys move the cursor between the buttons and the value.
1297 When the cursor is on the value,
1298 you can edit it by:
1299 .RS
1300 .TP 5
1301 left/right cursor movement to select a digit to modify
1302 .TP 5
1303 +/-
1304 characters to increment/decrement the digit by one
1305 .TP 5
1306 0 through 9
1307 to set the digit to the given value
1308 .RE
1309 .IP
1310 Some keys are also recognized in all cursor positions:
1311 .RS
1312 .TP 5
1313 home/end
1314 set the value to its maximum or minimum
1315 .TP 5
1316 pageup/pagedown
1317 increment the value so that the slider moves by one column
1318 .RE
1319 .
1320 .
1321 .IP "\fB\-\-tailbox \fIfile height width"
1322 Display text from a file in a dialog box,
1323 as in a \*(``tail -f\*('' command.
1324 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1325 A '0' resets the scrolling.
1326 .IP
1327 On exit, no text is written to \fB\*p\fP's output.
1328 Only an \*(``OK\*('' button is provided for input,
1329 but an ESC exit status may be returned.
1330 .
1331 .
1332 .IP "\fB\-\-tailboxbg \fIfile height width"
1333 Display text from a file in a dialog box as a background task,
1334 as in a \*(``tail -f &\*('' command.
1335 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1336 A '0' resets the scrolling.
1337 .IP
1338 \*L treats the background task specially if there are other
1339 widgets (\fB\-\-and\-widget\fP) on the screen concurrently.
1340 Until those widgets are closed (e.g., an \*(``OK\*(''),
1341 \fB\*p\fP will perform all of the tailboxbg widgets in the same process,
1342 polling for updates.
1343 You may use a tab to traverse between the widgets on the screen,
1344 and close them individually, e.g., by pressing \fIENTER\fP.
1345 Once the non-tailboxbg widgets are closed,
1346 \fB\*p\fP forks a copy of itself into the background,
1347 and prints its process id if the \*(``\fB\-\-no\-kill\fP\*('' option
1348 is given.
1349 .IP
1350 On exit, no text is written to \fB\*p\fP's output.
1351 Only an \*(``EXIT\*('' button is provided for input,
1352 but an ESC exit status may be returned.
1353 .IP
1354 NOTE:
1355 Older versions of \fB\*p\fP forked immediately and attempted to
1356 update the screen individually.
1357 Besides being bad for performance,
1358 it was unworkable.
1359 Some older scripts may not work properly with the polled scheme.
1360 .
1361 .
1362 .IP "\fB\-\-textbox \fIfile height width"
1363 A
1364 \fBtext\fP
1365 box lets you display the contents of a text file in a dialog box.
1366 It is like a simple text file viewer.
1367 The user can move through the file by using the
1368 cursor, page-up, page-down
1369 and \fIHOME/END\fR keys available on most keyboards.
1370 If the lines are too long to be displayed in the box,
1371 the \fILEFT/RIGHT\fP
1372 keys can be used to scroll the text region horizontally.
1373 You may also use vi-style keys h, j, k, and l in place of the cursor keys,
1374 and B or N in place of the page-up and page-down keys.
1375 Scroll up/down using vi-style 'k' and 'j', or arrow-keys.
1376 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1377 A '0' resets the left/right scrolling.
1378 For more convenience,
1379 vi-style forward and backward searching functions are also provided.
1380 .IP
1381 On exit, no text is written to \fB\*p\fP's output.
1382 Only an \*(``EXIT\*('' button is provided for input,
1383 but an ESC exit status may be returned.
1384 .
1385 .
1386 .IP "\fB\-\-timebox \fItext height [width hour minute second]"
1387 A dialog is displayed which allows you to select hour, minute and second.
1388 If the values for hour, minute or second are missing or negative,
1389 the current date's corresponding values are used.
1390 You can increment or decrement any of those using the
1391 left-, up-, right- and down-arrows.
1392 Use tab or backtab to move between windows.
1393 .IP
1394 On exit, the result is printed in the form hour:minute:second.
1395 The format can be overridden using the \fB\-\-time\-format\fP option.
1396 .
1397 .
1398 .IP "\fB\-\-treeview \fItext height width list-height \fR[ \fItag item status depth \fR] \fI..."
1399 Display data organized as a tree.
1400 Each group of data contains a tag,
1401 the text to display for the item,
1402 its status (\*(``on\*('' or \*(``off\*('')
1403 and the depth of the item in the tree.
1404 .IP
1405 Only one item can be selected (like the \fBradiolist\fP).
1406 The tag is not displayed.
1407 .IP
1408 On exit, the tag of the selected item is written to \fB\*p\fP's output.
1409 .
1410 .
1411 .IP "\fB\-\-yesno \fItext height width"
1412 A \fByes/no\fP dialog box of
1413 size \fIheight\fP rows by \fIwidth\fP columns will be displayed.
1414 The string specified by
1415 \fItext\fP
1416 is displayed inside the dialog box.
1417 If this string is too long to fit
1418 in one line, it will be automatically divided into multiple lines at
1419 appropriate places.
1420 The
1421 \fItext\fP
1422 string can also contain the sub-string
1423 .RI """" \en """"
1424 or newline characters
1425 .RI ` \en '
1426 to control line breaking explicitly.
1427 This dialog box is useful for
1428 asking questions that require the user to answer either yes or no.
1429 The dialog box has a
1430 \fBYes\fP
1431 button and a
1432 \fBNo\fP
1433 button, in which the user can switch between by pressing the
1434 .IR TAB " key."
1435 .IP
1436 On exit, no text is written to \fB\*p\fP's output.
1437 In addition to the \*(``Yes\*('' and \*(``No\*('' exit codes (see DIAGNOSTICS)
1438 an ESC exit status may be returned.
1439 .IP
1440 The codes used for \*(``Yes\*('' and \*(``No\*(''
1441 match those used for \*(``OK\*('' and \*(``Cancel\*('',
1442 internally no distinction is made.
1443 .
1444 .\" ************************************************************************
1445 .SS "Obsolete Options"
1446 .\" from cdialog 0.9a (Pako)
1447 .IP "\fB\-\-beep"
1448 This was used to tell the original cdialog that it should make a beep
1449 when the separate processes of the tailboxbg widget would repaint the screen.
1450 .
1451 .\" from cdialog 0.9a (Pako)
1452 .IP "\fB\-\-beep\-after"
1453 Beep after a user has completed a widget by pressing one of the buttons.
1454 .
1455 .\" ************************************************************************
1456 .SS "Whitespace Options"
1457 These options can be used to transform whitespace (space, tab, newline)
1458 as dialog reads the script:
1459 .RS
1460 .BR \-\-cr\-wrap ,
1461 .BR \-\-no\-collapse ,
1462 .BR \-\-no\-nl\-expand ", and"
1463 .B \-\-trim
1464 .RE
1465 .PP
1466 The options are not independent:
1467 .bP
1468 \fB\*L\fP checks if the script contains at least one \*(``\en\*(''
1469 and (unless \fB\-\-no\-nl\-expand\fP is set) will ignore the
1470 \fB\-\-no\-collapse\fP and \fB\-\-trim\fP options.
1471 .bP
1472 After checking for \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option,
1473 \fB\*l\fP handles the \fB\-\-trim\fP option.
1474 .IP
1475 If the \fB\-\-trim\fP option takes effect,
1476 then \fB\*l\fP ignores \fB\-\-no\-collapse\fP.
1477 It changes sequences of tabs, spaces
1478 (and newlines unless \fB\-cr\-wrap\fP is set) to a single space.
1479 .bP
1480 If neither the \*(``\en\*('' or \fB\-\-trim\fP cases apply,
1481 \fB\*l\fP checks \fB\-\-no\-collapse\fP to decide whether to reduce
1482 sequences of tabs and spaces to a single space.
1483 .IP
1484 In this case, \fB\*l\fP ignores \fB\-\-cr\-wrap\fP and does not modify newlines.
1485 .PP
1486 Taking those dependencies into account,
1487 here is a table summarizing the behavior
1488 for the various combinations of options.
1489 The table assumes that the script contains at least one \*(``\en\*(''
1490 when the \fB\-\-no\-nl\-expand\fP option is not set.
1491 .na
1492 .RS 5
1493 .TS
1494 tab(/) ;
1495 lB lB lB lB lB
1496 lB lB lB lB lB
1497 _ _ _ _ _
1498 lw4 lw4 lw4 lw4 lw29.
1499 cr-/no-/no-/trim/Result
1500 wrap/collapse/nl\-expand
1501 no/no/no/no/T{
1502 Convert tab to space.
1503 Convert newline to space.
1504 Convert \*(``\en\*('' to newline.
1505 T}
1506 no/no/no/yes/T{
1507 Convert tab to space.
1508 Convert newline to space.
1509 Convert \*(``\en\*('' to newline.
1510 T}
1511 no/no/yes/no/T{
1512 Convert tab to space.
1513 Do not convert newline to space.
1514 Convert multiple-space to single.
1515 Show \*(``\en\*('' literally.
1516 T}
1517 no/no/yes/yes/T{
1518 Convert tab to space.
1519 Convert multiple-space to single.
1520 Convert newline to space.
1521 Show \*(``\en\*('' literally.
1522 T}
1523 no/yes/no/no/T{
1524 Convert newline to space.
1525 Convert \*(``\en\*('' to newline.
1526 T}
1527 no/yes/no/yes/T{
1528 Convert newline to space.
1529 Convert \*(``\en\*('' to newline.
1530 T}
1531 no/yes/yes/no/T{
1532 Do not convert newline to space.
1533 Do not reduce multiple blanks.
1534 Show \*(``\en\*('' literally.
1535 T}
1536 no/yes/yes/yes/T{
1537 Convert multiple-space to single.
1538 Convert newline to space.
1539 Show \*(``\en\*('' literally.
1540 T}
1541 yes/no/no/no/T{
1542 Convert tab to space.
1543 Wrap on newline.
1544 Convert \*(``\en\*('' to newline.
1545 T}
1546 yes/no/no/yes/T{
1547 Convert tab to space.
1548 Wrap on newline.
1549 Convert \*(``\en\*('' to newline.
1550 T}
1551 yes/no/yes/no/T{
1552 Convert tab to space.
1553 Do not convert newline to space.
1554 Convert multiple-space to single.
1555 Show \*(``\en\*('' literally.
1556 T}
1557 yes/no/yes/yes/T{
1558 Convert tab to space.
1559 Convert multiple-space to single.
1560 Wrap on newline.
1561 Show \*(``\en\*('' literally.
1562 T}
1563 yes/yes/no/no/T{
1564 Wrap on newline.
1565 Convert \*(``\en\*('' to newline.
1566 T}
1567 yes/yes/no/yes/T{
1568 Wrap on newline.
1569 Convert \*(``\en\*('' to newline.
1570 T}
1571 yes/yes/yes/no/T{
1572 Do not convert newline to space.
1573 Do not reduce multiple blanks.
1574 Show \*(``\en\*('' literally.
1575 T}
1576 yes/yes/yes/yes/T{
1577 Convert multiple-space to single.
1578 Wrap on newline.
1579 Show \*(``\en\*('' literally.
1580 T}
1581 .TE
1582 .RE
1583 .ad
1584 .
1585 .\" ************************************************************************
1586 .SH "RUN-TIME CONFIGURATION"
1587 .TP 4
1588 1.
1589 Create a sample configuration file by typing:
1590 .LP
1591 .Ex
1592 \*p \-\-create\-rc \fIfile\fP
1593 .Ee
1594 .TP 4
1595 2.
1596 At start,
1597 \fB\*p\fP
1598 determines the settings to use as follows:
1599 .RS
1600 .TP 4
1601 a)
1602 if environment variable
1603 \fBDIALOGRC\fP
1604 is set, its value determines the name of the configuration file.
1605 .TP 4
1606 b)
1607 if the file in (a) is not found, use the file
1608 \fI$HOME/.dialogrc\fP
1609 as the configuration file.
1610 .TP 4
1611 c)
1612 if the file in (b) is not found, try using the GLOBALRC file determined at
1613 compile-time, i.e., \fI/etc/dialogrc\fP.
1614 .TP 4
1615 d)
1616 if the file in (c) is not found, use compiled in defaults.
1617 .RE
1618 .TP 4
1619 3.
1620 Edit the sample configuration file and copy it to some place that
1621 \fB\*p\fP
1622 can find, as stated in step 2 above.
1623 .
1624 .\" ************************************************************************
1625 .SH "KEY BINDINGS"
1626 You can override or add to key bindings in \fB\*p\fP
1627 by adding to the configuration file.
1628 \fB\*L\fP's \fBbindkey\fP command maps single keys to its internal coding.
1629 .Ex
1630 bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP
1631 .Ee
1632 .PP
1633 The \fIwidget\fP name can be \*(``*\*('' (all widgets), or
1634 specific widgets such as \fBtextbox\fP.
1635 Specific widget bindings override the \*(``*\*('' bindings.
1636 User-defined bindings override the built-in bindings.
1637 .PP
1638 The \fIcurses_key\fP can be expressed in different forms:
1639 .bP
1640 It may be any of the names derived from
1641 \fBcurses.h\fP, e.g., \*(``HELP\*('' from \*(``KEY_HELP\*(''.
1642 .bP
1643 \fB\*L\fP also recognizes ANSI control characters
1644 such as \*(``^A\*('', \*(``^?\*('',
1645 as well as C1-controls such as \*(``~A\*('' and \*(``~?\*(''.
1646 .bP
1647 Finally, \fB\*l\fP allows backslash escapes as in C.
1648 Those can be octal character values such as \*(``\\033\*(''
1649 (the ASCII escape character),
1650 or the characters listed in this table:
1651 .RS 10
1652 .TS
1653 tab(/) ;
1654 lI lI
1655 _ _
1656 l l .
1657 Escaped/Actual
1658 \\b/backspace
1659 \\f/form feed
1660 \\n/new line (line feed)
1661 \\r/carriage return
1662 \\s/space
1663 \\t/tab
1664 \\^/\*(``^\*('' (caret)
1665 \\?/\*(``?\*('' (question mark)
1666 \\\\/\*(``\\\*('' (backslash)
1667 _
1668 .TE
1669 .RE
1670 .PP
1671 \fB\*L\fP's internal keycode names correspond to the
1672 \fBDLG_KEYS_ENUM\fP type in
1673 \fBdlg_keys.h\fP, e.g., \*(``HELP\*('' from \*(``DLGK_HELP\*(''.
1674 .SS "Widget Names"
1675 Some widgets (such as the formbox) have an area where fields can be edited.
1676 Those are managed in a subwindow of the widget, and
1677 may have separate keybindings from the main widget
1678 because the subwindows are registered using a different name.
1679 .RS 5
1680 .TS
1681 tab(/) ;
1682 lI lI lI
1683 _ _ _
1684 l l l .
1685 Widget/Window name/Subwindow Name
1686 calendar/calendar
1687 checklist/checklist
1688 editbox/editbox/editbox2
1689 form/formbox/formfield
1690 fselect/fselect/fselect2
1691 inputbox/inputbox/inputbox2
1692 menu/menubox/menu
1693 msgbox/msgbox
1694 pause/pause
1695 progressbox/progressbox
1696 radiolist/radiolist
1697 tailbox/tailbox
1698 textbox/textbox/searchbox
1699 timebox/timebox
1700 yesno/yesno
1701 _
1702 .TE
1703 .RE
1704 .PP
1705 Some widgets are actually other widgets,
1706 using internal settings to modify the behavior.
1707 Those use the same widget name as the actual widget:
1708 .RS 5
1709 .TS
1710 tab(/) ;
1711 lI lI
1712 _ _
1713 l l .
1714 Widget/Actual Widget
1715 dselect/fselect
1716 infobox/msgbox
1717 inputmenu/menu
1718 mixedform/form
1719 passwordbox/inputbox
1720 passwordform/form
1721 prgbox/progressbox
1722 programbox/progressbox
1723 tailboxbg/tailbox
1724 _
1725 .TE
1726 .RE
1727 .SS "Built-in Bindings"
1728 This manual page does not list the key bindings for each widget,
1729 because that detailed information can be obtained by running \fB\*p\fP.
1730 If you have set the \fB\-\-trace\fP option,
1731 \fB\*p\fP writes the key-binding information for each widget
1732 as it is registered.
1733 .PP
1734 A few bindings are built-in, independent of particular widgets:
1735 .TS
1736 tab(/) ;
1737 lI lI
1738 _ _
1739 l l .
1740 Key/Purpose
1741 Control-I/forward tab-traversal, e.g., with \fB\-\-tailboxbg\fP.
1742 Control-L/repaints the screen.
1743 Control-T/writes a screen dump to the \fB\-\-trace\fP file.
1744 Control-V/suppresses special-keys for the next input byte.
1745 DLGK_FIELD_NEXT/forward tab-traversal, like Control-I.
1746 DLGK_FIELD_PREV/backward tab-traversal, like back-tab.
1747 DLGK_HELPFILE/displays the help-file specified with \fB\-\-hfile\fP.
1748 KEY_BTAB/backward tab-traversal, e.g., with \fB\-\-tailboxbg\fP.
1749 _
1750 .TE
1751
1752 .SS Example
1753 Normally \fB\*p\fP uses different keys for navigating between the buttons
1754 and editing part of a dialog versus navigating within the editing part.
1755 That is, tab (and back-tab) traverse buttons
1756 (or between buttons and the editing part),
1757 while arrow keys traverse fields within the editing part.
1758 Tabs are also recognized as a special case for traversing between
1759 widgets, e.g., when using multiple tailboxbg widgets.
1760 .PP
1761 Some users may wish to use the same key for traversing within the
1762 editing part as for traversing between buttons.
1763 The form widget is written to support this sort of redefinition of
1764 the keys, by adding a special group in \fBdlgk_keys.h\fP
1765 for \*(``form\*('' (left/right/next/prev).
1766 Here is an example binding demonstrating how to do this:
1767 .Ex
1768 bindkey formfield TAB form_NEXT
1769 bindkey formbox TAB form_NEXT
1770 bindkey formfield BTAB form_prev
1771 bindkey formbox BTAB form_prev
1772 .Ee
1773 .PP
1774 That type of redefinition would not be useful in other widgets,
1775 e.g., calendar, due to the potentially large number of fields to traverse.
1776 .
1777 .SH EXIT STATUS
1778 Exit status is subject to being overridden by environment variables.
1779 The default values and corresponding environment variables
1780 that can override them are:
1781 .TP 5
1782 0
1783 if the \fBYES\fP or \fBOK\fP button is pressed (DIALOG_OK).
1784 .TP 5
1785 1
1786 if the
1787 .BR No " or " Cancel
1788 button is pressed (DIALOG_CANCEL).
1789 .TP 5
1790 2
1791 if the
1792 .B Help
1793 button is pressed (DIALOG_HELP),
1794 .br
1795 except as noted below about DIALOG_ITEM_HELP.
1796 .TP 5
1797 3
1798 if the
1799 .B Extra
1800 button is pressed (DIALOG_EXTRA).
1801 .TP 5
1802 4
1803 if the
1804 .B Help
1805 button is pressed,
1806 .br
1807 and the \fB\-\-item\-help\fP option is set
1808 .br
1809 and the DIALOG_ITEM_HELP environment variable is set to 4.
1810 .IP
1811 While any of the exit-codes can be overridden using environment variables,
1812 this special case was introduced in 2004 to simplify compatibility.
1813 \fB\*L\fP uses DIALOG_ITEM_HELP (4) internally,
1814 but unless the environment variable is also set,
1815 it changes that to DIALOG_HELP (2) on exit.
1816 .TP 5
1817 5
1818 if a timeout expires and the \fBDIALOG_TIMEOUT\fP variable is set to 5.
1819 .TP 5
1820 \-1
1821 if errors occur inside \fB\*p\fP (DIALOG_ERROR)
1822 or \fB\*p\fP exits because the \fIESC\fP key (DIALOG_ESC) was pressed.
1823 .\" ************************************************************************
1824 .SH ENVIRONMENT
1825 .TP 15
1826 \fBDIALOGOPTS\fP
1827 Define this variable to apply any of the common options to each widget.
1828 Most of the common options are reset before processing each widget.
1829 If you set the options in this environment variable,
1830 they are applied to \fB\*p\fP's state after the reset.
1831 As in the \*(``\fB\-\-file\fP\*('' option,
1832 double-quotes and backslashes are interpreted.
1833 .IP
1834 The \*(``\fB\-\-file\fP\*('' option is not considered a common option
1835 (so you cannot embed it within this environment variable).
1836 .TP 15
1837 \fBDIALOGRC\fP
1838 Define this variable if you want to specify the name of the configuration file
1839 to use.
1840 .TP 15
1841 \fBDIALOG_CANCEL\fP
1842 .TP 15
1843 \fBDIALOG_ERROR\fP
1844 .TP 15
1845 \fBDIALOG_ESC\fP
1846 .TP 15
1847 \fBDIALOG_EXTRA\fP
1848 .TP 15
1849 \fBDIALOG_HELP\fP
1850 .TP 15
1851 \fBDIALOG_ITEM_HELP\fP
1852 .TP 15
1853 \fBDIALOG_TIMEOUT\fP
1854 .TP 15
1855 \fBDIALOG_OK\fP
1856 Define any of these variables to change the exit code on
1857 .RS
1858 .bP
1859 Cancel (1),
1860 .bP
1861 error (\-1),
1862 .bP
1863 ESC (255),
1864 .bP
1865 Extra (3),
1866 .bP
1867 Help (2),
1868 .bP
1869 Help with \fB\-\-item\-help\fP (2),
1870 .bP
1871 Timeout (5), or
1872 .bP
1873 OK (0).
1874 .RE
1875 .IP
1876 Normally shell scripts cannot distinguish between \-1 and 255.
1877 .TP 15
1878 \fBDIALOG_TTY\fP
1879 Set this variable to \*(``1\*('' to provide compatibility with older versions
1880 of \fB\*p\fP which assumed that if the script redirects the standard output,
1881 that the \*(``\fB\-\-stdout\fP\*('' option was given.
1882 .\" ************************************************************************
1883 .SH FILES
1884 .TP 20
1885 \fI$HOME/.dialogrc\fP
1886 default configuration file
1887 .\" ************************************************************************
1888 .SH PORTABILITY
1889 \fB\*L\fP works with X/Open curses.
1890 However, some implementations have deficiencies:
1891 .RS 3
1892 .bP
1893 HPUX curses (and perhaps others) do not open the terminal properly for
1894 the \fInewterm\fP function.
1895 This interferes with \fB\*p\fP's \fB\-\-input\-fd\fP option,
1896 by preventing cursor-keys and similar escape sequences from being recognized.
1897 .bP
1898 NetBSD 5.1 curses has incomplete support for wide-characters.
1899 \fB\*p\fP will build, but not all examples display properly.
1900 .RE
1901 .\" ************************************************************************
1902 .SH COMPATIBILITY
1903 You may want to write scripts which run with
1904 other \fB\*l\fP \*(``clones\*(''.
1905 .SS "Original Dialog"
1906 First, there is the \*(``original\*('' \fB\*p\fP program to consider
1907 (versions 0.3 to 0.9).
1908 It had some misspelled (or inconsistent) options.
1909 The \fB\*p\fP program maps those deprecated options to the preferred ones.
1910 They include:
1911 .RS
1912 .TS
1913 tab(/) ;
1914 lI lI
1915 _ _
1916 l l.
1917 Option/Treatment
1918 \fB\-\-beep\-after\fP/ignored
1919 \fB\-\-guage\fP/mapped to \fB\-\-gauge\fP
1920 _
1921 .TE
1922 .RE
1923 .SS Xdialog
1924 This is an X application, rather than a terminal program.
1925 With some care, it is possible to write useful scripts that work
1926 with both \fBXdialog\fP and \fB\*p\fP.
1927 .PP
1928 The \fB\*p\fP program ignores these options which are recognized
1929 by \fBXdialog\fP:
1930 .RS
1931 .TS
1932 tab(/) ;
1933 lI lI
1934 _ _
1935 l l.
1936 Option/Treatment
1937 \fB\-\-allow\-close\fP/ignored
1938 \fB\-\-auto\-placement\fP/ignored
1939 \fB\-\-fixed\-font\fP/ignored
1940 \fB\-\-icon\fP/ignored
1941 \fB\-\-keep\-colors\fP/ignored
1942 \fB\-\-no\-close\fP/ignored
1943 \fB\-\-no\-cr\-wrap\fP/ignored
1944 \fB\-\-screen\-center\fP/ignored
1945 \fB\-\-separator\fP/mapped to \fB\-\-separate\-output\fP
1946 \fB\-\-smooth\fP/ignored
1947 \fB\-\-under\-mouse\fP/ignored
1948 \fB\-\-wmclass\fP/ignored
1949 _
1950 .TE
1951 .RE
1952 .PP
1953 \fBXdialog\fP's manpage has a section discussing its compatibility
1954 with \fB\*p\fP.
1955 There are some differences not shown in the manpage.
1956 For example, the html documentation states
1957 .RS
1958 .PP
1959 Note: former Xdialog releases used the \*(``\en\*('' (line feed) as a
1960 results separator for the checklist widget;
1961 this has been changed to \*(``/\*('' in Xdialog v1.5.0
1962 to make it compatible with (c)dialog.
1963 In your old scripts using the Xdialog checklist, you
1964 will then have to add the \fB\-\-separate\-output\fP option before the
1965 \fB\-\-checklist\fP one.
1966 .RE
1967 .PP
1968 \fB\*L\fP has not used a different separator;
1969 the difference was likely due to confusion regarding some script.
1970 .SS Whiptail
1971 Then there is \fBwhiptail\fP.
1972 For practical purposes, it is maintained by Debian
1973 (very little work is done by its upstream developers).
1974 Its documentation (README.whiptail) claims
1975 .Ex
1976 \fBwhiptail\fP(1) is a lightweight replacement for \*p(1),
1977 to provide dialog boxes for shell scripts.
1978 It is built on the
1979 newt windowing library rather than the ncurses library, allowing
1980 it to be smaller in embedded environments such as installers,
1981 rescue disks, etc.
1982
1983 whiptail is designed to be drop-in compatible with \*p, but
1984 has less features: some dialog boxes are not implemented, such
1985 as tailbox, timebox, calendarbox, etc.
1986 .Ee
1987 .PP
1988 Comparing actual sizes (Debian testing, 2007/1/10):
1989 The total of sizes for \fBwhiptail\fP,
1990 the newt, popt and slang libraries is 757\ KB.
1991 The comparable number for \fB\*p\fP (counting ncurses) is 520\ KB.
1992 Disregard the first paragraph.
1993 .PP
1994 The second paragraph is misleading, since \fBwhiptail\fP
1995 also does not work for common options of \fB\*p\fP,
1996 such as the gauge box.
1997 \fBwhiptail\fP is less compatible with \fB\*p\fP than the
1998 original mid-1990s dialog 0.4 program.
1999 .PP
2000 \fBwhiptail\fP's manpage borrows features from \fB\*p\fP, e.g.,
2001 but oddly cites only \fB\*p\fP versions up to 0.4 (1994) as a source.
2002 That is, its manpage refers to features which
2003 were borrowed from more recent versions of \fB\*p\fP, e.g.,
2004 .bP
2005 \fB\-\-gauge\fP (from 0.5)
2006 .bP
2007 \fB\-\-passwordbox\fP (from Debian changes in 1999),
2008 .bP
2009 \fB\-\-default\-item\fP (from \fB\*p\fP 2000/02/22),
2010 .bP
2011 \fB\-\-output\-fd\fP (from \fB\*p\fP 2002/08/14).
2012 .PP
2013 Debian uses \fBwhiptail\fP for the official \fB\*p\fP variation.
2014 .PP
2015 The \fB\*p\fP program ignores or maps these options which are recognized
2016 by \fBwhiptail\fP:
2017 .RS
2018 .TS
2019 tab(/) ;
2020 lI lI
2021 _ _
2022 l l.
2023 Option/Treatment
2024 \fB\-\-cancel\-button\fP/mapped to \fB\-\-cancel\-label\fP
2025 \fB\-\-fb\fP/ignored
2026 \fB\-\-fullbutton\fP/ignored
2027 \fB\-\-no\-button\fP/mapped to \fB\-\-no\-label\fP
2028 \fB\-\-nocancel\fP/mapped to \fB\-\-no\-cancel\fP
2029 \fB\-\-noitem\fP/mapped to \fB\-\-no\-items\fP
2030 \fB\-\-notags\fP/mapped to \fB\-\-no\-tags\fP
2031 \fB\-\-ok\-button\fP/mapped to \fB\-\-ok\-label\fP
2032 \fB\-\-scrolltext\fP/mapped to \fB\-\-scrollbar\fP
2033 \fB\-\-topleft\fP/mapped to \fB\-\-begin 0 0\fP
2034 \fB\-\-yes\-button\fP/mapped to \fB\-\-yes\-label\fP
2035 _
2036 .TE
2037 .RE
2038 .LP
2039 There are visual differences which are not addressed by command-line options:
2040 .bP
2041 \fB\*p\fP centers lists within the window.
2042 \fBwhiptail\fP typically puts lists against the left margin.
2043 .bP
2044 \fBwhiptail\fP uses angle brackets (\*(``<\*('' and \*(``>\*('')
2045 for marking buttons.
2046 \fB\*p\fP uses square brackets.
2047 .bP
2048 \fBwhiptail\fP marks the limits of subtitles with vertical bars.
2049 \fB\*p\fP does not mark the limits.
2050 .bP
2051 \fBwhiptail\fP attempts to mark the top/bottom cells of a scrollbar
2052 with up/down arrows.
2053 When it cannot do this,
2054 it fills those cells with the background color
2055 of the scrollbar and confusing the user.
2056 \fB\*p\fP uses the entire scrollbar space,
2057 thereby getting better resolution.
2058 .\" ************************************************************************
2059 .SH BUGS
2060 Perhaps.
2061 .\" ************************************************************************
2062 .SH EXAMPLES
2063 The \fB\*p\fP sources contain several samples
2064 of how to use the different box options and how they look.
2065 Just take a look into the directory \fBsamples/\fP of the source.
2066 .\" ************************************************************************
2067 .SH AUTHORS
2068 Thomas E.\& Dickey (updates for 0.9b and beyond)
2069 .LP
2070 Kiran Cherupally \(en the mixed form and mixed gauge widgets.
2071 .LP
2072 Tobias C.\& Rittweiler
2073 .LP
2074 Valery Reznic \(en the form and progressbox widgets.
2075 .LP
2076 Yura Kalinichenko adapted the gauge widget as \*(``pause\*(''.
2077 .PP
2078 This is a rewrite (except as needed to provide compatibility)
2079 of the earlier version of \fB\*p 0.9a\fP,
2080 which lists as authors:
2081 .bP
2082 Savio Lam \(en version 0.3, \*(``dialog\*(''
2083 .bP
2084 Stuart Herbert \(en patch for version 0.4
2085 .bP
2086 Marc Ewing \(en the gauge widget.
2087 .bP
2088 Pasquale De Marco \*(``Pako\*('' \(en version 0.9a, \*(``cdialog\*(''