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