2 .\" $Id: dialog.1,v 1.205 2018/06/19 00:26:13 tom Exp $
3 .\" Copyright 2005-2017,2018 Thomas E. Dickey
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.
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.
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.
20 .\" definitions for renaming
41 .\" Bulleted paragraph
51 .TH \*D 1 "" "$Date: 2018/06/19 00:26:13 $"
53 dialog \- display dialog boxes from shell scripts
57 .BI "\*p --create-rc " file
59 \fB\*p --print-maxsize\fP
66 is a program that will let you present a variety of questions or
67 display messages using dialog boxes from a shell script.
68 These types of dialog boxes are implemented
69 (though not all are necessarily compiled into \fB\*p\fR):
88 .BR msgbox " (message), "
101 .BR treeview ", and "
102 .BR yesno " (yes/no)."
107 You can put more than one dialog box into a script:
109 Use the "\fB--and-widget\fP" token to force \fB\*p\fP to proceed to the next
110 dialog unless you have pressed ESC to cancel, or
112 Simply add the tokens for the next dialog box, making a chain.
113 \*L stops chaining when the return code from a dialog is nonzero,
114 e.g., Cancel or No (see DIAGNOSTICS).
116 Some widgets, e.g., checklist, will write text to \fB\*p\fP's output.
117 Normally that is the standard error, but there are options for
118 changing this: "\fB--output-fd\fP", "\fB--stderr\fP" and "\fB--stdout\fP".
119 No text is written if the Cancel button (or ESC) is pressed;
120 \fB\*p\fP exits immediately in that case.
122 .\" ************************************************************************
124 All options begin with "\fB--\fP"
126 for the benefit of those using systems with deranged locale support).
128 A "\fB--\fP" by itself is used as an escape,
129 i.e., the next token on the command-line is not treated as an option.
131 .B \*p --title -- --Not an option
134 The "\fB--args\fP" option tells \fB\*p\fP to list the command-line
135 parameters to the standard error.
136 This is useful when debugging complex scripts using
137 the "\fB--\fP" and "\fB--file\fP",
138 since the command-line may be rewritten as these are expanded.
140 The "\fB--file\fP" option tells \fB\*p\fP to read parameters from
141 the file named as its value.
143 .B \*p --file \fIparameterfile
146 Blanks not within double-quotes are discarded
147 (use backslashes to quote single characters).
148 The result is inserted into the command-line,
149 replacing "\fB--file\fP" and its option value.
150 Interpretation of the command-line resumes from that point.
151 If \fIparameterfile\fP begins with "&", \fB\*p\fP
152 interprets the following text as a file descriptor number
153 rather than a filename.
155 Most widgets accept \fIheight\fP and \fIwidth\fP parameters,
156 which can be used to automatically size the widget to accommodate
157 multi-line message \fIprompt\fP values:
159 If the parameter is negative,
160 \fB\*l\fP uses the screen's size.
162 If the parameter is zero,
163 \fB\*l\fP uses minimum size for the widget to display the \fIprompt\fP
166 Otherwise, \fB\*l\fP uses the given size for the widget.
168 .SS \fBCommon Options\fP
169 Most of the common options are reset before processing each widget.
171 .IP "\fB--ascii-lines
172 Rather than draw graphics lines around boxes,
173 draw ASCII "+" and "-" in the same place.
174 See also "\fB--no-lines\fR".
176 .IP "\fB--aspect \fIratio"
177 This gives you some control over the box dimensions when using auto
178 sizing (specifying 0 for height and width).
179 It represents width / height.
180 The default is 9, which means 9 characters wide to every 1 line high.
182 .IP "\fB--backtitle \fIbacktitle"
185 string to be displayed on the backdrop, at the top of the screen.
187 .IP "\fB--begin \fIy x"
188 Specify the position of the upper left corner of a dialog box on the screen.
190 .IP "\fB--cancel-label \fIstring"
191 Override the label used for \*(``Cancel\*('' buttons.
194 Clears the widget screen, keeping only the screen_color background.
195 Use this when you combine widgets with "\fB--and-widget\fR" to erase the
196 contents of a previous widget on the screen, so it won't be seen
197 under the contents of a following widget.
198 Understand this as the complement of "\fB--keep-window\fR".
199 To compare the effects, use these:
202 All three widgets visible, staircase effect, ordered 1,2,3:
205 --begin 2 2 --yesno "" 0 0 \e
206 --and-widget --begin 4 4 --yesno "" 0 0 \e
207 --and-widget --begin 6 6 --yesno "" 0 0
211 Only the last widget is left visible:
214 --clear --begin 2 2 --yesno "" 0 0 \e
215 --and-widget --clear --begin 4 4 --yesno "" 0 0 \e
216 --and-widget --begin 6 6 --yesno "" 0 0
220 All three widgets visible, staircase effect, ordered 3,2,1:
223 --keep-window --begin 2 2 --yesno "" 0 0 \e
224 --and-widget --keep-window --begin 4 4 --yesno "" 0 0 \e
225 --and-widget --begin 6 6 --yesno "" 0 0
229 First and third widget visible, staircase effect, ordered 3,1:
232 --keep-window --begin 2 2 --yesno "" 0 0 \e
233 --and-widget --clear --begin 4 4 --yesno "" 0 0 \e
234 --and-widget --begin 6 6 --yesno "" 0 0
237 Note, if you want to restore original console colors and send your
238 cursor home after the dialog program has exited, use the \fBclear\fR\ (1)
242 Interpret embedded "\eZ" sequences in the dialog text
243 by the following character,
244 which tells \fB\*p\fP to set colors or video attributes:
247 0 through 7 are the ANSI color numbers used in curses:
257 Bold is set by 'b', reset by 'B'.
259 Reverse is set by 'r', reset by 'R'.
261 Underline is set by 'u', reset by 'U'.
263 The settings are cumulative, e.g., "\eZb\eZ1" makes the following text
264 bold (perhaps bright) red.
266 Restore normal settings with "\eZn".
269 .IP "\fB--column-separator \fIstring"
270 Tell \fB\*p\fP to split data for radio/checkboxes and menus on the
271 occurrences of the given string, and to align the split data into columns.
274 Interpret embedded newlines in the dialog text as a newline on the screen.
275 Otherwise, \fB\*p\fR will only wrap lines
276 where needed to fit inside the text box.
278 Even though you can control line breaks with this,
279 \fB\*L\fR will still wrap any lines that are too long for the width of the box.
280 Without cr-wrap, the layout of your text may be formatted to look nice
281 in the source code of your script without affecting the way it will
284 The \fIcr-wrap\fP feature is implemented subject to these conditions:
287 the string contains \*(``\en\*('' and the \fB--no-nl-expand\fP option is
290 the \fB--trim\fP option is used.
293 For more information, see \fBWhitespace Options\fP.
295 .IP "\fB--create-rc \fIfile"
298 supports run-time configuration,
299 this can be used to dump a sample configuration file to the file specified
303 .IP "\fB--date-format \fIformat"
304 If the host provides \fBstrftime\fP,
305 this option allows you to specify the format of the date printed for
306 the \fB--calendar\fP widget.
307 The time of day (hour, minute, second) are the current local time.
310 Make the default value of the
314 Likewise, treat the default button of widgets that provide
315 \*(``OK\*('' and \*(``Cancel\*(''
317 If "\fB--nocancel\fP" or "\fB--visit-items\fP" are given
318 those options overrides this,
319 making the default button always \*(``Yes\*(''
320 (internally the same as \*(``OK\*('').
322 .IP "\fB--default-button \fIstring"
323 Set the default (preselected) button in a widget.
324 By preselecting a button,
325 a script makes it possible for the user to simply press \fIEnter\fP
326 to proceed through a dialog with minimum interaction.
328 The option's value is the name of the button:
336 Normally the first button in each widget is the default.
337 The first button shown is determined by the widget
338 together with the "\fB--nook\fP" and "\fB--nocancel\fP options.
339 If this option is not given, there is no default button assigned.
341 .IP "\fB--default-item \fIstring"
342 Set the default item in a checklist, form or menu box.
343 Normally the first item in the box is the default.
345 .IP "\fB--exit-label \fIstring"
346 Override the label used for \*(``EXIT\*('' buttons.
348 .IP "\fB--extra-button"
349 Show an extra button, between \*(``OK\*('' and \*(``Cancel\*('' buttons.
351 .IP "\fB--extra-label \fIstring"
352 Override the label used for \*(``Extra\*('' buttons.
353 Note: for inputmenu widgets, this defaults to \*(``Rename\*(''.
356 Prints the help message to the standard output and exits.
357 The help message is also printed if no options are given,
358 or if an unrecognized option is given.
360 .IP "\fB--help-button"
361 Show a help-button after \*(``OK\*('' and \*(``Cancel\*('' buttons,
362 e.g., in checklist, radiolist and menu boxes,
363 and other widgets which have an \*(``OK\*('' button,
364 whether or not the \*(``Cancel\*('' button is used.
366 On exit, the return status will indicate that the Help button was pressed.
367 \fB\*L\fP will also write a message to its output
368 after the token \*(``HELP\*('':
371 If "\fB--item-help\fR" is also given, the item-help text will be written.
373 Otherwise, the item's tag (the first field) will be written.
377 You can use the \fB--help-tags\fP option and/or set the DIALOG_ITEM_HELP
378 environment variable to modify these messages and exit-status.
380 .IP "\fB--help-label \fIstring"
381 Override the label used for \*(``Help\*('' buttons.
383 .IP "\fB--help-status"
384 If the help-button is selected,
385 writes the checklist, radiolist or form information
386 after the item-help \*(``HELP\*('' information.
387 This can be used to reconstruct the state of a checklist after processing
391 Modify the messages written on exit for \fB--help-button\fP
392 by making them always just the item's tag.
393 This does not affect the exit status code.
395 .IP "\fB--hfile \fIfilename"
396 Display the given file using a textbox when the user presses F1.
398 .IP "\fB--hline \fIstring"
399 Display the given string centered at the bottom of the widget.
402 Ignore options that \fB\*p\fP does not recognize.
403 Some well-known ones such as "\fB--icon\fP" are ignored anyway,
404 but this is a better choice for compatibility with other implementations.
406 .IP "\fB--input-fd \fIfd"
407 Read keyboard input from the given file descriptor.
408 Most \fB\*p\fR scripts read from the standard input,
409 but the gauge widget reads a pipe (which is always standard input).
410 Some configurations do not work properly when
411 \fB\*p\fP tries to reopen the terminal.
412 Use this option (with appropriate juggling of file-descriptors)
413 if your script must work in that type of environment.
416 Makes the password widget friendlier but less secure,
417 by echoing asterisks for each character.
420 Set the starting point for the week-number
421 shown in the "\fB--calendar\fP" option
422 according to ISO-8601, which starts numbering
423 with the first week which includes a Thursday in January.
426 Interpret the tags data for checklist, radiolist and menu boxes
427 adding a column which is displayed in the bottom line of the
428 screen, for the currently selected item.
431 When built with \fBncurses\fP,
432 \fB\*p\fP normally checks to see if it is running in an \fBxterm\fP,
433 and in that case tries to suppress the initialization strings that
434 would make it switch to the alternate screen.
435 Switching between the normal and alternate screens
436 is visually distracting in a script which runs \fB\*p\fP
438 Use this option to allow \fB\*p\fP to use those initialization strings.
440 .IP "\fB--keep-window"
441 Normally when \fB\*p\fR performs several \fBtailboxbg\fR widgets
442 connected by "\fB--and-widget\fR",
443 it clears the old widget from the screen by painting over it.
444 Use this option to suppress that repainting.
446 At exit, \fB\*p\fR repaints all of the widgets which have been
447 marked with "\fB--keep-window\fR", even if they are not \fBtailboxbg\fR widgets.
448 That causes them to be repainted in reverse order.
449 See the discussion of the "\fB--clear\fR" option for examples.
452 At exit, report the last key which the user entered.
453 This is the curses key code rather than a symbol or literal character.
454 It can be used by scripts to distinguish between two keys which are
455 bound to the same action.
457 .IP "\fB--max-input \fIsize"
458 Limit input strings to the given size.
459 If not specified, the limit is 2048.
463 Suppress the \*(``Cancel\*('' button in checklist, inputbox and menu box modes.
464 A script can still test if the user pressed the ESC key to cancel to quit.
466 .IP "\fB--no-collapse"
467 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
468 spaces to a single space for text which is displayed in a message boxes, etc.
469 Use this option to disable that feature.
470 Note that \fB\*p\fR will still wrap text,
471 subject to the "\fB--cr-wrap\fR" and "\fB--trim\fR" options.
473 The \fIno-collapse\fP feature is implemented subject to these conditions:
476 the string contains \*(``\en\*('' and the \fB--no-nl-expand\fP option is
479 the \fB--trim\fP option is not used.
482 For more information, see \fBWhitespace Options\fP.
485 Some widgets (checklist, inputmenu, radiolist, menu) display a list
486 with two columns (a \*(``tag\*('' and \*(``item\*('',
487 i.e., \*(``description\*('').
488 This option tells \fB\*p\fP to read shorter rows,
489 omitting the \*(``item\*('' part of the list.
490 This is occasionally useful, e.g., if the tags provide enough information.
492 See also \fB--no-tags\fP.
493 If both options are given, this one is ignored.
500 box in the background,
501 printing its process id to \fB\*p\fP's output.
502 SIGHUP is disabled for the background process.
504 .IP "\fB--no-label \fIstring"
505 Override the label used for \*(``No\*('' buttons.
508 Rather than draw lines around boxes, draw spaces in the same place.
509 See also "\fB--ascii-lines\fR".
512 Do not enable the mouse.
514 .IP "\fB--no-nl-expand
515 Do not convert "\en" substrings of the message/prompt text into
518 The \fIno-nl-expand\fP feature is used only if
519 the string contains \*(``\en\*('' so that there is something to convert.
521 For more information, see \fBWhitespace Options\fP.
525 Suppress the \*(``OK\*('' button in checklist, inputbox and menu box modes.
526 A script can still test if the user pressed
527 the \*(``Enter\*('' key to accept the data.
530 Suppress shadows that would be drawn to the right and bottom of each dialog box.
533 Some widgets (checklist, inputmenu, radiolist, menu) display a list
534 with two columns (a \*(``tag\*('' and \*(``description\*('').
535 The tag is useful for scripting, but may not help the user.
536 The \fB--no-tags\fP option (from Xdialog) may be used to suppress the
537 column of tags from the display.
538 Unlike the \fB--no-items\fP option,
539 this does not affect the data which is read from the script.
541 Xdialog does not display the tag column for the analogous buildlist
542 and treeview widgets; \fB\*p\fP does the same.
544 Normally \fB\*p\fP allows you to quickly move to entries on the displayed list,
545 by matching a single character to the first character of the tag.
546 When the \fB--no-tags\fP option is given, \fB\*p\fP matches against
547 the first character of the description.
548 In either case, the matchable character is highlighted.
550 .IP "\fB--ok-label \fIstring"
551 Override the label used for \*(``OK\*('' buttons.
553 .IP "\fB--output-fd \fIfd"
554 Direct output to the given file descriptor.
555 Most \fB\*p\fR scripts write to the standard error,
556 but error messages may also be written there, depending on your script.
558 .IP "\fB--separator \fIstring"
559 .IP "\fB--output-separator \fIstring"
560 Specify a string that will separate the output on \fB\*p\fP's output from
561 checklists, rather than a newline (for \fB--separate-output\fP) or a space.
562 This applies to other widgets such as forms and editboxes which normally
565 .IP "\fB--print-maxsize"
566 Print the maximum size of dialog boxes, i.e., the screen size,
567 to \fB\*p\fP's output.
568 This may be used alone, without other options.
570 .IP "\fB--print-size"
571 Prints the size of each dialog box to \fB\*p\fP's output
572 when the box is initialized.
574 .IP "\fB--print-text-only \fIstring [ height [ width ] ]"
575 Prints the string as it would be wrapped in a message box
576 to \fB\*p\fP's output.
578 Because the optional \fIheight\fP and \fIwidth\fP default to zero,
579 if they are omitted, \fB\*p\fP autosizes according to the screen dimensions.
581 .IP "\fB--print-text-size \fIstring [ height [ width ] ]"
582 Prints the size of the string as it would be wrapped in a message box,
583 to \fB\*p\fP's output,
589 Because the optional \fIheight\fP and \fIwidth\fP parameters default to zero,
590 if they are omitted, \fB\*p\fP autosizes according to the screen dimensions.
592 .IP "\fB--print-version"
593 Prints \fB\*p\fR's version to \fB\*p\fP's output.
594 This may be used alone, without other options.
595 It does not cause \fBdialog\fP to exit by itself.
598 Normally \fB\*p\fP quotes the strings returned by checklist's
599 as well as the item-help text.
600 Use this option to quote all string results.
602 By default, the buildlist widget uses the same order for the output (right)
603 list as for the input (left).
604 Use this option to tell \fB\*p\fP to use the order
605 in which a user adds selections to the output list.
608 For widgets holding a scrollable set of data,
609 draw a scrollbar on its right-margin.
610 This does not respond to the mouse.
612 .IP "\fB--separate-output"
613 For certain widgets (buildlist, checklist, treeview),
614 output result one line at a time, with no quoting.
615 This facilitates parsing by another program.
617 .IP "\fB--separate-widget \fIstring"
618 Specify a string that will separate the output on \fB\*p\fP's output from
620 This is used to simplify parsing the result of a dialog with several widgets.
621 If this option is not given,
622 the default separator string is a tab character.
625 Draw a shadow to the right and bottom of each dialog box.
627 .IP "\fB--single-quoted"
628 Use single-quoting as needed (and no quotes if unneeded) for the
629 output of checklist's as well as the item-help text.
630 If this option is not set, \fB\*p\fP uses double quotes around each item.
632 \fB\*p\fP adds backslashes to make the output useful in shell scripts.
635 Check the resulting size of a dialog box before trying to use it,
636 printing the resulting size if it is larger than the screen.
637 (This option is obsolete, since all new-window calls are checked).
639 .IP "\fB--sleep \fIsecs"
640 Sleep (delay) for the given number of seconds after processing a dialog box.
643 Direct output to the standard error.
644 This is the default, since curses normally writes screen updates to
648 Direct output to the standard output.
649 This option is provided for compatibility with Xdialog,
650 however using it in portable scripts is not recommended,
651 since curses normally writes its screen updates to the standard output.
652 If you use this option, \fB\*p\fR attempts to reopen the terminal
653 so it can write to the display.
654 Depending on the platform and your environment, that may fail.
656 .IP "\fB--tab-correct"
657 Convert each tab character to one or more spaces
658 (for the \fBtextbox\fP widget; otherwise to a single space).
659 Otherwise, tabs are rendered according to the curses library's interpretation.
660 The \fB--no-collapse\fP option disables tab expansion.
662 .IP "\fB--tab-len \fIn"
663 Specify the number of spaces that a tab character occupies if the
664 "\fB--tab-correct\fP" option is given.
666 This option is only effective for the \fBtextbox\fP widget.
668 .IP "\fB--time-format \fIformat"
669 If the host provides \fBstrftime\fP,
670 this option allows you to specify the format of the time printed for
671 the \fB--timebox\fP widget.
672 The day, month, year values in this case are for the current local time.
674 .IP "\fB--timeout \fIsecs"
675 Timeout (exit with error code)
676 if no user response within the given number of seconds.
677 A timeout of zero seconds is ignored.
679 This option is ignored by the "\fB--pause\fP" widget.
680 It is also overridden if the background "\fB--tailboxbg\fP" option is used
681 to set up multiple concurrent widgets.
683 .IP "\fB--title \fItitle"
686 string to be displayed at the top of the dialog box.
688 .IP "\fB--trace \fIfilename"
689 logs the command-line parameters,
690 keystrokes and other information to the given file.
691 If \fBdialog\fP reads a configure file, it is logged as well.
692 Piped input to the \fIgauge\fP widget is logged.
693 Use control/T to log a picture of the current dialog window.
695 The \fB\*p\fR program handles some command-line parameters specially,
696 and removes them from the parameter list as they are processed.
697 For example, if the first option is \fB--trace\fP,
698 then that is processed (and removed) before \fB\*p\fR initializes the display.
700 .IP "\fB--week-start \fIday"
701 sets the starting day for the week, used in the "\fB--calendar\fP" option.
702 The \fIday\fP parameter can be
705 a number (0 to 6, Sunday through Saturday using POSIX) or
707 the special value \*(``locale\*('' (this works with systems using glibc,
708 providing an extension to the \fBlocale\fP command,
709 the \fBfirst_weekday\fP value).
711 a string matching one of the abbreviations for the day of the week
712 shown in the \fBcalendar\fP widget, e.g., \*(``Mo\*('' for \*(``Monday\*(''.
716 eliminate leading blanks,
717 trim literal newlines and repeated blanks from message text.
719 The \fItrim\fP feature is implemented subject to these conditions:
722 the string does not contain \*(``\en\*('' or
724 the \fB--no-nl-expand\fP option is used.
727 For more information, see \fBWhitespace Options\fP.
730 See also the "\fB--cr-wrap\fR" and "\fB--no-collapse\fR" options.
733 Prints \fB\*p\fR's version to the standard output, and exits.
734 See also "\fB--print-version\fP".
736 .IP "\fB--visit-items"
737 Modify the tab-traversal of checklist, radiolist, menubox and inputmenu
738 to include the list of items as one of the states.
739 This is useful as a visual aid,
740 i.e., the cursor position helps some users.
742 When this option is given, the cursor is initially placed on the list.
743 Abbreviations (the first letter of the tag) apply to the list items.
744 If you tab to the button row, abbreviations apply to the buttons.
746 .IP "\fB--yes-label \fIstring"
747 Override the label used for \*(``Yes\*('' buttons.
749 .\" ************************************************************************
751 All dialog boxes have at least three parameters:
754 the caption or contents of the box.
757 the height of the dialog box.
760 the width of the dialog box.
762 Other parameters depend on the box type.
765 .IP "\fB--buildlist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
766 A \fBbuildlist\fP dialog displays two lists, side-by-side.
767 The list on the left shows unselected items.
768 The list on the right shows selected items.
769 As items are selected or unselected, they move between the lists.
771 Use a carriage return or the \*(``OK\*('' button to accept the current value
772 in the selected-window and exit.
773 The results are written using the order displayed in the selected-window.
775 The initial on/off state of each entry is specified by
778 The dialog behaves like a \fBmenu\fP, using the \fB--visit-items\fP
779 to control whether the cursor is allowed to visit the lists directly.
782 If \fB--visit-items\fP is not given,
783 tab-traversal uses two states (OK/Cancel).
785 If \fB--visit-items\fP is given,
786 tab-traversal uses four states (Left/Right/OK/Cancel).
789 Whether or not \fB--visit-items\fP is given,
790 it is possible to move the highlight between the two lists using
791 the default "^" (left-column) and "$" (right-column) keys.
793 On exit, a list of the \fItag\fP
794 strings of those entries that are turned on
795 will be printed on \fB\*p\fP's output.
797 If the "\fB--separate-output\fP" option is not given,
798 the strings will be quoted as needed
799 to make it simple for scripts to separate them.
800 By default, this uses double-quotes.
801 See the "\fB--single-quoted\fP" option, which modifies the quoting behavior.
804 .IP "\fB--calendar \fItext height width day month year"
805 A \fBcalendar\fP box displays
806 month, day and year in separately adjustable windows.
807 If the values for day, month or year are missing or negative,
808 the current date's corresponding values are used.
809 You can increment or decrement any of those using the
810 left-, up-, right-, and down-arrows.
811 Use vi-style h, j, k and l for moving around the array of days in a month.
812 Use tab or backtab to move between windows.
813 If the year is given as zero, the current date is used as an initial value.
815 On exit, the date is printed in the form day/month/year.
816 The format can be overridden using the \fB--date-format\fP option.
819 .IP "\fB--checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
820 A \fBchecklist\fP box is similar to a \fBmenu\fP box;
821 there are multiple entries presented in the form of a menu.
822 Another difference is
823 that you can indicate which entry is currently selected, by setting its
824 .IR status " to " on "."
826 one entry among the entries, each entry can be turned on or off by the user.
827 The initial on/off state of each entry is specified by
830 On exit, a list of the \fItag\fP
831 strings of those entries that are turned on
832 will be printed on \fB\*p\fP's output.
834 If the "\fB--separate-output\fP" option is not given,
835 the strings will be quoted as needed
836 to make it simple for scripts to separate them.
837 By default, this uses double-quotes.
838 See the "\fB--single-quoted\fP" option, which modifies the quoting behavior.
841 .IP "\fB--dselect \fIfilepath height width\fR"
842 The directory-selection dialog displays a text-entry window
843 in which you can type a directory,
844 and above that a windows with directory names.
848 can be a filepath in which case the directory window
849 will display the contents of the path and the text-entry window will contain
850 the preselected directory.
852 Use tab or arrow keys to move between the windows.
853 Within the directory window, use the up/down arrow keys
854 to scroll the current selection.
855 Use the space-bar to copy the current selection into the text-entry
858 Typing any printable characters switches focus to the text-entry window,
859 entering that character as well as scrolling the directory
860 window to the closest match.
862 Use a carriage return or the \*(``OK\*('' button to accept the current value
863 in the text-entry window and exit.
865 On exit, the contents of the text-entry window are written
866 to \fB\*p\fP's output.
868 .IP "\fB--editbox \fIfilepath height width\fR"
869 The edit-box dialog displays a copy of the file.
870 You may edit it using
871 the \fIbackspace\fP, \fIdelete\fP and cursor keys
872 to correct typing errors.
873 It also recognizes pageup/pagedown.
874 Unlike the \fB--inputbox\fP,
875 you must tab to the \*(``OK\*('' or \*(``Cancel\*('' buttons
877 Pressing the \*(``Enter\*('' key within the box will split
878 the corresponding line.
880 On exit, the contents of the edit window are written to \fB\*p\fP's output.
883 .IP "\fB--form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
885 The \fBform\fP dialog displays a form consisting of labels and fields,
886 which are positioned on a scrollable window by coordinates given in the script.
887 The field length \fIflen\fR and input-length \fIilen\fR tell how long
889 The former defines the length shown for a selected field,
890 while the latter defines the permissible length of the data entered in the
894 If \fIflen\fR is zero, the corresponding field cannot be altered.
895 and the contents of the field determine the displayed-length.
897 If \fIflen\fR is negative, the corresponding field cannot be altered,
898 and the negated value of \fIflen\fR is used as the displayed-length.
900 If \fIilen\fR is zero, it is set to \fIflen\fR.
903 Use up/down arrows (or control/N, control/P) to move between fields.
904 Use tab to move between windows.
906 On exit, the contents of the form-fields are written to \fB\*p\fP's output,
907 each field separated by a newline.
908 The text used to fill non-editable fields
909 (\fIflen\fR is zero or negative)
913 .IP "\fB--fselect \fIfilepath height width\fR"
914 The \fBfselect\fP (file-selection) dialog displays a text-entry window
915 in which you can type a filename (or directory),
916 and above that two windows with directory names and filenames.
920 can be a filepath in which case the file and directory windows
921 will display the contents of the path and the text-entry window will contain
922 the preselected filename.
924 Use tab or arrow keys to move between the windows.
925 Within the directory or filename windows, use the up/down arrow keys
926 to scroll the current selection.
927 Use the space-bar to copy the current selection into the text-entry
930 Typing any printable characters switches focus to the text-entry window,
931 entering that character as well as scrolling the directory and filename
932 windows to the closest match.
934 Typing the space character forces \fB\*p\fP to complete the current
935 name (up to the point where there may be a match against more than one
938 Use a carriage return or the \*(``OK\*('' button to accept the current value
939 in the text-entry window and exit.
941 On exit, the contents of the text-entry window are written
942 to \fB\*p\fP's output.
945 .IP "\fB--gauge \fItext height width [percent]\fR"
948 box displays a meter along the bottom of the box.
949 The meter indicates the percentage.
950 New percentages are read from
951 standard input, one integer per line.
953 to reflect each new percentage.
954 If the standard input reads the string \*(``XXX\*('',
955 then the first line following is taken as an integer percentage,
956 then subsequent lines up to another \*(``XXX\*('' are used for a new prompt.
957 The gauge exits when EOF is reached on the standard input.
959 The \fIpercent\fR value denotes the initial percentage shown in the meter.
960 If not specified, it is zero.
962 On exit, no text is written to \fB\*p\fP's output.
963 The widget accepts no input, so the exit status is always OK.
966 .IP "\fB--infobox \fItext height width"
967 An \fBinfo\fP box is basically a \fBmessage\fP box.
968 However, in this case, \fB\*p\fP
969 will exit immediately after displaying the message to the user.
970 The screen is not cleared when \fB\*p\fP
971 exits, so that the message will remain on the screen until the calling
972 shell script clears it later.
973 This is useful when you want to inform
974 the user that some operations are carrying on that may require some
977 On exit, no text is written to \fB\*p\fP's output.
978 An OK exit status is returned.
981 .IP "\fB--inputbox \fItext height width [init]"
984 box is useful when you want to ask questions that
985 require the user to input a string as the answer.
987 it is used to initialize the input string.
988 When entering the string,
989 the \fIbackspace\fP, \fIdelete\fP and cursor keys
990 can be used to correct typing errors.
991 If the input string is longer than
992 can fit in the dialog box, the input field will be scrolled.
994 On exit, the input string will be printed on \fB\*p\fP's output.
997 .IP "\fB--inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
998 An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box.
999 There are only a few differences between them:
1003 The entries are not automatically centered but left adjusted.
1006 An extra button (called \fIRename\/\fP) is implied to rename
1007 the current item when it is pressed.
1010 It is possible to rename the current entry by pressing the
1013 Then \fB\*p\fP will write the following on \fB\*p\fP's output.
1015 RENAMED <tag> <item>
1019 .IP "\fB--menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
1020 As its name suggests, a
1022 box is a dialog box that can be used to present a list of choices in
1023 the form of a menu for the user to choose.
1024 Choices are displayed in the order given.
1025 Each menu entry consists of a \fItag\fP string and an \fIitem\fP string.
1027 gives the entry a name to distinguish it from the other entries in the
1029 The \fIitem\fP is a short description of the option that the entry represents.
1030 The user can move between the menu entries by pressing the
1031 cursor keys, the first letter of the \fItag\fP
1032 as a hot-key, or the number keys \fI1\fP through \fI9\fP.
1033 There are \fImenu-height\fP
1034 entries displayed in the menu at one time, but the menu will be
1035 scrolled if there are more entries than that.
1037 On exit the \fItag\fP
1038 of the chosen menu entry will be printed on \fB\*p\fP's output.
1039 If the "\fB--help-button\fR" option is given, the corresponding help
1040 text will be printed if the user selects the help button.
1043 .IP "\fB--mixedform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen itype \fR] \fI..."
1045 The \fBmixedform\fP dialog displays a form consisting of labels and fields,
1046 much like the \fB--form\fP dialog.
1047 It differs by adding a field-type parameter to each field's description.
1048 Each bit in the type denotes an attribute of the field:
1052 hidden, e.g., a password field.
1055 readonly, e.g., a label.
1058 .IP "\fB--mixedgauge \fItext height width percent \fR[ \fItag1 item1 \fR] \fI..."
1059 A \fBmixedgauge\fP box displays a meter along the bottom of the box.
1060 The meter indicates the percentage.
1062 It also displays a list of the \fItag\/\fP- and \fIitem\/\fP-values at the
1064 See \*l(3) for the tag values.
1066 The \fItext\fP is shown as a caption between the list and meter.
1067 The \fIpercent\fR value denotes the initial percentage shown in the meter.
1069 No provision is made for reading data from the standard input as \fB--gauge\fP
1072 On exit, no text is written to \fB\*p\fP's output.
1073 The widget accepts no input, so the exit status is always OK.
1075 .IP "\fB--msgbox \fItext height width"
1076 A \fBmessage\fP box is very similar to a \fByes/no\fP box.
1077 The only difference between a \fBmessage\fP box and a \fByes/no\fP
1078 box is that a \fBmessage\fP box has only a single \fBOK\fP button.
1079 You can use this dialog box to display any message you like.
1080 After reading the message, the user can press the \fIENTER\fP key so that
1081 \fB\*p\fP will exit and the calling shell script can continue its operation.
1083 If the message is too large for the space,
1084 \fB\*p\fP may allow you to scroll it,
1085 provided that the underlying curses implementation is capable enough.
1086 In this case, a percentage is shown in the base of the widget.
1088 On exit, no text is written to \fB\*p\fP's output.
1089 Only an \*(``OK\*('' button is provided for input,
1090 but an ESC exit status may be returned.
1092 .IP "\fB--pause \fItext height width seconds\fR"
1095 box displays a meter along the bottom of the box.
1096 The meter indicates how many seconds remain until the end of the pause.
1097 The pause exits when timeout is reached
1098 or the user presses the OK button
1100 or the user presses the CANCEL button
1102 .IP "\fB--passwordbox \fItext height width [init]"
1103 A \fBpassword\fP box is similar to an input box,
1104 except that the text the user enters is not displayed.
1105 This is useful when prompting for passwords or other
1106 sensitive information.
1107 Be aware that if anything is passed in \*(``init\*('', it
1108 will be visible in the system's process table to casual snoopers.
1110 is very confusing to the user to provide them with a default password they
1112 For these reasons, using \*(``init\*('' is highly discouraged.
1113 See "\fB--insecure\fP" if you do not care about your password.
1115 On exit, the input string will be printed on \fB\*p\fP's output.
1119 .IP "\fB--passwordform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
1121 This is identical to \fB--form\fP except that all text fields are
1122 treated as \fBpassword\fP widgets rather than \fBinputbox\fP widgets.
1125 .IP "\fB--prgbox \fItext command height width"
1126 .IP "\fB--prgbox \fIcommand height width"
1127 A \fBprgbox\fP is very similar to a \fBprogrambox\fP.
1129 This dialog box is used to display the output of a command that is
1130 specified as an argument to \fBprgbox\fP.
1132 After the command completes, the user can press the \fIENTER\fP key so that
1133 \fBdialog\fP will exit and the calling shell script can continue its operation.
1135 If three parameters are given, it displays the text under the title,
1136 delineated from the scrolling file's contents.
1137 If only two parameters are given, this text is omitted.
1140 .IP "\fB--programbox \fItext height width"
1141 .IP "\fB--programbox \fIheight width"
1142 A \fBprogrambox\fP is very similar to a \fBprogressbox\fP.
1143 The only difference between a \fBprogram\fP box and a \fBprogress\fP
1144 box is that a \fBprogram\fP box displays an \fBOK\fP button
1145 (but only after the command completes).
1147 This dialog box is used to display the piped output of a command.
1148 After the command completes, the user can press the \fIENTER\fP key so that
1149 \fBdialog\fP will exit and the calling shell script can continue its operation.
1151 If three parameters are given, it displays the text under the title,
1152 delineated from the scrolling file's contents.
1153 If only two parameters are given, this text is omitted.
1156 .IP "\fB--progressbox \fItext height width"
1157 .IP "\fB--progressbox \fIheight width"
1158 A \fBprogressbox\fP is similar to an \fBtailbox\fP,
1162 a) rather than displaying the contents of a file,
1163 it displays the piped output of a command and
1165 b) it will exit when it reaches the end of the file
1166 (there is no \*(``OK\*('' button).
1169 If three parameters are given, it displays the text under the title,
1170 delineated from the scrolling file's contents.
1171 If only two parameters are given, this text is omitted.
1174 .IP "\fB--radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
1175 A \fBradiolist\fP box is similar to a \fBmenu\fP box.
1176 The only difference is
1177 that you can indicate which entry is currently selected, by setting its
1178 .IR status " to " on "."
1180 On exit, the tag of the selected item is written to \fB\*p\fP's output.
1183 .IP "\fB--tailbox \fIfile height width"
1184 Display text from a file in a dialog box, as in a "tail -f" command.
1185 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1186 A '0' resets the scrolling.
1188 On exit, no text is written to \fB\*p\fP's output.
1189 Only an \*(``OK\*('' button is provided for input,
1190 but an ESC exit status may be returned.
1194 .IP "\fB--rangebox \fItext height width min-value max-value default-value"
1196 Allow the user to select from a range of values, e.g., using a slider.
1197 The dialog shows the current value as a bar (like the gauge dialog).
1198 Tabs or arrow keys move the cursor between the buttons and the value.
1199 When the cursor is on the value,
1203 left/right cursor movement to select a digit to modify
1206 characters to increment/decrement the digit by one
1209 to set the digit to the given value
1212 Some keys are also recognized in all cursor positions:
1216 set the value to its maximum or minimum
1219 increment the value so that the slider moves by one column
1223 .IP "\fB--tailboxbg \fIfile height width"
1224 Display text from a file in a dialog box as a background task,
1225 as in a "tail -f &" command.
1226 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1227 A '0' resets the scrolling.
1229 \*L treats the background task specially if there are other
1230 widgets (\fB--and-widget\fP) on the screen concurrently.
1231 Until those widgets are closed (e.g., an \*(``OK\*(''),
1232 \fB\*p\fP will perform all of the tailboxbg widgets in the same process,
1233 polling for updates.
1234 You may use a tab to traverse between the widgets on the screen,
1235 and close them individually, e.g., by pressing \fIENTER\fP.
1236 Once the non-tailboxbg widgets are closed, \fB\*p\fP forks a copy of itself
1237 into the background, and prints its process id if the "\fB--no-kill\fP" option
1240 On exit, no text is written to \fB\*p\fP's output.
1241 Only an \*(``EXIT\*('' button is provided for input,
1242 but an ESC exit status may be returned.
1245 Older versions of \fB\*p\fP forked immediately and attempted to
1246 update the screen individually.
1247 Besides being bad for performance,
1249 Some older scripts may not work properly with the polled scheme.
1252 .IP "\fB--textbox \fIfile height width"
1255 box lets you display the contents of a text file in a dialog box.
1256 It is like a simple text file viewer.
1257 The user can move through the file by using the
1258 cursor, page-up, page-down
1259 and \fIHOME/END\fR keys available on most keyboards.
1260 If the lines are too long to be displayed in the box,
1261 the \fILEFT/RIGHT\fP
1262 keys can be used to scroll the text region horizontally.
1263 You may also use vi-style keys h, j, k, and l in place of the cursor keys,
1264 and B or N in place of the page-up and page-down keys.
1265 Scroll up/down using vi-style 'k' and 'j', or arrow-keys.
1266 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1267 A '0' resets the left/right scrolling.
1268 For more convenience,
1269 vi-style forward and backward searching functions are also provided.
1271 On exit, no text is written to \fB\*p\fP's output.
1272 Only an \*(``EXIT\*('' button is provided for input,
1273 but an ESC exit status may be returned.
1276 .IP "\fB--timebox \fItext height [width hour minute second]"
1277 A dialog is displayed which allows you to select hour, minute and second.
1278 If the values for hour, minute or second are missing or negative,
1279 the current date's corresponding values are used.
1280 You can increment or decrement any of those using the
1281 left-, up-, right- and down-arrows.
1282 Use tab or backtab to move between windows.
1284 On exit, the result is printed in the form hour:minute:second.
1285 The format can be overridden using the \fB--time-format\fP option.
1288 .IP "\fB--treeview \fItext height width list-height \fR[ \fItag item status depth \fR] \fI..."
1289 Display data organized as a tree.
1290 Each group of data contains a tag,
1291 the text to display for the item,
1292 its status (\*(``on\*('' or \*(``off\*('')
1293 and the depth of the item in the tree.
1295 Only one item can be selected (like the \fBradiolist\fP).
1296 The tag is not displayed.
1298 On exit, the tag of the selected item is written to \fB\*p\fP's output.
1301 .IP "\fB--yesno \fItext height width"
1302 A \fByes/no\fP dialog box of
1303 size \fIheight\fP rows by \fIwidth\fP columns will be displayed.
1304 The string specified by
1306 is displayed inside the dialog box.
1307 If this string is too long to fit
1308 in one line, it will be automatically divided into multiple lines at
1312 string can also contain the sub-string
1314 or newline characters
1316 to control line breaking explicitly.
1317 This dialog box is useful for
1318 asking questions that require the user to answer either yes or no.
1319 The dialog box has a
1323 button, in which the user can switch between by pressing the
1326 On exit, no text is written to \fB\*p\fP's output.
1327 In addition to the \*(``Yes\*('' and \*(``No\*('' exit codes (see DIAGNOSTICS)
1328 an ESC exit status may be returned.
1330 The codes used for \*(``Yes\*('' and \*(``No\*(''
1331 match those used for \*(``OK\*('' and \*(``Cancel\*('',
1332 internally no distinction is made.
1334 .\" ************************************************************************
1335 .SS "Obsolete Options"
1336 .\" from cdialog 0.9a (Pako)
1338 This was used to tell the original cdialog that it should make a beep
1339 when the separate processes of the tailboxbg widget would repaint the screen.
1341 .\" from cdialog 0.9a (Pako)
1342 .IP "\fB--beep-after"
1343 Beep after a user has completed a widget by pressing one of the buttons.
1345 .\" ************************************************************************
1346 .SS "Whitespace Options"
1348 These options can be used to transform whitespace (space, tab, newline)
1349 as dialog reads the script:
1353 .BR --no-nl-expand ", and"
1357 The options are not independent:
1359 \fB\*L\fP checks if the script contains at least one \*(``\en\*(''
1360 and (unless \fB--no-nl-expand\fP is set) will ignore the
1361 \fB--no-collapse\fP and \fB--trim\fP options.
1363 After checking for \*(``\en\*('' and the \fB--no-nl-expand\fP option,
1364 \fB\*l\fP handles the \fB--trim\fP option.
1366 If the \fB--trim\fP option takes effect,
1367 then \fB\*l\fP ignores \fB--no-collapse\fP.
1368 It changes sequences of tabs, spaces
1369 (and newlines unless \fB-cr-wrap\fP is set) to a single space.
1371 If neither the \*(``\en\*('' or \fB--trim\fP cases apply,
1372 \fB\*l\fP checks \fB--no-collapse\fP to decide whether to reduce
1373 sequences of tabs and spaces to a single space.
1375 In this case, \fB\*l\fP ignores \fB-cr-wrap\fP and does not modify newlines.
1377 Taking those dependencies into account,
1378 here is a table summarizing the behavior
1379 for the various combinations of options.
1380 The table assumes that the script contains at least one \*(``\en\*(''
1381 when the \fB--no-nl-expand\fP option is not set.
1388 lw5 lw5 lw5 lw5 lw30.
1389 cr-/no-/no-/trim/Result
1390 wrap/collapse/nl-expand
1392 Convert tab to space.
1393 Convert newline to space.
1394 Convert \*(``\en\*('' to newline.
1397 Convert tab to space.
1398 Convert newline to space.
1399 Convert \*(``\en\*('' to newline.
1402 Convert tab to space.
1403 Do not convert newline to space.
1404 Convert multiple-space to single.
1405 Show \*(``\en\*('' literally.
1408 Convert tab to space.
1409 Convert multiple-space to single.
1410 Convert newline to space.
1411 Show \*(``\en\*('' literally.
1414 Convert newline to space.
1415 Convert \*(``\en\*('' to newline.
1418 Convert newline to space.
1419 Convert \*(``\en\*('' to newline.
1422 Do not convert newline to space.
1423 Do not reduce multiple blanks.
1424 Show \*(``\en\*('' literally.
1427 Convert multiple-space to single.
1428 Convert newline to space.
1429 Show \*(``\en\*('' literally.
1432 Convert tab to space.
1434 Convert \*(``\en\*('' to newline.
1437 Convert tab to space.
1439 Convert \*(``\en\*('' to newline.
1442 Convert tab to space.
1443 Do not convert newline to space.
1444 Convert multiple-space to single.
1445 Show \*(``\en\*('' literally.
1448 Convert tab to space.
1449 Convert multiple-space to single.
1451 Show \*(``\en\*('' literally.
1455 Convert \*(``\en\*('' to newline.
1459 Convert \*(``\en\*('' to newline.
1462 Do not convert newline to space.
1463 Do not reduce multiple blanks.
1464 Show \*(``\en\*('' literally.
1467 Convert multiple-space to single.
1469 Show \*(``\en\*('' literally.
1474 .\" ************************************************************************
1475 .SH "RUN-TIME CONFIGURATION"
1478 Create a sample configuration file by typing:
1481 \*p --create-rc \fIfile\fP
1487 determines the settings to use as follows:
1491 if environment variable
1493 is set, its value determines the name of the configuration file.
1496 if the file in (a) is not found, use the file
1497 \fI$HOME/.dialogrc\fP
1498 as the configuration file.
1501 if the file in (b) is not found, try using the GLOBALRC file determined at
1502 compile-time, i.e., \fI/etc/dialogrc\fP.
1505 if the file in (c) is not found, use compiled in defaults.
1509 Edit the sample configuration file and copy it to some place that
1511 can find, as stated in step 2 above.
1513 .\" ************************************************************************
1515 You can override or add to key bindings in \fB\*p\fP
1516 by adding to the configuration file.
1517 \fB\*L\fP's \fBbindkey\fP command maps single keys to its internal coding.
1519 bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP
1522 The \fIwidget\fP name can be "*" (all widgets), or
1523 specific widgets such as \fBtextbox\fP.
1524 Specific widget bindings override the "*" bindings.
1525 User-defined bindings override the built-in bindings.
1527 The \fIcurses_key\fP can be any of the names derived from
1528 \fBcurses.h\fP, e.g., \*(``HELP\*('' from \*(``KEY_HELP\*(''.
1529 \fB\*L\fP also recognizes ANSI control characters such as "^A", "^?",
1530 as well as C1-controls such as "~A" and "~?".
1531 Finally, it allows any single character to be escaped with a backslash.
1533 \fB\*L\fP's internal keycode names correspond to the
1534 \fBDLG_KEYS_ENUM\fP type in
1535 \fBdlg_keys.h\fP, e.g., \*(``HELP\*('' from \*(``DLGK_HELP\*(''.
1538 Some widgets (such as the formbox) have an area where fields can be edited.
1539 Those are managed in a subwindow of the widget, and
1540 may have separate keybindings from the main widget
1541 because the subwindows are registered using a different name.
1547 Widget/Window name/Subwindow Name
1550 editbox/editbox/editbox2
1551 form/formbox/formfield
1552 fselect/fselect/fselect2
1553 inputbox/inputbox/inputbox2
1557 progressbox/progressbox
1560 textbox/textbox/searchbox
1566 Some widgets are actually other widgets,
1567 using internal settings to modify the behavior.
1568 Those use the same widget name as the actual widget:
1574 Widget/Actual Widget
1579 passwordbox/inputbox
1582 programbox/progressbox
1586 .SS Built-in Bindings
1587 This manual page does not list the key bindings for each widget,
1588 because that detailed information can be obtained by running \fB\*p\fP.
1589 If you have set the \fB--trace\fP option,
1590 \fB\*p\fP writes the key-binding information for each widget
1591 as it is registered.
1593 Normally \fB\*p\fP uses different keys for navigating between the buttons
1594 and editing part of a dialog versus navigating within the editing part.
1595 That is, tab (and back-tab) traverse buttons
1596 (or between buttons and the editing part),
1597 while arrow keys traverse fields within the editing part.
1598 Tabs are also recognized as a special case for traversing between
1599 widgets, e.g., when using multiple tailboxbg widgets.
1601 Some users may wish to use the same key for traversing within the
1602 editing part as for traversing between buttons.
1603 The form widget is written to support this sort of redefinition of
1604 the keys, by adding a special group in \fBdlgk_keys.h\fP
1605 for \*(``form\*('' (left/right/next/prev).
1606 Here is an example binding demonstrating how to do this:
1608 bindkey formfield TAB form_NEXT
1609 bindkey formbox TAB form_NEXT
1610 bindkey formfield BTAB form_prev
1611 bindkey formbox BTAB form_prev
1614 That type of redefinition would not be useful in other widgets,
1615 e.g., calendar, due to the potentially large number of fields to traverse.
1617 .\" ************************************************************************
1621 Define this variable to apply any of the common options to each widget.
1622 Most of the common options are reset before processing each widget.
1623 If you set the options in this environment variable,
1624 they are applied to \fB\*p\fP's state after the reset.
1625 As in the "\fB--file\fP" option,
1626 double-quotes and backslashes are interpreted.
1628 The "\fB--file\fP" option is not considered a common option
1629 (so you cannot embed it within this environment variable).
1632 Define this variable if you want to specify the name of the configuration file
1645 \fBDIALOG_ITEM_HELP\fP
1648 Define any of these variables to change the exit code on
1654 Help with \fB--item-help\fP (2),
1656 Normally shell scripts cannot distinguish between \-1 and 255.
1659 Set this variable to \*(``1\*('' to provide compatibility with older versions
1660 of \fB\*p\fP which assumed that if the script redirects the standard output,
1661 that the "\fB--stdout\fP" option was given.
1664 \fI$HOME/.dialogrc\fP
1665 default configuration file
1667 The \fB\*p\fP sources contain several samples
1668 of how to use the different box options and how they look.
1669 Just take a look into the directory \fBsamples/\fP of the source.
1671 Exit status is subject to being overridden by environment variables.
1672 The default values and corresponding environment variables
1673 that can override them are:
1676 if the \fBYES\fP or \fBOK\fP button is pressed (DIALOG_OK).
1680 .BR No " or " Cancel
1681 button is pressed (DIALOG_CANCEL).
1686 button is pressed (DIALOG_HELP),
1688 except as noted below about DIALOG_ITEM_HELP.
1693 button is pressed (DIALOG_EXTRA).
1700 and the \fB--item-help\fP option is set
1702 and the DIALOG_ITEM_HELP environment variable is set to 4.
1704 While any of the exit-codes can be overridden using environment variables,
1705 this special case was introduced in 2004 to simplify compatibility.
1706 \fB\*L\fP uses DIALOG_ITEM_HELP(4) internally,
1707 but unless the environment variable is also set,
1708 it changes that to DIALOG_HELP(2) on exit.
1711 if errors occur inside \fB\*p\fP (DIALOG_ERROR)
1712 or \fB\*p\fP exits because the \fIESC\fP key (DIALOG_ESC) was pressed.
1714 .\" ************************************************************************
1716 \fB\*L\fP works with X/Open curses.
1717 However, some implementations have deficiencies:
1720 HPUX curses (and perhaps others) do not open the terminal properly for
1721 the \fInewterm\fP function.
1722 This interferes with \fB\*p\fP's \fB--input-fd\fP option,
1723 by preventing cursor-keys and similar escape sequences from being recognized.
1725 NetBSD 5.1 curses has incomplete support for wide-characters.
1726 \fB\*p\fP will build, but not all examples display properly.
1728 .\" ************************************************************************
1730 You may want to write scripts which run with
1731 other \fBdialog\fP \*(``clones\*(''.
1733 First, there is the \*(``original\*('' \fBdialog\fP program to consider
1734 (versions 0.3 to 0.9).
1735 It had some misspelled (or inconsistent) options.
1736 The \fB\*p\fP program maps those deprecated options to the preferred ones.
1745 \fB--beep-after\fP/ignored
1746 \fB--guage\fP/mapped to \fB--gauge\fP
1751 This is an X application, rather than a terminal program.
1752 With some care, it is possible to write useful scripts that work
1753 with both \fBXdialog\fP and \fBdialog\fP.
1755 The \fB\*p\fP program ignores these options which are recognized
1764 \fB--allow-close\fP/ignored
1765 \fB--auto-placement\fP/ignored
1766 \fB--fixed-font\fP/ignored
1767 \fB--icon\fP/ignored
1768 \fB--keep-colors\fP/ignored
1769 \fB--no-close\fP/ignored
1770 \fB--no-cr-wrap\fP/ignored
1771 \fB--screen-center\fP/ignored
1772 \fB--separator\fP/mapped to \fB--separate-output\fP
1773 \fB--smooth\fP/ignored
1774 \fB--under-mouse\fP/ignored
1775 \fB--wmclass\fP/ignored
1780 \fBXdialog\fP's manpage has a section discussing its compatibility
1782 There are some differences not shown in the manpage.
1783 For example, the html documentation states
1786 Note: former Xdialog releases used the "\en" (line feed) as a
1787 results separator for the checklist widget;
1788 this has been changed to "/" in Xdialog v1.5.0
1789 to make it compatible with (c)dialog.
1790 In your old scripts using the Xdialog checklist, you
1791 will then have to add the \fB--separate-output\fP option before the
1792 \fB--checklist\fP one.
1795 \fB\*L\fP has not used a different separator;
1796 the difference was likely due to confusion regarding some script.
1798 Then there is \fBwhiptail\fP.
1799 For practical purposes, it is maintained by Debian
1800 (very little work is done by its upstream developers).
1801 Its documentation (README.whiptail) claims
1803 whiptail(1) is a lightweight replacement for \*p(1),
1804 to provide dialog boxes for shell scripts.
1806 newt windowing library rather than the ncurses library, allowing
1807 it to be smaller in embedded environments such as installers,
1810 whiptail is designed to be drop-in compatible with \*p, but
1811 has less features: some dialog boxes are not implemented, such
1812 as tailbox, timebox, calendarbox, etc.
1815 Comparing actual sizes (Debian testing, 2007/1/10):
1816 The total of sizes for \fBwhiptail\fP,
1817 the newt, popt and slang libraries is 757\ KB.
1818 The comparable number for \fB\*p\fP (counting ncurses) is 520\ KB.
1819 Disregard the first paragraph.
1821 The second paragraph is misleading, since \fBwhiptail\fP
1822 also does not work for common options of \fB\*p\fP,
1823 such as the gauge box.
1824 \fBwhiptail\fP is less compatible with \fB\*p\fP than the
1825 original mid-1990s dialog 0.4 program.
1827 \fBwhiptail\fP's manpage borrows features from \fB\*p\fP, e.g.,
1828 but oddly cites only \fB\*p\fP versions up to 0.4 (1994) as a source.
1829 That is, its manpage refers to features which
1830 were borrowed from more recent versions of \fB\*p\fP, e.g.,
1832 \fB--gauge\fP (from 0.5)
1834 \fB--passwordbox\fP (from Debian changes in 1999),
1836 \fB--default-item\fP (from \fB\*p\fP 2000/02/22),
1838 \fB--output-fd\fP (from \fB\*p\fP 2002/08/14).
1840 Somewhat humorously, one may note that the \fBpopt\fP feature
1841 (undocumented in its manpage)
1842 of using a "--" as an escape was documented in \fB\*p\fP's manpage about
1843 a year before it was mentioned in \fBwhiptail\fP's manpage.
1844 \fBwhiptail\fP's manpage incorrectly attributes that to \fBgetopt\fP
1845 (and is inaccurate anyway).
1847 Debian uses \fBwhiptail\fP for the official \fB\*p\fP variation.
1849 The \fB\*p\fP program ignores or maps these options which are recognized
1858 \fB--cancel-button\fP/mapped to \fB--cancel-label\fP
1860 \fB--fullbutton\fP/ignored
1861 \fB--no-button\fP/mapped to \fB--no-label\fP
1862 \fB--nocancel\fP/mapped to \fB--no-cancel\fP
1863 \fB--noitem\fP/mapped to \fB--no-items\fP
1864 \fB--notags\fP/mapped to \fB--no-tags\fP
1865 \fB--ok-button\fP/mapped to \fB--ok-label\fP
1866 \fB--scrolltext\fP/mapped to \fB--scrollbar\fP
1867 \fB--topleft\fP/mapped to \fB--begin 0 0\fP
1868 \fB--yes-button\fP/mapped to \fB--yes-label\fP
1873 There are visual differences which are not addressed by command-line options:
1875 \fB\*p\fP centers lists within the window.
1876 \fBwhiptail\fP typically puts lists against the left margin.
1878 \fBwhiptail\fP uses angle brackets ("<" and ">") for marking buttons.
1879 \fB\*p\fP uses square brackets.
1881 \fBwhiptail\fP marks the limits of subtitles with vertical bars.
1882 \fB\*p\fP does not mark the limits.
1884 \fBwhiptail\fP attempts to mark the top/bottom cells of a scrollbar
1885 with up/down arrows.
1886 When it cannot do this,
1887 it fills those cells with the background color
1888 of the scrollbar and confusing the user.
1889 \fB\*p\fP uses the entire scrollbar space,
1890 thereby getting better resolution.
1891 .\" ************************************************************************
1896 Thomas E.\& Dickey (updates for 0.9b and beyond)
1898 Kiran Cherupally \(en the mixed form and mixed gauge widgets.
1900 Tobias C.\& Rittweiler
1902 Valery Reznic \(en the form and progressbox widgets.
1904 Yura Kalinichenko adapted the gauge widget as \*(``pause\*(''.
1906 This is a rewrite (except as needed to provide compatibility)
1907 of the earlier version of \fB\*p 0.9a\fP,
1908 which lists as authors:
1910 Savio Lam \(en version 0.3, \*(``dialog\*(''
1912 Stuart Herbert \(en patch for version 0.4
1914 Marc Ewing \(en the gauge widget.
1916 Pasquale De Marco \*(``Pako\*('' \(en version 0.9a, \*(``cdialog\*(''
projects / FreeBSD / FreeBSD.git / blob