2 .\" $Id: dialog.1,v 1.226 2021/01/17 17:25:01 tom Exp $
3 .\" Copyright 2005-2020,2021 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: 2021/01/17 17:25:01 $"
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)."
106 You can put more than one dialog box into a script:
108 Use the "\fB\-\-and\-widget\fP" token to force \fB\*p\fP to proceed to the next
109 dialog unless you have pressed ESC to cancel, or
111 Simply add the tokens for the next dialog box, making a chain.
112 \*L stops chaining when the return code from a dialog is nonzero,
113 e.g., Cancel or No (see DIAGNOSTICS).
115 Some widgets, e.g., checklist, will write text to \fB\*p\fP's output.
116 Normally that is the standard error, but there are options for
118 \*(``\fB\-\-output\-fd\fP\*('',
119 \*(``\fB\-\-stderr\fP\*('' and
120 \*(``\fB\-\-stdout\fP\*(''.
121 No text is written if the Cancel button (or ESC) is pressed;
122 \fB\*p\fP exits immediately in that case.
124 .\" ************************************************************************
126 All options begin with \*(``\fB--\fP\*(''
128 for the benefit of those using systems with deranged locale support).
130 A \*(``\fB--\fP\*('' by itself is used as an escape,
131 i.e., the next token on the command-line is not treated as an option.
133 .B \*p --title -- --Not an option
136 When a common (e.g., non-widget) option is repeated,
137 the last found is the one that is used.
138 Boolean options are handled specially so they can be cancelled,
139 by adding (or omitting) a \*(``no\*('' modifier
140 after the leading \*(``\fB--\fP\*(''.
141 For instance, \fB\-\-no-shadow\fP is documented here,
142 but \fB\-\-shadow\fP also is accepted.
144 The \*(``\fB\-\-args\fP\*('' option tells \fB\*p\fP to list the command-line
145 parameters to the standard error.
146 This is useful when debugging complex scripts using
147 the \*(``\fB--\fP\*('' and \*(``\fB\-\-file\fP\*('',
148 since the command-line may be rewritten as these are expanded.
150 The \*(``\fB\-\-file\fP\*('' option tells \fB\*p\fP to read parameters from
151 the file named as its value.
153 .B \*p --file \fIparameterfile
156 Blanks not within double-quotes are discarded
157 (use backslashes to quote single characters).
158 The result is inserted into the command-line,
159 replacing \*(``\fB\-\-file\fP\*('' and its option value.
160 Interpretation of the command-line resumes from that point.
161 If \fIparameterfile\fP begins with \*(``&\*('', \fB\*p\fP
162 interprets the following text as a file descriptor number
163 rather than a filename.
165 Most widgets accept \fIheight\fP and \fIwidth\fP parameters,
166 which can be used to automatically size the widget to accommodate
167 multi-line message \fIprompt\fP values:
169 If the parameter is negative,
170 \fB\*l\fP uses the screen's size.
172 If the parameter is zero,
173 \fB\*l\fP uses minimum size for the widget to display the \fIprompt\fP
176 Otherwise, \fB\*l\fP uses the given size for the widget.
178 .SS \fBCommon Options\fP
179 Most of the common options are reset before processing each widget.
181 .IP "\fB--ascii-lines
182 Rather than draw graphics lines around boxes,
183 draw ASCII \*(``+\*('' and \*(``-\*('' in the same place.
184 See also \*(``\fB\-\-no\-lines\fR\*(''.
186 .IP "\fB--aspect \fIratio"
187 This gives you some control over the box dimensions when using auto
188 sizing (specifying 0 for height and width).
189 It represents width / height.
190 The default is 9, which means 9 characters wide to every 1 line high.
192 .IP "\fB--backtitle \fIbacktitle"
195 string to be displayed on the backdrop, at the top of the screen.
197 .IP "\fB--begin \fIy x"
198 Specify the position of the upper left corner of a dialog box on the screen.
200 .IP "\fB--cancel-label \fIstring"
201 Override the label used for \*(``Cancel\*('' buttons.
204 Clears the widget screen, keeping only the screen_color background.
205 Use this when you combine widgets
206 with \*(``\fB\-\-and\-widget\fR\*('' to erase the
207 contents of a previous widget on the screen, so it won't be seen
208 under the contents of a following widget.
209 Understand this as the complement of \*(``\fB\-\-keep\-window\fR\*(''.
210 To compare the effects, use these:
213 All three widgets visible, staircase effect, ordered 1,2,3:
216 --begin 2 2 --yesno "" 0 0 \e
217 --and-widget --begin 4 4 --yesno "" 0 0 \e
218 --and-widget --begin 6 6 --yesno "" 0 0
222 Only the last widget is left visible:
225 --clear --begin 2 2 --yesno "" 0 0 \e
226 --and-widget --clear --begin 4 4 --yesno "" 0 0 \e
227 --and-widget --begin 6 6 --yesno "" 0 0
231 All three widgets visible, staircase effect, ordered 3,2,1:
234 --keep-window --begin 2 2 --yesno "" 0 0 \e
235 --and-widget --keep-window --begin 4 4 --yesno "" 0 0 \e
236 --and-widget --begin 6 6 --yesno "" 0 0
240 First and third widget visible, staircase effect, ordered 3,1:
243 --keep-window --begin 2 2 --yesno "" 0 0 \e
244 --and-widget --clear --begin 4 4 --yesno "" 0 0 \e
245 --and-widget --begin 6 6 --yesno "" 0 0
248 Note, if you want to restore original console colors and send your
249 cursor home after the dialog program has exited, use the \fBclear\fR\ (1)
251 Conversely, if you want to clear the screen and send your cursor to
252 the lower left after the \fB\*p\fP program has exited, use the
253 \fB\-\-erase\-on\-exit\fR\ option.
256 Interpret embedded \*(``\eZ\*('' sequences in the dialog text
257 by the following character,
258 which tells \fB\*p\fP to set colors or video attributes:
261 0 through 7 are the ANSI color numbers used in curses:
271 Bold is set by 'b', reset by 'B'.
273 Reverse is set by 'r', reset by 'R'.
275 Underline is set by 'u', reset by 'U'.
277 The settings are cumulative, e.g., \*(``\eZb\eZ1\*('' makes the following text
278 bold (perhaps bright) red.
280 Restore normal settings with \*(``\eZn\*(''.
283 .IP "\fB--column-separator \fIstring"
284 Tell \fB\*p\fP to split data for radio/checkboxes and menus on the
285 occurrences of the given string, and to align the split data into columns.
288 Interpret embedded newlines in the dialog text as a newline on the screen.
289 Otherwise, \fB\*p\fR will only wrap lines
290 where needed to fit inside the text box.
292 Even though you can control line breaks with this,
293 \fB\*L\fR will still wrap any lines that are too long for the width of the box.
294 Without cr-wrap, the layout of your text may be formatted to look nice
295 in the source code of your script without affecting the way it will
298 The \fIcr\-wrap\fP feature is implemented subject to these conditions:
301 the string contains \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option is
304 the \fB\-\-trim\fP option is used.
307 For more information, see \fBWhitespace Options\fP.
309 .IP "\fB--create-rc \fIfile"
312 supports run-time configuration,
313 this can be used to dump a sample configuration file to the file specified
317 .IP "\fB--cursor-off-label"
318 Place the terminal cursor at the end of a button instead of on the
319 first character of the button label.
320 This is useful to reduce visual confusion when the cursor coloration
321 interacts poorly with the button-label text colors.
323 .IP "\fB--date-format \fIformat"
324 If the host provides \fBstrftime\fP,
325 this option allows you to specify the format of the date printed for
326 the \fB\-\-calendar\fP widget.
327 The time of day (hour, minute, second) are the current local time.
330 Make the default value of the
334 Likewise, treat the default button of widgets that provide
335 \*(``OK\*('' and \*(``Cancel\*(''
337 If \*(``\fB\-\-no\-cancel\fP\*('' or \*(``\fB\-\-visit\-items\fP\*('' are given
338 those options overrides this,
339 making the default button always \*(``Yes\*(''
340 (internally the same as \*(``OK\*('').
342 .IP "\fB--default-button \fIstring"
343 Set the default (preselected) button in a widget.
344 By preselecting a button,
345 a script makes it possible for the user to simply press \fIEnter\fP
346 to proceed through a dialog with minimum interaction.
348 The option's value is the name of the button:
356 Normally the first button in each widget is the default.
357 The first button shown is determined by the widget
358 together with the \*(``\fB\-\-no\-ok\fP\*(''
359 and \*(``\fB\-\-no\-cancel\fP\*('' options.
360 If this option is not given, there is no default button assigned.
362 .IP "\fB--default-item \fIstring"
363 Set the default item in a checklist, form or menu box.
364 Normally the first item in the box is the default.
366 .IP "\fB--erase-on-exit"
367 When \fB\*p\fP exits, remove the dialog widget, erasing the entire
368 screen to its native background color, and place the terminal cursor
369 at the lower left corner.
371 .IP "\fB--exit-label \fIstring"
372 Override the label used for \*(``EXIT\*('' buttons.
374 .IP "\fB--extra-button"
375 Show an extra button, between \*(``OK\*('' and \*(``Cancel\*('' buttons.
377 .IP "\fB--extra-label \fIstring"
378 Override the label used for \*(``Extra\*('' buttons.
379 Note: for inputmenu widgets, this defaults to \*(``Rename\*(''.
382 Prints the help message to the standard output and exits.
383 The help message is also printed if no options are given,
384 or if an unrecognized option is given.
386 .IP "\fB--help-button"
387 Show a help-button after \*(``OK\*('' and \*(``Cancel\*('' buttons
388 in boxes which have a list of tagged items
389 (i.e., checklist, radiolist, menu, and treeview boxes).
391 On exit, the return status indicates that the Help button was pressed.
392 \fB\*L\fP also writes a message to its output
393 after the token \*(``HELP\*('':
396 If "\fB\-\-item\-help\fR" is also given, the item-help text is written.
398 Otherwise, the item's tag (the first field) is written.
402 You can use the \fB\-\-help\-tags\fP option and/or set the DIALOG_ITEM_HELP
403 environment variable to modify these messages and exit-status.
405 This option can be applied to other widgets,
406 which have an \*(``OK\*('' button,
407 whether or not the \*(``Cancel\*('' button is used.
408 The return status and output are not treated specially for the other widgets;
409 the help-button is just an extra button.
411 .IP "\fB--help-label \fIstring"
412 Override the label used for \*(``Help\*('' buttons.
414 .IP "\fB--help-status"
415 If the help-button is selected,
416 writes the checklist, radiolist or form information
417 after the item-help \*(``HELP\*('' information.
418 This can be used to reconstruct the state of a checklist after processing
422 Modify the messages written on exit for \fB\-\-help\-button\fP
423 by making them always just the item's tag.
424 This does not affect the exit status code.
426 .IP "\fB--hfile \fIfilename"
427 Display the given file using a textbox when the user presses F1.
429 .IP "\fB--hline \fIstring"
430 Display the given string centered at the bottom of the widget.
433 Ignore options that \fB\*p\fP does not recognize.
434 Some well-known ones such as \*(``\fB\-\-icon\fP\*('' are ignored anyway,
435 but this is a better choice for compatibility with other implementations.
437 .IP "\fB--input-fd \fIfd"
438 Read keyboard input from the given file descriptor.
439 Most \fB\*p\fR scripts read from the standard input,
440 but the gauge widget reads a pipe (which is always standard input).
441 Some configurations do not work properly when
442 \fB\*p\fP tries to reopen the terminal.
443 Use this option (with appropriate juggling of file-descriptors)
444 if your script must work in that type of environment.
447 Makes the password widget friendlier but less secure,
448 by echoing asterisks for each character.
451 Set the starting point for the week-number
452 shown in the \*(``\fB\-\-calendar\fP\*('' option
453 according to ISO-8601, which starts numbering
454 with the first week which includes a Thursday in January.
457 Interpret the tags data for checklist, radiolist and menu boxes
458 adding a column which is displayed in the bottom line of the
459 screen, for the currently selected item.
462 When built with \fBncurses\fP,
463 \fB\*p\fP normally checks to see if it is running in an \fBxterm\fP,
464 and in that case tries to suppress the initialization strings that
465 would make it switch to the alternate screen.
466 Switching between the normal and alternate screens
467 is visually distracting in a script which runs \fB\*p\fP
469 Use this option to allow \fB\*p\fP to use those initialization strings.
471 .IP "\fB--keep-window"
472 Normally when \fB\*p\fR performs several \fBtailboxbg\fR widgets
473 connected by \*(``\fB\-\-and\-widget\fR\*('',
474 it clears the old widget from the screen by painting over it.
475 Use this option to suppress that repainting.
477 At exit, \fB\*p\fR repaints all of the widgets which have been
478 marked with \*(``\fB\-\-keep\-window\fR\*('',
479 even if they are not \fBtailboxbg\fR widgets.
480 That causes them to be repainted in reverse order.
481 See the discussion of the \*(``\fB\-\-clear\fR\*('' option for examples.
484 At exit, report the last key which the user entered.
485 This is the curses key code rather than a symbol or literal character,
486 and is only reported for keys which are bound to an action.
487 It can be used by scripts to distinguish between two keys which are
488 bound to the same action.
490 .IP "\fB--max-input \fIsize"
491 Limit input strings to the given size.
492 If not specified, the limit is 2048.
495 Suppress the \*(``Cancel\*('' button in checklist, inputbox and menu box modes.
496 A script can still test if the user pressed the ESC key to cancel to quit.
498 .IP "\fB--no-collapse"
499 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
500 spaces to a single space for text which is displayed in a message boxes, etc.
501 Use this option to disable that feature.
502 Note that \fB\*p\fR will still wrap text,
503 subject to the \*(``\fB\-\-cr\-wrap\fR\*(''
504 and \*(``\fB\-\-trim\fR\*('' options.
506 The \fIno\-collapse\fP feature is implemented subject to these conditions:
509 the string contains \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option is
512 the \fB\-\-trim\fP option is not used.
515 For more information, see \fBWhitespace Options\fP.
517 .IP "\fB\-\-no\-hot\-list"
520 to suppress the hotkey feature for lists, e.g., the checkbox, menus.
522 Normally, the first uppercase character of a list entry will be highlighted,
523 and typing that character will move the focus to that entry.
524 This option suppresses both the highlighting and the movement.
526 Hotkeys for buttons (\*(``OK\*('' , \*(``Cancel\*('', etc.) are unaffected.
529 Some widgets (checklist, inputmenu, radiolist, menu) display a list
530 with two columns (a \*(``tag\*('' and \*(``item\*('',
531 i.e., \*(``description\*('').
532 This option tells \fB\*p\fP to read shorter rows,
533 omitting the \*(``item\*('' part of the list.
534 This is occasionally useful, e.g., if the tags provide enough information.
536 See also \fB\-\-no\-tags\fP.
537 If both options are given, this one is ignored.
544 box in the background,
545 printing its process id to \fB\*p\fP's output.
546 SIGHUP is disabled for the background process.
548 .IP "\fB--no-label \fIstring"
549 Override the label used for \*(``No\*('' buttons.
552 Rather than draw lines around boxes, draw spaces in the same place.
553 See also \*(``\fB\-\-ascii\-lines\fR\*(''.
556 Do not enable the mouse.
558 .IP "\fB--no-nl-expand
559 Do not convert \*(``\en\*('' substrings of the message/prompt text into
562 The \fIno\-nl\-expand\fP feature is used only if
563 the string contains \*(``\en\*('' so that there is something to convert.
565 For more information, see \fBWhitespace Options\fP.
568 Suppress the \*(``OK\*('' button, so that it is not displayed.
569 A script can still test if the user pressed
570 the \*(``Enter\*('' key to accept the data:
573 The \*(``Enter\*('' key is always handled as the \*(``OK\*('' button
574 when the \fB\-\-no\-ok\fP option is used.
575 That is, by default it is bound to the \fILEAVE\fP virtual key.
577 When \fB\-\-no\-ok\fP is not used,
578 you can use the the \fITab\fP key to move the cursor through the
579 fields and buttons on the widget.
580 In that case, the \*(``Enter\*('' key activates the current button
581 if the cursor is positioned on a button.
583 To provide for the case where you want to activate a button
584 when using \fB\-\-no\-ok\fP,
585 there is another virtual key \fILEAVE\fP,
586 which activates the current button.
587 By default, \fB^D\fP (EOF) is bound to that key.
591 Suppress shadows that would be drawn to the right and bottom of each dialog box.
594 Some widgets (checklist, inputmenu, radiolist, menu) display a list
595 with two columns (a \*(``tag\*('' and \*(``description\*('').
596 The tag is useful for scripting, but may not help the user.
597 The \fB\-\-no\-tags\fP option (from Xdialog) may be used to suppress the
598 column of tags from the display.
599 Unlike the \fB\-\-no\-items\fP option,
600 this does not affect the data which is read from the script.
602 Xdialog does not display the tag column for the analogous buildlist
603 and treeview widgets; \fB\*p\fP does the same.
605 Normally \fB\*p\fP allows you to quickly move to entries on the displayed list,
606 by matching a single character to the first character of the tag.
607 When the \fB\-\-no\-tags\fP option is given, \fB\*p\fP matches against
608 the first character of the description.
609 In either case, the matchable character is highlighted.
611 .IP "\fB--ok-label \fIstring"
612 Override the label used for \*(``OK\*('' buttons.
614 .IP "\fB--output-fd \fIfd"
615 Direct output to the given file descriptor.
616 Most \fB\*p\fR scripts write to the standard error,
617 but error messages may also be written there, depending on your script.
619 .IP "\fB--separator \fIstring"
620 .IP "\fB--output-separator \fIstring"
621 Specify a string that will separate the output on \fB\*p\fP's output from
622 checklists, rather than a newline (for \fB\-\-separate\-output\fP) or a space.
623 This applies to other widgets such as forms and editboxes which normally
626 .IP "\fB--print-maxsize"
627 Print the maximum size of dialog boxes, i.e., the screen size,
628 to \fB\*p\fP's output.
629 This may be used alone, without other options.
631 .IP "\fB--print-size"
632 Prints the size of each dialog box to \fB\*p\fP's output
633 when the box is initialized.
635 .IP "\fB--print-text-only \fIstring [ height [ width ] ]"
636 Prints the string as it would be wrapped in a message box
637 to \fB\*p\fP's output.
639 Because the optional \fIheight\fP and \fIwidth\fP default to zero,
640 if they are omitted, \fB\*p\fP autosizes according to the screen dimensions.
642 .IP "\fB--print-text-size \fIstring [ height [ width ] ]"
643 Prints the size of the string as it would be wrapped in a message box,
644 to \fB\*p\fP's output,
650 Because the optional \fIheight\fP and \fIwidth\fP parameters default to zero,
651 if they are omitted, \fB\*p\fP autosizes according to the screen dimensions.
653 .IP "\fB--print-version"
654 Prints \fB\*p\fR's version to \fB\*p\fP's output.
655 This may be used alone, without other options.
656 It does not cause \fB\*l\fP to exit by itself.
659 Normally \fB\*p\fP quotes the strings returned by checklist's
660 as well as the item-help text.
661 Use this option to quote all string results as needed
662 (i.e., if the string contains whitespace or a single or double-quote character).
665 By default, the buildlist widget uses the same order for the output (right)
666 list as for the input (left).
667 Use this option to tell \fB\*p\fP to use the order
668 in which a user adds selections to the output list.
671 For widgets holding a scrollable set of data,
672 draw a scrollbar on its right-margin.
673 This does not respond to the mouse.
675 .IP "\fB--separate-output"
676 For certain widgets (buildlist, checklist, treeview),
677 output result one line at a time, with no quoting.
678 This facilitates parsing by another program.
680 .IP "\fB--separate-widget \fIstring"
681 Specify a string that will separate the output on \fB\*p\fP's output from
683 This is used to simplify parsing the result of a dialog with several widgets.
684 If this option is not given,
685 the default separator string is a tab character.
687 .IP "\fB--single-quoted"
688 Use single-quoting as needed (and no quotes if unneeded) for the
689 output of checklist's as well as the item-help text.
691 If this option is not set, \fB\*p\fP may use double quotes around each item.
693 \fB\*p\fP adds backslashes to make the output useful in shell scripts.
695 Single quotes would be needed if
696 the string contains whitespace or a single or double-quote character.
699 Check the resulting size of a dialog box before trying to use it,
700 printing the resulting size if it is larger than the screen.
701 (This option is obsolete, since all new-window calls are checked).
703 .IP "\fB--sleep \fIsecs"
704 Sleep (delay) for the given number of seconds after processing a dialog box.
707 Direct output to the standard error.
708 This is the default, since curses normally writes screen updates to
712 Direct output to the standard output.
713 This option is provided for compatibility with Xdialog,
714 however using it in portable scripts is not recommended,
715 since curses normally writes its screen updates to the standard output.
716 If you use this option, \fB\*p\fR attempts to reopen the terminal
717 so it can write to the display.
718 Depending on the platform and your environment, that may fail.
720 .IP "\fB--tab-correct"
721 Convert each tab character to one or more spaces
722 (for the \fBtextbox\fP widget; otherwise to a single space).
723 Otherwise, tabs are rendered according to the curses library's interpretation.
724 The \fB\-\-no\-collapse\fP option disables tab expansion.
726 .IP "\fB--tab-len \fIn"
727 Specify the number of spaces that a tab character occupies if the
728 \*(``\fB\-\-tab\-correct\fP\*('' option is given.
730 This option is only effective for the \fBtextbox\fP widget.
732 .IP "\fB--time-format \fIformat"
733 If the host provides \fBstrftime\fP,
734 this option allows you to specify the format of the time printed for
735 the \fB\-\-timebox\fP widget.
736 The day, month, year values in this case are for the current local time.
738 .IP "\fB--timeout \fIsecs"
739 Timeout if no user response within the given number of seconds.
740 A timeout of zero seconds is ignored.
742 Normally a timeout causes an ESC character to be entered in the current widget,
744 Other widgets may still be on the screen;
745 these are not cancelled.
746 Set the \fBDIALOG_TIMEOUT\fP environment variable to tell \fB\*l\fP to
747 directly exit instead, i.e., cancelling all widgets on the screen.
749 This option is ignored by the \*(``\fB\-\-pause\fP\*('' widget.
750 It is also overridden
751 if the background \*(``\fB\-\-tailboxbg\fP\*('' option is used
752 to set up multiple concurrent widgets.
754 .IP "\fB--title \fItitle"
757 string to be displayed at the top of the dialog box.
759 .IP "\fB--trace \fIfilename"
760 logs the command-line parameters,
761 keystrokes and other information to the given file.
762 If \fB\*l\fP reads a configure file, it is logged as well.
763 Piped input to the \fIgauge\fP widget is logged.
764 Use control/T to log a picture of the current dialog window.
766 The \fB\*p\fR program handles some command-line parameters specially,
767 and removes them from the parameter list as they are processed.
768 For example, if the first option is \fB\-\-trace\fP,
769 then that is processed (and removed) before \fB\*p\fR initializes the display.
771 .IP "\fB--week-start \fIday"
772 sets the starting day for the week,
773 used in the \*(``\fB\-\-calendar\fP\*('' option.
774 The \fIday\fP parameter can be
777 a number (0 to 6, Sunday through Saturday using POSIX) or
779 the special value \*(``locale\*('' (this works with systems using glibc,
780 providing an extension to the \fBlocale\fP command,
781 the \fBfirst_weekday\fP value).
783 a string matching one of the abbreviations for the day of the week
784 shown in the \fBcalendar\fP widget, e.g., \*(``Mo\*('' for \*(``Monday\*(''.
788 eliminate leading blanks,
789 trim literal newlines and repeated blanks from message text.
791 The \fItrim\fP feature is implemented subject to these conditions:
794 the string does not contain \*(``\en\*('' or
796 the \fB\-\-no\-nl\-expand\fP option is used.
799 For more information, see \fBWhitespace Options\fP.
802 See also the \*(``\fB\-\-cr\-wrap\fR\*(''
803 and \*(``\fB\-\-no\-collapse\fR\*('' options.
806 Prints \fB\*p\fR's version to the standard output, and exits.
807 See also \*(``\fB\-\-print\-version\fP\*(''.
809 .IP "\fB--visit-items"
810 Modify the tab-traversal of checklist, radiolist, menubox and inputmenu
811 to include the list of items as one of the states.
812 This is useful as a visual aid,
813 i.e., the cursor position helps some users.
815 When this option is given, the cursor is initially placed on the list.
816 Abbreviations (the first letter of the tag) apply to the list items.
817 If you tab to the button row, abbreviations apply to the buttons.
819 .IP "\fB--yes-label \fIstring"
820 Override the label used for \*(``Yes\*('' buttons.
822 .\" ************************************************************************
824 All dialog boxes have at least three parameters:
827 the caption or contents of the box.
830 the height of the dialog box.
833 the width of the dialog box.
835 Other parameters depend on the box type.
838 .IP "\fB\-\-buildlist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
839 A \fBbuildlist\fP dialog displays two lists, side-by-side.
840 The list on the left shows unselected items.
841 The list on the right shows selected items.
842 As items are selected or unselected, they move between the lists.
844 Use a carriage return or the \*(``OK\*('' button to accept the current value
845 in the selected-window and exit.
846 The results are written using the order displayed in the selected-window.
848 The initial on/off state of each entry is specified by
851 The dialog behaves like a \fBmenu\fP, using the \fB\-\-visit\-items\fP
852 to control whether the cursor is allowed to visit the lists directly.
855 If \fB\-\-visit\-items\fP is not given,
856 tab-traversal uses two states (OK/Cancel).
858 If \fB\-\-visit\-items\fP is given,
859 tab-traversal uses four states (Left/Right/OK/Cancel).
862 Whether or not \fB\-\-visit\-items\fP is given,
863 it is possible to move the highlight between the two lists using
864 the default \*(``^\*('' (left-column) and \*(``$\*('' (right-column) keys.
866 On exit, a list of the \fItag\fP
867 strings of those entries that are turned on
868 will be printed on \fB\*p\fP's output.
870 If the "\fB\-\-separate\-output\fP" option is not given,
871 the strings will be quoted as needed
872 to make it simple for scripts to separate them.
873 By default, this uses double-quotes, as needed.
874 See the \*(``\fB\-\-single\-quoted\fP\*('' option,
875 which modifies the quoting behavior.
877 .IP "\fB--calendar \fItext height width day month year"
878 A \fBcalendar\fP box displays
879 month, day and year in separately adjustable windows.
880 If the values for day, month or year are missing or negative,
881 the current date's corresponding values are used.
882 You can increment or decrement any of those using the
883 left-, up-, right-, and down-arrows.
884 Use vi-style h, j, k and l for moving around the array of days in a month.
885 Use tab or backtab to move between windows.
886 If the year is given as zero, the current date is used as an initial value.
888 On exit, the date is printed in the form day/month/year.
889 The format can be overridden using the \fB\-\-date\-format\fP option.
891 .IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
892 A \fBchecklist\fP box is similar to a \fBmenu\fP box;
893 there are multiple entries presented in the form of a menu.
894 Another difference is
895 that you can indicate which entry is currently selected, by setting its
896 .IR status " to " on "."
898 one entry among the entries, each entry can be turned on or off by the user.
899 The initial on/off state of each entry is specified by
902 On exit, a list of the \fItag\fP
903 strings of those entries that are turned on
904 will be printed on \fB\*p\fP's output.
906 If the \*(``\fB\-\-separate\-output\fP\*('' option is not given,
907 the strings will be quoted as needed
908 to make it simple for scripts to separate them.
909 By default, this uses double-quotes (as needed).
910 See the \*(``\fB\-\-single\-quoted\fP\*('' option,
911 which modifies the quoting behavior.
913 .IP "\fB\-\-dselect \fIfilepath height width\fR"
914 The directory-selection dialog displays a text-entry window
915 in which you can type a directory,
916 and above that a windows with directory names.
920 can be a filepath in which case the directory window
921 will display the contents of the path and the text-entry window will contain
922 the preselected directory.
924 Use tab or arrow keys to move between the windows.
925 Within the directory window, 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
932 window to the closest match.
934 Use a carriage return or the \*(``OK\*('' button to accept the current value
935 in the text-entry window and exit.
937 On exit, the contents of the text-entry window are written
938 to \fB\*p\fP's output.
940 .IP "\fB\-\-editbox \fIfilepath height width\fR"
941 The edit-box dialog displays a copy of the file.
942 You may edit it using
943 the \fIbackspace\fP, \fIdelete\fP and cursor keys
944 to correct typing errors.
945 It also recognizes pageup/pagedown.
946 Unlike the \fB\-\-inputbox\fP,
947 you must tab to the \*(``OK\*('' or \*(``Cancel\*('' buttons
949 Pressing the \*(``Enter\*('' key within the box will split
950 the corresponding line.
952 On exit, the contents of the edit window are written to \fB\*p\fP's output.
955 .IP "\fB\-\-form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
957 The \fBform\fP dialog displays a form consisting of labels and fields,
958 which are positioned on a scrollable window by coordinates given in the script.
959 The field length \fIflen\fR and input-length \fIilen\fR tell how long
961 The former defines the length shown for a selected field,
962 while the latter defines the permissible length of the data entered in the
966 If \fIflen\fR is zero, the corresponding field cannot be altered.
967 and the contents of the field determine the displayed-length.
969 If \fIflen\fR is negative, the corresponding field cannot be altered,
970 and the negated value of \fIflen\fR is used as the displayed-length.
972 If \fIilen\fR is zero, it is set to \fIflen\fR.
975 Use up/down arrows (or control/N, control/P) to move between fields.
976 Use tab to move between windows.
978 On exit, the contents of the form-fields are written to \fB\*p\fP's output,
979 each field separated by a newline.
980 The text used to fill non-editable fields
981 (\fIflen\fR is zero or negative)
985 .IP "\fB\-\-fselect \fIfilepath height width\fR"
986 The \fBfselect\fP (file-selection) dialog displays a text-entry window
987 in which you can type a filename (or directory),
988 and above that two windows with directory names and filenames.
992 can be a filepath in which case the file and directory windows
993 will display the contents of the path and the text-entry window will contain
994 the preselected filename.
996 Use tab or arrow keys to move between the windows.
997 Within the directory or filename windows, use the up/down arrow keys
998 to scroll the current selection.
999 Use the space-bar to copy the current selection into the text-entry
1002 Typing any printable characters switches focus to the text-entry window,
1003 entering that character as well as scrolling the directory and filename
1004 windows to the closest match.
1006 Typing the space character forces \fB\*p\fP to complete the current
1007 name (up to the point where there may be a match against more than one
1010 Use a carriage return or the \*(``OK\*('' button to accept the current value
1011 in the text-entry window and exit.
1013 On exit, the contents of the text-entry window are written
1014 to \fB\*p\fP's output.
1017 .IP "\fB\-\-gauge \fItext height width [percent]\fR"
1020 box displays a meter along the bottom of the box.
1021 The meter indicates the percentage.
1022 New percentages are read from
1023 standard input, one integer per line.
1024 The meter is updated
1025 to reflect each new percentage.
1026 If the standard input reads the string \*(``XXX\*('',
1027 then the first line following is taken as an integer percentage,
1028 then subsequent lines up to another \*(``XXX\*('' are used for a new prompt.
1029 The gauge exits when EOF is reached on the standard input.
1031 The \fIpercent\fR value denotes the initial percentage shown in the meter.
1032 If not specified, it is zero.
1034 On exit, no text is written to \fB\*p\fP's output.
1035 The widget accepts no input, so the exit status is always OK.
1038 .IP "\fB--infobox \fItext height width"
1039 An \fBinfo\fP box is basically a \fBmessage\fP box.
1040 However, in this case, \fB\*p\fP
1041 will exit immediately after displaying the message to the user.
1042 The screen is not cleared when \fB\*p\fP
1043 exits, so that the message will remain on the screen until the calling
1044 shell script clears it later.
1045 This is useful when you want to inform
1046 the user that some operations are carrying on that may require some
1049 On exit, no text is written to \fB\*p\fP's output.
1050 An OK exit status is returned.
1053 .IP "\fB--inputbox \fItext height width [init]"
1056 box is useful when you want to ask questions that
1057 require the user to input a string as the answer.
1059 it is used to initialize the input string.
1060 When entering the string,
1061 the \fIbackspace\fP, \fIdelete\fP and cursor keys
1062 can be used to correct typing errors.
1063 If the input string is longer than
1064 can fit in the dialog box, the input field will be scrolled.
1066 On exit, the input string will be printed on \fB\*p\fP's output.
1069 .IP "\fB\-\-inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
1070 An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box.
1071 There are only a few differences between them:
1075 The entries are not automatically centered but left adjusted.
1078 An extra button (called \fIRename\/\fP) is implied to rename
1079 the current item when it is pressed.
1082 It is possible to rename the current entry by pressing the
1085 Then \fB\*p\fP will write the following on \fB\*p\fP's output.
1087 RENAMED <tag> <item>
1091 .IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
1092 As its name suggests, a
1094 box is a dialog box that can be used to present a list of choices in
1095 the form of a menu for the user to choose.
1096 Choices are displayed in the order given.
1097 Each menu entry consists of a \fItag\fP string and an \fIitem\fP string.
1099 gives the entry a name to distinguish it from the other entries in the
1101 The \fIitem\fP is a short description of the option that the entry represents.
1102 The user can move between the menu entries by pressing the
1103 cursor keys, the first letter of the \fItag\fP
1104 as a hot-key, or the number keys \fI1\fP through \fI9\fP.
1105 There are \fImenu-height\fP
1106 entries displayed in the menu at one time, but the menu will be
1107 scrolled if there are more entries than that.
1109 On exit the \fItag\fP
1110 of the chosen menu entry will be printed on \fB\*p\fP's output.
1111 If the \*(``\fB\-\-help\-button\fR\*('' option is given, the corresponding help
1112 text will be printed if the user selects the help button.
1115 .IP "\fB\-\-mixedform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen itype \fR] \fI..."
1117 The \fBmixedform\fP dialog displays a form consisting of labels and fields,
1118 much like the \fB\-\-form\fP dialog.
1119 It differs by adding a field-type parameter to each field's description.
1120 Each bit in the type denotes an attribute of the field:
1124 hidden, e.g., a password field.
1127 readonly, e.g., a label.
1130 .IP "\fB\-\-mixedgauge \fItext height width percent \fR[ \fItag1 item1 \fR] \fI..."
1131 A \fBmixedgauge\fP box displays a meter along the bottom of the box.
1132 The meter indicates the percentage.
1134 It also displays a list of the \fItag\/\fP- and \fIitem\/\fP-values at the
1136 See \*l(3) for the tag values.
1138 The \fItext\fP is shown as a caption between the list and meter.
1139 The \fIpercent\fR value denotes the initial percentage shown in the meter.
1141 No provision is made for reading data from the standard input as \fB\-\-gauge\fP
1144 On exit, no text is written to \fB\*p\fP's output.
1145 The widget accepts no input, so the exit status is always OK.
1147 .IP "\fB--msgbox \fItext height width"
1148 A \fBmessage\fP box is very similar to a \fByes/no\fP box.
1149 The only difference between a \fBmessage\fP box and a \fByes/no\fP
1150 box is that a \fBmessage\fP box has only a single \fBOK\fP button.
1151 You can use this dialog box to display any message you like.
1152 After reading the message, the user can press the \fIENTER\fP key so that
1153 \fB\*p\fP will exit and the calling shell script can continue its operation.
1155 If the message is too large for the space,
1156 \fB\*p\fP may allow you to scroll it,
1157 provided that the underlying curses implementation is capable enough.
1158 In this case, a percentage is shown in the base of the widget.
1160 On exit, no text is written to \fB\*p\fP's output.
1161 Only an \*(``OK\*('' button is provided for input,
1162 but an ESC exit status may be returned.
1164 .IP "\fB\-\-pause \fItext height width seconds\fR"
1167 box displays a meter along the bottom of the box.
1168 The meter indicates how many seconds remain until the end of the pause.
1169 The pause exits when timeout is reached
1170 or the user presses the OK button
1172 or the user presses the CANCEL button
1174 .IP "\fB--passwordbox \fItext height width [init]"
1175 A \fBpassword\fP box is similar to an input box,
1176 except that the text the user enters is not displayed.
1177 This is useful when prompting for passwords or other
1178 sensitive information.
1179 Be aware that if anything is passed in \*(``init\*('', it
1180 will be visible in the system's process table to casual snoopers.
1182 is very confusing to the user to provide them with a default password they
1184 For these reasons, using \*(``init\*('' is highly discouraged.
1185 See \*(``\fB\-\-insecure\fP\*('' if you do not care about your password.
1187 On exit, the input string will be printed on \fB\*p\fP's output.
1191 .IP "\fB\-\-passwordform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
1193 This is identical to \fB\-\-form\fP except that all text fields are
1194 treated as \fBpassword\fP widgets rather than \fBinputbox\fP widgets.
1197 .IP "\fB--prgbox \fItext command height width"
1198 .IP "\fB--prgbox \fIcommand height width"
1199 A \fBprgbox\fP is very similar to a \fBprogrambox\fP.
1201 This dialog box is used to display the output of a command that is
1202 specified as an argument to \fBprgbox\fP.
1204 After the command completes, the user can press the \fIENTER\fP key so that
1205 \fB\*l\fP will exit and the calling shell script can continue its operation.
1207 If four parameters are given, it displays the text under the title,
1208 delineated from the scrolling file's contents.
1209 If only three parameters are given, this text is omitted.
1212 .IP "\fB--programbox \fItext height width"
1213 .IP "\fB--programbox \fIheight width"
1214 A \fBprogrambox\fP is very similar to a \fBprogressbox\fP.
1215 The only difference between a \fBprogram\fP box and a \fBprogress\fP
1216 box is that a \fBprogram\fP box displays an \fBOK\fP button
1217 (but only after the command completes).
1219 This dialog box is used to display the piped output of a command.
1220 After the command completes, the user can press the \fIENTER\fP key so that
1221 \fB\*l\fP will exit and the calling shell script can continue its operation.
1223 If three parameters are given, it displays the text under the title,
1224 delineated from the scrolling file's contents.
1225 If only two parameters are given, this text is omitted.
1228 .IP "\fB--progressbox \fItext height width"
1229 .IP "\fB--progressbox \fIheight width"
1230 A \fBprogressbox\fP is similar to an \fBtailbox\fP,
1234 a) rather than displaying the contents of a file,
1235 it displays the piped output of a command and
1237 b) it will exit when it reaches the end of the file
1238 (there is no \*(``OK\*('' button).
1241 If three parameters are given, it displays the text under the title,
1242 delineated from the scrolling file's contents.
1243 If only two parameters are given, this text is omitted.
1246 .IP "\fB\-\-radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
1247 A \fBradiolist\fP box is similar to a \fBmenu\fP box.
1248 The only difference is
1249 that you can indicate which entry is currently selected, by setting its
1250 .IR status " to " on "."
1252 On exit, the tag of the selected item is written to \fB\*p\fP's output.
1256 .IP "\fB--rangebox \fItext height width min-value max-value default-value"
1258 Allow the user to select from a range of values, e.g., using a slider.
1259 The dialog shows the current value as a bar (like the gauge dialog).
1260 Tabs or arrow keys move the cursor between the buttons and the value.
1261 When the cursor is on the value,
1265 left/right cursor movement to select a digit to modify
1268 characters to increment/decrement the digit by one
1271 to set the digit to the given value
1274 Some keys are also recognized in all cursor positions:
1278 set the value to its maximum or minimum
1281 increment the value so that the slider moves by one column
1285 .IP "\fB--tailbox \fIfile height width"
1286 Display text from a file in a dialog box,
1287 as in a \*(``tail -f\*('' command.
1288 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1289 A '0' resets the scrolling.
1291 On exit, no text is written to \fB\*p\fP's output.
1292 Only an \*(``OK\*('' button is provided for input,
1293 but an ESC exit status may be returned.
1296 .IP "\fB--tailboxbg \fIfile height width"
1297 Display text from a file in a dialog box as a background task,
1298 as in a \*(``tail -f &\*('' command.
1299 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1300 A '0' resets the scrolling.
1302 \*L treats the background task specially if there are other
1303 widgets (\fB\-\-and\-widget\fP) on the screen concurrently.
1304 Until those widgets are closed (e.g., an \*(``OK\*(''),
1305 \fB\*p\fP will perform all of the tailboxbg widgets in the same process,
1306 polling for updates.
1307 You may use a tab to traverse between the widgets on the screen,
1308 and close them individually, e.g., by pressing \fIENTER\fP.
1309 Once the non-tailboxbg widgets are closed,
1310 \fB\*p\fP forks a copy of itself into the background,
1311 and prints its process id if the \*(``\fB\-\-no\-kill\fP\*('' option
1314 On exit, no text is written to \fB\*p\fP's output.
1315 Only an \*(``EXIT\*('' button is provided for input,
1316 but an ESC exit status may be returned.
1319 Older versions of \fB\*p\fP forked immediately and attempted to
1320 update the screen individually.
1321 Besides being bad for performance,
1323 Some older scripts may not work properly with the polled scheme.
1326 .IP "\fB--textbox \fIfile height width"
1329 box lets you display the contents of a text file in a dialog box.
1330 It is like a simple text file viewer.
1331 The user can move through the file by using the
1332 cursor, page-up, page-down
1333 and \fIHOME/END\fR keys available on most keyboards.
1334 If the lines are too long to be displayed in the box,
1335 the \fILEFT/RIGHT\fP
1336 keys can be used to scroll the text region horizontally.
1337 You may also use vi-style keys h, j, k, and l in place of the cursor keys,
1338 and B or N in place of the page-up and page-down keys.
1339 Scroll up/down using vi-style 'k' and 'j', or arrow-keys.
1340 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1341 A '0' resets the left/right scrolling.
1342 For more convenience,
1343 vi-style forward and backward searching functions are also provided.
1345 On exit, no text is written to \fB\*p\fP's output.
1346 Only an \*(``EXIT\*('' button is provided for input,
1347 but an ESC exit status may be returned.
1350 .IP "\fB--timebox \fItext height [width hour minute second]"
1351 A dialog is displayed which allows you to select hour, minute and second.
1352 If the values for hour, minute or second are missing or negative,
1353 the current date's corresponding values are used.
1354 You can increment or decrement any of those using the
1355 left-, up-, right- and down-arrows.
1356 Use tab or backtab to move between windows.
1358 On exit, the result is printed in the form hour:minute:second.
1359 The format can be overridden using the \fB\-\-time\-format\fP option.
1362 .IP "\fB\-\-treeview \fItext height width list-height \fR[ \fItag item status depth \fR] \fI..."
1363 Display data organized as a tree.
1364 Each group of data contains a tag,
1365 the text to display for the item,
1366 its status (\*(``on\*('' or \*(``off\*('')
1367 and the depth of the item in the tree.
1369 Only one item can be selected (like the \fBradiolist\fP).
1370 The tag is not displayed.
1372 On exit, the tag of the selected item is written to \fB\*p\fP's output.
1375 .IP "\fB--yesno \fItext height width"
1376 A \fByes/no\fP dialog box of
1377 size \fIheight\fP rows by \fIwidth\fP columns will be displayed.
1378 The string specified by
1380 is displayed inside the dialog box.
1381 If this string is too long to fit
1382 in one line, it will be automatically divided into multiple lines at
1386 string can also contain the sub-string
1388 or newline characters
1390 to control line breaking explicitly.
1391 This dialog box is useful for
1392 asking questions that require the user to answer either yes or no.
1393 The dialog box has a
1397 button, in which the user can switch between by pressing the
1400 On exit, no text is written to \fB\*p\fP's output.
1401 In addition to the \*(``Yes\*('' and \*(``No\*('' exit codes (see DIAGNOSTICS)
1402 an ESC exit status may be returned.
1404 The codes used for \*(``Yes\*('' and \*(``No\*(''
1405 match those used for \*(``OK\*('' and \*(``Cancel\*('',
1406 internally no distinction is made.
1408 .\" ************************************************************************
1409 .SS "Obsolete Options"
1410 .\" from cdialog 0.9a (Pako)
1412 This was used to tell the original cdialog that it should make a beep
1413 when the separate processes of the tailboxbg widget would repaint the screen.
1415 .\" from cdialog 0.9a (Pako)
1416 .IP "\fB--beep-after"
1417 Beep after a user has completed a widget by pressing one of the buttons.
1419 .\" ************************************************************************
1420 .SS "Whitespace Options"
1422 These options can be used to transform whitespace (space, tab, newline)
1423 as dialog reads the script:
1427 .BR --no-nl-expand ", and"
1431 The options are not independent:
1433 \fB\*L\fP checks if the script contains at least one \*(``\en\*(''
1434 and (unless \fB\-\-no\-nl\-expand\fP is set) will ignore the
1435 \fB\-\-no\-collapse\fP and \fB\-\-trim\fP options.
1437 After checking for \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option,
1438 \fB\*l\fP handles the \fB\-\-trim\fP option.
1440 If the \fB\-\-trim\fP option takes effect,
1441 then \fB\*l\fP ignores \fB\-\-no\-collapse\fP.
1442 It changes sequences of tabs, spaces
1443 (and newlines unless \fB\-cr\-wrap\fP is set) to a single space.
1445 If neither the \*(``\en\*('' or \fB\-\-trim\fP cases apply,
1446 \fB\*l\fP checks \fB\-\-no\-collapse\fP to decide whether to reduce
1447 sequences of tabs and spaces to a single space.
1449 In this case, \fB\*l\fP ignores \fB\-\-cr\-wrap\fP and does not modify newlines.
1451 Taking those dependencies into account,
1452 here is a table summarizing the behavior
1453 for the various combinations of options.
1454 The table assumes that the script contains at least one \*(``\en\*(''
1455 when the \fB\-\-no\-nl\-expand\fP option is not set.
1463 lw4 lw4 lw4 lw4 lw29.
1464 cr-/no-/no-/trim/Result
1465 wrap/collapse/nl-expand
1467 Convert tab to space.
1468 Convert newline to space.
1469 Convert \*(``\en\*('' to newline.
1472 Convert tab to space.
1473 Convert newline to space.
1474 Convert \*(``\en\*('' to newline.
1477 Convert tab to space.
1478 Do not convert newline to space.
1479 Convert multiple-space to single.
1480 Show \*(``\en\*('' literally.
1483 Convert tab to space.
1484 Convert multiple-space to single.
1485 Convert newline to space.
1486 Show \*(``\en\*('' literally.
1489 Convert newline to space.
1490 Convert \*(``\en\*('' to newline.
1493 Convert newline to space.
1494 Convert \*(``\en\*('' to newline.
1497 Do not convert newline to space.
1498 Do not reduce multiple blanks.
1499 Show \*(``\en\*('' literally.
1502 Convert multiple-space to single.
1503 Convert newline to space.
1504 Show \*(``\en\*('' literally.
1507 Convert tab to space.
1509 Convert \*(``\en\*('' to newline.
1512 Convert tab to space.
1514 Convert \*(``\en\*('' to newline.
1517 Convert tab to space.
1518 Do not convert newline to space.
1519 Convert multiple-space to single.
1520 Show \*(``\en\*('' literally.
1523 Convert tab to space.
1524 Convert multiple-space to single.
1526 Show \*(``\en\*('' literally.
1530 Convert \*(``\en\*('' to newline.
1534 Convert \*(``\en\*('' to newline.
1537 Do not convert newline to space.
1538 Do not reduce multiple blanks.
1539 Show \*(``\en\*('' literally.
1542 Convert multiple-space to single.
1544 Show \*(``\en\*('' literally.
1550 .\" ************************************************************************
1551 .SH "RUN-TIME CONFIGURATION"
1554 Create a sample configuration file by typing:
1557 \*p \-\-create\-rc \fIfile\fP
1563 determines the settings to use as follows:
1567 if environment variable
1569 is set, its value determines the name of the configuration file.
1572 if the file in (a) is not found, use the file
1573 \fI$HOME/.dialogrc\fP
1574 as the configuration file.
1577 if the file in (b) is not found, try using the GLOBALRC file determined at
1578 compile-time, i.e., \fI/etc/dialogrc\fP.
1581 if the file in (c) is not found, use compiled in defaults.
1585 Edit the sample configuration file and copy it to some place that
1587 can find, as stated in step 2 above.
1589 .\" ************************************************************************
1591 You can override or add to key bindings in \fB\*p\fP
1592 by adding to the configuration file.
1593 \fB\*L\fP's \fBbindkey\fP command maps single keys to its internal coding.
1595 bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP
1598 The \fIwidget\fP name can be \*(``*\*('' (all widgets), or
1599 specific widgets such as \fBtextbox\fP.
1600 Specific widget bindings override the \*(``*\*('' bindings.
1601 User-defined bindings override the built-in bindings.
1603 The \fIcurses_key\fP can be expressed in different forms:
1605 It may be any of the names derived from
1606 \fBcurses.h\fP, e.g., \*(``HELP\*('' from \*(``KEY_HELP\*(''.
1608 \fB\*L\fP also recognizes ANSI control characters
1609 such as \*(``^A\*('', \*(``^?\*('',
1610 as well as C1-controls such as \*(``~A\*('' and \*(``~?\*(''.
1612 Finally, \fB\*l\fP allows backslash escapes as in C.
1613 Those can be octal character values such as \*(``\\033\*(''
1614 (the ASCII escape character),
1615 or the characters listed in this table:
1625 \\n/new line (line feed)
1629 \\^/\*(``^\*('' (caret)
1630 \\?/\*(``?\*('' (question mark)
1631 \\\\/\*(``\\\*('' (backslash)
1636 \fB\*L\fP's internal keycode names correspond to the
1637 \fBDLG_KEYS_ENUM\fP type in
1638 \fBdlg_keys.h\fP, e.g., \*(``HELP\*('' from \*(``DLGK_HELP\*(''.
1641 Some widgets (such as the formbox) have an area where fields can be edited.
1642 Those are managed in a subwindow of the widget, and
1643 may have separate keybindings from the main widget
1644 because the subwindows are registered using a different name.
1651 Widget/Window name/Subwindow Name
1654 editbox/editbox/editbox2
1655 form/formbox/formfield
1656 fselect/fselect/fselect2
1657 inputbox/inputbox/inputbox2
1661 progressbox/progressbox
1664 textbox/textbox/searchbox
1671 Some widgets are actually other widgets,
1672 using internal settings to modify the behavior.
1673 Those use the same widget name as the actual widget:
1680 Widget/Actual Widget
1685 passwordbox/inputbox
1688 programbox/progressbox
1693 .SS Built-in Bindings
1694 This manual page does not list the key bindings for each widget,
1695 because that detailed information can be obtained by running \fB\*p\fP.
1696 If you have set the \fB\-\-trace\fP option,
1697 \fB\*p\fP writes the key-binding information for each widget
1698 as it is registered.
1700 Normally \fB\*p\fP uses different keys for navigating between the buttons
1701 and editing part of a dialog versus navigating within the editing part.
1702 That is, tab (and back-tab) traverse buttons
1703 (or between buttons and the editing part),
1704 while arrow keys traverse fields within the editing part.
1705 Tabs are also recognized as a special case for traversing between
1706 widgets, e.g., when using multiple tailboxbg widgets.
1708 Some users may wish to use the same key for traversing within the
1709 editing part as for traversing between buttons.
1710 The form widget is written to support this sort of redefinition of
1711 the keys, by adding a special group in \fBdlgk_keys.h\fP
1712 for \*(``form\*('' (left/right/next/prev).
1713 Here is an example binding demonstrating how to do this:
1715 bindkey formfield TAB form_NEXT
1716 bindkey formbox TAB form_NEXT
1717 bindkey formfield BTAB form_prev
1718 bindkey formbox BTAB form_prev
1721 That type of redefinition would not be useful in other widgets,
1722 e.g., calendar, due to the potentially large number of fields to traverse.
1724 .\" ************************************************************************
1728 Define this variable to apply any of the common options to each widget.
1729 Most of the common options are reset before processing each widget.
1730 If you set the options in this environment variable,
1731 they are applied to \fB\*p\fP's state after the reset.
1732 As in the \*(``\fB\-\-file\fP\*('' option,
1733 double-quotes and backslashes are interpreted.
1735 The \*(``\fB\-\-file\fP\*('' option is not considered a common option
1736 (so you cannot embed it within this environment variable).
1739 Define this variable if you want to specify the name of the configuration file
1752 \fBDIALOG_ITEM_HELP\fP
1754 \fBDIALOG_TIMEOUT\fP
1757 Define any of these variables to change the exit code on
1770 Help with \fB\-\-item\-help\fP (2),
1777 Normally shell scripts cannot distinguish between \-1 and 255.
1780 Set this variable to \*(``1\*('' to provide compatibility with older versions
1781 of \fB\*p\fP which assumed that if the script redirects the standard output,
1782 that the \*(``\fB\-\-stdout\fP\*('' option was given.
1785 \fI$HOME/.dialogrc\fP
1786 default configuration file
1788 The \fB\*p\fP sources contain several samples
1789 of how to use the different box options and how they look.
1790 Just take a look into the directory \fBsamples/\fP of the source.
1792 Exit status is subject to being overridden by environment variables.
1793 The default values and corresponding environment variables
1794 that can override them are:
1797 if the \fBYES\fP or \fBOK\fP button is pressed (DIALOG_OK).
1801 .BR No " or " Cancel
1802 button is pressed (DIALOG_CANCEL).
1807 button is pressed (DIALOG_HELP),
1809 except as noted below about DIALOG_ITEM_HELP.
1814 button is pressed (DIALOG_EXTRA).
1821 and the \fB\-\-item\-help\fP option is set
1823 and the DIALOG_ITEM_HELP environment variable is set to 4.
1825 While any of the exit-codes can be overridden using environment variables,
1826 this special case was introduced in 2004 to simplify compatibility.
1827 \fB\*L\fP uses DIALOG_ITEM_HELP(4) internally,
1828 but unless the environment variable is also set,
1829 it changes that to DIALOG_HELP(2) on exit.
1832 if a timeout expires and the \fBDIALOG_TIMEOUT\fP variable is set to 5.
1835 if errors occur inside \fB\*p\fP (DIALOG_ERROR)
1836 or \fB\*p\fP exits because the \fIESC\fP key (DIALOG_ESC) was pressed.
1838 .\" ************************************************************************
1840 \fB\*L\fP works with X/Open curses.
1841 However, some implementations have deficiencies:
1844 HPUX curses (and perhaps others) do not open the terminal properly for
1845 the \fInewterm\fP function.
1846 This interferes with \fB\*p\fP's \fB\-\-input\-fd\fP option,
1847 by preventing cursor-keys and similar escape sequences from being recognized.
1849 NetBSD 5.1 curses has incomplete support for wide-characters.
1850 \fB\*p\fP will build, but not all examples display properly.
1852 .\" ************************************************************************
1854 You may want to write scripts which run with
1855 other \fB\*l\fP \*(``clones\*(''.
1857 First, there is the \*(``original\*('' \fB\*p\fP program to consider
1858 (versions 0.3 to 0.9).
1859 It had some misspelled (or inconsistent) options.
1860 The \fB\*p\fP program maps those deprecated options to the preferred ones.
1869 \fB\-\-beep\-after\fP/ignored
1870 \fB\-\-guage\fP/mapped to \fB\-\-gauge\fP
1875 This is an X application, rather than a terminal program.
1876 With some care, it is possible to write useful scripts that work
1877 with both \fBXdialog\fP and \fB\*p\fP.
1879 The \fB\*p\fP program ignores these options which are recognized
1888 \fB\-\-allow\-close\fP/ignored
1889 \fB\-\-auto\-placement\fP/ignored
1890 \fB\-\-fixed\-font\fP/ignored
1891 \fB\-\-icon\fP/ignored
1892 \fB\-\-keep\-colors\fP/ignored
1893 \fB\-\-no\-close\fP/ignored
1894 \fB\-\-no\-cr\-wrap\fP/ignored
1895 \fB\-\-screen\-center\fP/ignored
1896 \fB\-\-separator\fP/mapped to \fB\-\-separate\-output\fP
1897 \fB\-\-smooth\fP/ignored
1898 \fB\-\-under\-mouse\fP/ignored
1899 \fB\-\-wmclass\fP/ignored
1904 \fBXdialog\fP's manpage has a section discussing its compatibility
1906 There are some differences not shown in the manpage.
1907 For example, the html documentation states
1910 Note: former Xdialog releases used the \*(``\en\*('' (line feed) as a
1911 results separator for the checklist widget;
1912 this has been changed to \*(``/\*('' in Xdialog v1.5.0
1913 to make it compatible with (c)dialog.
1914 In your old scripts using the Xdialog checklist, you
1915 will then have to add the \fB\-\-separate\-output\fP option before the
1916 \fB\-\-checklist\fP one.
1919 \fB\*L\fP has not used a different separator;
1920 the difference was likely due to confusion regarding some script.
1922 Then there is \fBwhiptail\fP.
1923 For practical purposes, it is maintained by Debian
1924 (very little work is done by its upstream developers).
1925 Its documentation (README.whiptail) claims
1927 whiptail(1) is a lightweight replacement for \*p(1),
1928 to provide dialog boxes for shell scripts.
1930 newt windowing library rather than the ncurses library, allowing
1931 it to be smaller in embedded environments such as installers,
1934 whiptail is designed to be drop-in compatible with \*p, but
1935 has less features: some dialog boxes are not implemented, such
1936 as tailbox, timebox, calendarbox, etc.
1939 Comparing actual sizes (Debian testing, 2007/1/10):
1940 The total of sizes for \fBwhiptail\fP,
1941 the newt, popt and slang libraries is 757\ KB.
1942 The comparable number for \fB\*p\fP (counting ncurses) is 520\ KB.
1943 Disregard the first paragraph.
1945 The second paragraph is misleading, since \fBwhiptail\fP
1946 also does not work for common options of \fB\*p\fP,
1947 such as the gauge box.
1948 \fBwhiptail\fP is less compatible with \fB\*p\fP than the
1949 original mid-1990s dialog 0.4 program.
1951 \fBwhiptail\fP's manpage borrows features from \fB\*p\fP, e.g.,
1952 but oddly cites only \fB\*p\fP versions up to 0.4 (1994) as a source.
1953 That is, its manpage refers to features which
1954 were borrowed from more recent versions of \fB\*p\fP, e.g.,
1956 \fB\-\-gauge\fP (from 0.5)
1958 \fB\-\-passwordbox\fP (from Debian changes in 1999),
1960 \fB\-\-default\-item\fP (from \fB\*p\fP 2000/02/22),
1962 \fB\-\-output\-fd\fP (from \fB\*p\fP 2002/08/14).
1964 Somewhat humorously, one may note that the \fBpopt\fP feature
1965 (undocumented in its manpage)
1966 of using a \*(``--\*('' as an escape was documented in \fB\*p\fP's manpage about
1967 a year before it was mentioned in \fBwhiptail\fP's manpage.
1968 \fBwhiptail\fP's manpage incorrectly attributes that to \fBgetopt\fP
1969 (and is inaccurate anyway).
1971 Debian uses \fBwhiptail\fP for the official \fB\*p\fP variation.
1973 The \fB\*p\fP program ignores or maps these options which are recognized
1982 \fB\-\-cancel\-button\fP/mapped to \fB\-\-cancel\-label\fP
1983 \fB\-\-fb\fP/ignored
1984 \fB\-\-fullbutton\fP/ignored
1985 \fB\-\-no\-button\fP/mapped to \fB\-\-no\-label\fP
1986 \fB\-\-nocancel\fP/mapped to \fB\-\-no\-cancel\fP
1987 \fB\-\-noitem\fP/mapped to \fB\-\-no\-items\fP
1988 \fB\-\-notags\fP/mapped to \fB\-\-no\-tags\fP
1989 \fB\-\-ok\-button\fP/mapped to \fB\-\-ok\-label\fP
1990 \fB\-\-scrolltext\fP/mapped to \fB\-\-scrollbar\fP
1991 \fB\-\-topleft\fP/mapped to \fB\-\-begin 0 0\fP
1992 \fB\-\-yes\-button\fP/mapped to \fB\-\-yes\-label\fP
1997 There are visual differences which are not addressed by command-line options:
1999 \fB\*p\fP centers lists within the window.
2000 \fBwhiptail\fP typically puts lists against the left margin.
2002 \fBwhiptail\fP uses angle brackets (\*(``<\*('' and \*(``>\*('')
2003 for marking buttons.
2004 \fB\*p\fP uses square brackets.
2006 \fBwhiptail\fP marks the limits of subtitles with vertical bars.
2007 \fB\*p\fP does not mark the limits.
2009 \fBwhiptail\fP attempts to mark the top/bottom cells of a scrollbar
2010 with up/down arrows.
2011 When it cannot do this,
2012 it fills those cells with the background color
2013 of the scrollbar and confusing the user.
2014 \fB\*p\fP uses the entire scrollbar space,
2015 thereby getting better resolution.
2016 .\" ************************************************************************
2021 Thomas E.\& Dickey (updates for 0.9b and beyond)
2023 Kiran Cherupally \(en the mixed form and mixed gauge widgets.
2025 Tobias C.\& Rittweiler
2027 Valery Reznic \(en the form and progressbox widgets.
2029 Yura Kalinichenko adapted the gauge widget as \*(``pause\*(''.
2031 This is a rewrite (except as needed to provide compatibility)
2032 of the earlier version of \fB\*p 0.9a\fP,
2033 which lists as authors:
2035 Savio Lam \(en version 0.3, \*(``dialog\*(''
2037 Stuart Herbert \(en patch for version 0.4
2039 Marc Ewing \(en the gauge widget.
2041 Pasquale De Marco \*(``Pako\*('' \(en version 0.9a, \*(``cdialog\*(''
projects / FreeBSD / FreeBSD.git / blob