Debian Codegraph @

upstream/debian-unstable/man1/dialog.1

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