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