2 .\" $Id: dialog.1,v 1.145 2012/07/03 08:32:33 tom Exp $
3 .\" Copyright 2005-2011,2012 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
40 .TH \*D 1 "" "$Date: 2012/07/03 08:32:33 $"
42 \*p \- display dialog boxes from shell scripts
46 .BI "\*p --create-rc " file
48 \fB\*p --print-maxsize\fP
55 is a program that will let you to present a variety of questions or
56 display messages using dialog boxes from a shell script.
57 These types of dialog boxes are implemented
58 (though not all are necessarily compiled into \fB\*p\fR):
76 .BR msgbox " (message), "
88 .BR yesno " (yes/no)."
93 You can put more than one dialog box into a script:
96 Use the "\fB--and-widget\fP" token to force \fB\*p\fP to proceed to the next
97 dialog unless you have pressed ESC to cancel, or
100 Simply add the tokens for the next dialog box, making a chain.
101 \*L stops chaining when the return code from a dialog is nonzero,
102 e.g., Cancel or No (see DIAGNOSTICS).
104 Some widgets, e.g., checklist, will write text to \fB\*p\fP's output.
105 Normally that is the standard error, but there are options for
106 changing this: "\fB--output-fd\fP", "\fB--stderr\fP" and "\fB--stdout\fP".
107 No text is written if the Cancel button (or ESC) is pressed;
108 \fB\*p\fP exits immediately in that case.
110 .\" ************************************************************************
112 All options begin with "\fB--\fP"
114 for the benefit of those using systems with deranged locale support).
116 A "\fB--\fP" by itself is used as an escape,
117 i.e., the next token on the command-line is not treated as an option.
119 .B \*p --title -- --Not an option
122 The "\fB--args\fP" option tells \fB\*p\fP to list the command-line
123 parameters to the standard error.
124 This is useful when debugging complex scripts using
125 the "\fB--\fP" and "\fB--file\fP",
126 since the command-line may be rewritten as these are expanded.
128 The "\fB--file\fP" option tells \fB\*p\fP to read parameters from
129 the file named as its value.
131 .B \*p --file \fIparameterfile
133 Blanks not within double-quotes are discarded
134 (use backslashes to quote single characters).
135 The result is inserted into the command-line,
136 replacing "\fB--file\fP" and its option value.
137 Interpretation of the command-line resumes from that point.
138 If \fIparameterfile\fP begins with "&", \fB\*p\fP
139 interprets the following text as a file descriptor number
140 rather than a filename.
142 .SS \fBCommon Options\fP
144 .IP "\fB--ascii-lines
145 Rather than draw graphics lines around boxes,
146 draw ASCII "+" and "-" in the same place.
147 See also "\fB--no-lines\fR".
149 .IP "\fB--aspect \fIratio"
150 This gives you some control over the box dimensions when using auto
151 sizing (specifying 0 for height and width).
152 It represents width / height.
153 The default is 9, which means 9 characters wide to every 1 line high.
155 .IP "\fB--backtitle \fIbacktitle"
158 string to be displayed on the backdrop, at the top of the screen.
160 .IP "\fB--begin \fIy x"
161 Specify the position of the upper left corner of a dialog box on the screen.
163 .IP "\fB--cancel-label \fIstring"
164 Override the label used for "Cancel" buttons.
167 Clears the widget screen, keeping only the screen_color background.
168 Use this when you combine widgets with "\fB--and-widget\fR" to erase the
169 contents of a previous widget on the screen, so it won't be seen
170 under the contents of a following widget.
171 Understand this as the complement of "\fB--keep-window\fR".
172 To compare the effects, use these:
175 All three widgets visible, staircase effect, ordered 1,2,3:
178 --begin 2 2 --yesno "" 0 0 \\
179 --and-widget --begin 4 4 --yesno "" 0 0 \\
180 --and-widget --begin 6 6 --yesno "" 0 0
184 Only the last widget is left visible:
187 --clear --begin 2 2 --yesno "" 0 0 \\
188 --and-widget --clear --begin 4 4 --yesno "" 0 0 \\
189 --and-widget --begin 6 6 --yesno "" 0 0
193 All three widgets visible, staircase effect, ordered 3,2,1:
196 --keep-window --begin 2 2 --yesno "" 0 0 \\
197 --and-widget --keep-window --begin 4 4 --yesno "" 0 0 \\
198 --and-widget --begin 6 6 --yesno "" 0 0
202 First and third widget visible, staircase effect, ordered 3,1:
205 --keep-window --begin 2 2 --yesno "" 0 0 \\
206 --and-widget --clear --begin 4 4 --yesno "" 0 0 \\
207 --and-widget --begin 6 6 --yesno "" 0 0
210 Note, if you want to restore original console colors and send your
211 cursor home after the dialog program has exited, use the \fBclear\fR\ (1)
215 Interpret embedded "\\Z" sequences in the dialog text
216 by the following character,
217 which tells \fB\*p\fP to set colors or video attributes:
218 0 through 7 are the ANSI used in curses:
227 Bold is set by 'b', reset by 'B'.
228 Reverse is set by 'r', reset by 'R'.
229 Underline is set by 'u', reset by 'U'.
230 The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text
231 bold (perhaps bright) red.
232 Restore normal settings with "\\Zn".
234 .IP "\fB--column-separator \fIstring"
235 Tell \fB\*p\fP to split data for radio/checkboxes and menus on the
236 occurrences of the given string, and to align the split data into columns.
239 Interpret embedded newlines in the dialog text as a newline on the screen.
240 Otherwise, \fB\*p\fR will only wrap lines where needed to fit inside the text box.
242 Even though you can control line breaks with this,
243 \fB\*L\fR will still wrap any lines that are too long for the width of the box.
244 Without cr-wrap, the layout of your text may be formatted to look nice
245 in the source code of your script without affecting the way it will
248 See also the "\fB--no-collapse\fP" and "\fB--trim\fP" options.
250 .IP "\fB--create-rc \fIfile"
253 supports run-time configuration,
254 this can be used to dump a sample configuration file to the file specified
258 .IP "\fB--date-format \fIformat"
259 If the host provides \fBstrftime\fP,
260 this option allows you to specify the format of the date printed for
261 the \fB--calendar\fP widget.
262 The time of day (hour, minute, second) are the current local time.
265 Make the default value of the
269 Likewise, make the default button of widgets that provide "OK" and "Cancel"
271 If "\fB--nocancel\fP" or "\fB--visit-items\fP" are given
272 those options overrides this,
273 making the default button always "Yes" (internally the same as "OK").
275 .IP "\fB--default-button \fIstring"
276 Set the default (preselected) button in a widget.
277 By preselecting a button,
278 a script makes it possible for the user to simply press \fIEnter\fP
279 to proceed through a dialog with minimum interaction.
281 The option's value is the name of the button:
289 Normally the first button in each widget is the default.
290 The first button shown is determined by the widget
291 together with the "\fB--nook\fP" and "\fB--nocancel\fP options.
292 If this option is not given, there is no default button assigned.
294 .IP "\fB--default-item \fIstring"
295 Set the default item in a checklist, form or menu box.
296 Normally the first item in the box is the default.
298 .IP "\fB--exit-label \fIstring"
299 Override the label used for "EXIT" buttons.
301 .IP "\fB--extra-button"
302 Show an extra button, between "OK" and "Cancel" buttons.
304 .IP "\fB--extra-label \fIstring"
305 Override the label used for "Extra" buttons.
306 Note: for inputmenu widgets, this defaults to "Rename".
309 Prints the help message to the standard output and exits.
310 The help message is also printed if no options are given,
311 or if an unrecognized option is given.
313 .IP "\fB--help-button"
314 Show a help-button after "OK" and "Cancel" buttons,
315 i.e., in checklist, radiolist and menu boxes.
316 If "\fB--item-help\fR" is also given, on exit
317 the return status will be the same as for the "OK" button,
318 and the item-help text will be written to \fB\*p\fP's output after the token "HELP".
319 Otherwise, the return status will indicate that the Help button was pressed,
320 and no message printed.
322 .IP "\fB--help-label \fIstring"
323 Override the label used for "Help" buttons.
325 .IP "\fB--help-status"
326 If the help-button is selected,
327 writes the checklist, radiolist or form information
328 after the item-help "HELP" information.
329 This can be used to reconstruct the state of a checklist after processing
332 .IP "\fB--hfile \fIfilename"
333 Display the given file using a textbox when the user presses F1.
335 .IP "\fB--hline \fIstring"
336 Display the given string centered at the bottom of the widget.
339 Ignore options that \fB\*p\fP does not recognize.
340 Some well-known ones such as "\fB--icon\fP" are ignored anyway,
341 but this is a better choice for compatibility with other implementations.
343 .IP "\fB--input-fd \fIfd"
344 Read keyboard input from the given file descriptor.
345 Most \fB\*p\fR scripts read from the standard input,
346 but the gauge widget reads a pipe (which is always standard input).
347 Some configurations do not work properly when
348 \fB\*p\fP tries to reopen the terminal.
349 Use this option (with appropriate juggling of file-descriptors)
350 if your script must work in that type of environment.
353 Makes the password widget friendlier but less secure,
354 by echoing asterisks for each character.
357 Interpret the tags data for checklist, radiolist and menu boxes
358 adding a column which is displayed in the bottom line of the
359 screen, for the currently selected item.
362 When built with \fBncurses\fP,
363 \fB\*p\fP normally checks to see if it is running in an \fBxterm\fP,
364 and in that case tries to suppress the initialization strings that
365 would make it switch to the alternate screen.
366 Switching between the normal and alternate screens
367 is visually distracting in a script which runs \fB\*p\fP
369 Use this option to allow \fB\*p\fP to use those initialization strings.
371 .IP "\fB--keep-window"
372 Normally when \fB\*p\fR performs several \fBtailboxbg\fR widgets
373 connected by "\fB--and-widget\fR",
374 it clears the old widget from the screen by painting over it.
375 Use this option to suppress that repainting.
377 At exit, \fB\*p\fR repaints all of the widgets which have been
378 marked with "\fB--keep-window\fR", even if they are not \fBtailboxbg\fR widgets.
379 That causes them to be repainted in reverse order.
380 See the discussion of the "\fB--clear\fR" option for examples.
382 .IP "\fB--max-input \fIsize"
383 Limit input strings to the given size.
384 If not specified, the limit is 2048.
388 Suppress the "Cancel" button in checklist, inputbox and menu box modes.
389 A script can still test if the user pressed the ESC key to cancel to quit.
391 .IP "\fB--no-collapse"
392 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
393 spaces to a single space for text which is displayed in a message boxes, etc.
394 Use this option to disable that feature.
395 Note that \fB\*p\fR will still wrap text,
396 subject to the "\fB--cr-wrap\fR" and "\fB--trim\fR" options.
403 box in the background,
404 printing its process id to \fB\*p\fP's output.
405 SIGHUP is disabled for the background process.
407 .IP "\fB--no-label \fIstring"
408 Override the label used for "No" buttons.
411 Rather than draw lines around boxes, draw spaces in the same place.
412 See also "\fB--ascii-lines\fR".
415 Do not enable the mouse.
417 .IP "\fB--no-nl-expand
418 Do not convert "\\n" substrings of the message/prompt text into
423 Suppress the "OK" button in checklist, inputbox and menu box modes.
424 A script can still test if the user pressed the "Enter" key to accept the data.
428 Suppress shadows that would be drawn to the right and bottom of each dialog box.
430 .IP "\fB--ok-label \fIstring"
431 Override the label used for "OK" buttons.
433 .IP "\fB--output-fd \fIfd"
434 Direct output to the given file descriptor.
435 Most \fB\*p\fR scripts write to the standard error,
436 but error messages may also be written there, depending on your script.
438 .IP "\fB--separator \fIstring"
439 .IP "\fB--output-separator\fIstring"
440 Specify a string that will separate the output on \fB\*p\fP's output from
441 checklists, rather than a newline (for --separate-output) or a space.
442 This applies to other widgets such as forms and editboxes which normally
445 .IP "\fB--print-maxsize"
446 Print the maximum size of dialog boxes, i.e., the screen size,
447 to \fB\*p\fP's output.
448 This may be used alone, without other options.
450 .IP "\fB--print-size"
451 Prints the size of each dialog box to \fB\*p\fP's output.
453 .IP "\fB--print-version"
454 Prints \fB\*p\fR's version to \fB\*p\fP's output.
455 This may be used alone, without other options.
456 It does not cause \fBdialog\fP to exit by itself.
459 Normally \fB\*p\fP quotes the strings returned by checklist's
460 as well as the item-help text.
461 Use this option to quote all string results.
464 For widgets holding a scrollable set of data,
465 draw a scrollbar on its right-margin.
466 This does not respond to the mouse.
468 .IP "\fB--separate-output"
469 For checklist widgets, output result one line at a time, with no quoting.
470 This facilitates parsing by another program.
472 .IP "\fB--separate-widget \fIstring"
473 Specify a string that will separate the output on \fB\*p\fP's output from
475 This is used to simplify parsing the result of a dialog with several widgets.
476 If this option is not given,
477 the default separator string is a tab character.
480 Draw a shadow to the right and bottom of each dialog box.
482 .IP "\fB--single-quoted"
483 Use single-quoting as needed (and no quotes if unneeded) for the
484 output of checklist's as well as the item-help text.
485 If this option is not set, \fB\*p\fP uses double quotes around each item.
487 \fB\*p\fP adds backslashes to make the output useful in shell scripts.
490 Check the resulting size of a dialog box before trying to use it,
491 printing the resulting size if it is larger than the screen.
492 (This option is obsolete, since all new-window calls are checked).
494 .IP "\fB--sleep \fIsecs"
495 Sleep (delay) for the given number of seconds after processing a dialog box.
498 Direct output to the standard error.
499 This is the default, since curses normally writes screen updates to
503 Direct output to the standard output.
504 This option is provided for compatibility with Xdialog,
505 however using it in portable scripts is not recommended,
506 since curses normally writes its screen updates to the standard output.
507 If you use this option, \fB\*p\fR attempts to reopen the terminal
508 so it can write to the display.
509 Depending on the platform and your environment, that may fail.
511 .IP "\fB--tab-correct"
512 Convert each tab character to one or more spaces
513 (for the \fBtextbox\fP widget; otherwise to a single space).
514 Otherwise, tabs are rendered according to the curses library's interpretation.
516 .IP "\fB--tab-len \fIn"
517 Specify the number of spaces that a tab character occupies if the
518 "\fB--tab-correct\fP" option is given.
520 This option is only effective for the \fBtextbox\fP widget.
522 .IP "\fB--time-format \fIformat"
523 If the host provides \fBstrftime\fP,
524 this option allows you to specify the format of the time printed for
525 the \fB--timebox\fP widget.
526 The day, month, year values in this case are for the current local time.
528 .IP "\fB--timeout \fIsecs"
529 Timeout (exit with error code)
530 if no user response within the given number of seconds.
531 A timeout of zero seconds is ignored.
533 This option is ignored by the "\fB--pause\fP" widget.
534 It is also overridden if the background "\fB--tailboxbg\fP" option is used
535 to setup multiple concurrent widgets.
537 .IP "\fB--title \fItitle"
540 string to be displayed at the top of the dialog box.
542 .IP "\fB--trace \fIfilename"
543 logs the command-line parameters,
544 keystrokes and other information to the given file.
545 If \fBdialog\fP reads a configure file, it is logged as well.
546 Piped input to the \fIgauge\fP widget is logged.
547 Use control/T to log a picture of the current dialog window.
549 The \fB\*p\fR program handles some command-line parameters specially,
550 and removes them from the parameter list as they are processed.
551 For example, if the first option is \fB--trace\fP,
552 then that is processed (and removed) before \fB\*p\fR initializes the display.
555 eliminate leading blanks,
556 trim literal newlines and repeated blanks from message text.
559 See also the "\fB--cr-wrap\fR" and "\fB--no-collapse\fR" options.
562 Prints \fB\*p\fR's version to the standard output, and exits.
563 See also "\fB--print-version\fP".
565 .IP "\fB--visit-items"
566 Modify the tab-traversal of checklist, radiobox, menubox and inputmenu
567 to include the list of items as one of the states.
568 This is useful as a visual aid,
569 i.e., the cursor position helps some users.
571 When this option is given, the cursor is initially placed on the list.
572 Abbreviations (the first letter of the tag) apply to the list items.
573 If you tab to the button row, abbreviations apply to the buttons.
575 .IP "\fB--yes-label \fIstring"
576 Override the label used for "Yes" buttons.
578 .\" ************************************************************************
580 All dialog boxes have at least three parameters:
583 the caption or contents of the box.
586 the height of the dialog box.
589 the width of the dialog box.
591 Other parameters depend on the box type.
594 .IP "\fB--calendar \fItext height width day month year"
595 A \fBcalendar\fP box displays
596 month, day and year in separately adjustable windows.
597 If the values for day, month or year are missing or negative,
598 the current date's corresponding values are used.
599 You can increment or decrement any of those using the
600 left-, up-, right- and down-arrows.
601 Use vi-style h, j, k and l for moving around the array of days in a month.
602 Use tab or backtab to move between windows.
603 If the year is given as zero, the current date is used as an initial value.
605 On exit, the date is printed in the form day/month/year.
606 The format can be overridden using the \fB--date-format\fP option.
609 .IP "\fB--checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
615 multiple entries presented in the form of a menu.
616 Another difference is
617 that you can indicate which entry is currently selected, by setting its
618 .IR status " to " on "."
620 one entry among the entries, each entry can be turned on or off by the user.
621 The initial on/off state of each entry is specified by
624 On exit, a list of the \fItag\fP
625 strings of those entries that are turned on
626 will be printed on \fB\*p\fP's output.
628 If the "\fB--separate-output\fP" option is not given,
629 the strings will be quoted as needed to make it simple for scripts to separate them.
630 By default, this uses double-quotes.
631 See the "\fB--single-quoted\fP" option, which modifies the quoting behavior.
634 .IP "\fB--dselect \fIfilepath height width\fR"
635 The directory-selection dialog displays a text-entry window in which you can type
636 a directory, and above that a windows with directory names.
640 can be a filepath in which case the directory window
641 will display the contents of the path and the text-entry window will contain
642 the preselected directory.
644 Use tab or arrow keys to move between the windows.
645 Within the directory window, use the up/down arrow keys
646 to scroll the current selection.
647 Use the space-bar to copy the current selection into the text-entry
650 Typing any printable characters switches focus to the text-entry window,
651 entering that character as well as scrolling the directory
652 window to the closest match.
654 Use a carriage return or the "OK" button to accept the current value
655 in the text-entry window and exit.
657 On exit, the contents of the text-entry window are written to \fB\*p\fP's output.
659 .IP "\fB--editbox \fIfilepath height width\fR"
660 The edit-box dialog displays a copy of the file.
661 You may edit it using
662 the \fIbackspace\fP, \fIdelete\fP and cursor keys
663 to correct typing errors.
664 It also recognizes pageup/pagedown.
665 Unlike the \fB--inputbox\fP,
666 you must tab to the "OK" or "Cancel" buttons to close the dialog.
667 Pressing the "Enter" key within the box will split the corresponding line.
669 On exit, the contents of the edit window are written to \fB\*p\fP's output.
672 .IP "\fB--form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
674 The \fBform\fP dialog displays a form consisting of labels and fields,
675 which are positioned on a scrollable window by coordinates given in the script.
676 The field length \fIflen\fR and input-length \fIilen\fR tell how long
678 The former defines the length shown for a selected field,
679 while the latter defines the permissible length of the data entered in the
684 If \fIflen\fR is zero, the corresponding field cannot be altered.
685 and the contents of the field determine the displayed-length.
688 If \fIflen\fR is negative, the corresponding field cannot be altered,
689 and the negated value of \fIflen\fR is used as the displayed-length.
692 If \fIilen\fR is zero, it is set to \fIflen\fR.
695 Use up/down arrows (or control/N, control/P) to move between fields.
696 Use tab to move between windows.
698 On exit, the contents of the form-fields are written to \fB\*p\fP's output,
699 each field separated by a newline.
700 The text used to fill non-editable fields
701 (\fIflen\fR is zero or negative)
705 .IP "\fB--fselect \fIfilepath height width\fR"
706 The \fBfselect\fP (file-selection) dialog displays a text-entry window in which you can type
707 a filename (or directory), and above that two windows with directory
712 can be a filepath in which case the file and directory windows
713 will display the contents of the path and the text-entry window will contain
714 the preselected filename.
716 Use tab or arrow keys to move between the windows.
717 Within the directory or filename windows, use the up/down arrow keys
718 to scroll the current selection.
719 Use the space-bar to copy the current selection into the text-entry
722 Typing any printable characters switches focus to the text-entry window,
723 entering that character as well as scrolling the directory and filename
724 windows to the closest match.
726 Typing the space character forces \fB\*p\fP to complete the current
727 name (up to the point where there may be a match against more than one
730 Use a carriage return or the "OK" button to accept the current value
731 in the text-entry window and exit.
733 On exit, the contents of the text-entry window are written to \fB\*p\fP's output.
736 .IP "\fB--gauge \fItext height width [percent]\fR"
739 box displays a meter along the bottom of the box.
740 The meter indicates the percentage.
741 New percentages are read from
742 standard input, one integer per line.
744 to reflect each new percentage.
745 If the standard input reads the string "XXX",
746 then the first line following is taken as an integer percentage,
747 then subsequent lines up to another "XXX" are used for a new prompt.
748 The gauge exits when EOF is reached on the standard input.
750 The \fIpercent\fR value denotes the initial percentage shown in the meter.
751 If not specified, it is zero.
753 On exit, no text is written to \fB\*p\fP's output.
754 The widget accepts no input, so the exit status is always OK.
757 .IP "\fB--infobox \fItext height width"
758 An \fBinfo\fP box is basically a \fBmessage\fP box.
759 However, in this case, \fB\*p\fP
760 will exit immediately after displaying the message to the user.
761 The screen is not cleared when \fB\*p\fP
762 exits, so that the message will remain on the screen until the calling
763 shell script clears it later.
764 This is useful when you want to inform
765 the user that some operations are carrying on that may require some
768 On exit, no text is written to \fB\*p\fP's output.
769 Only an "OK" button is provided for input,
770 but an ESC exit status may be returned.
773 .IP "\fB--inputbox \fItext height width [init]"
776 box is useful when you want to ask questions that
777 require the user to input a string as the answer.
779 it is used to initialize the input string.
780 When entering the string,
781 the \fIbackspace\fP, \fIdelete\fP and cursor keys
782 can be used to correct typing errors.
783 If the input string is longer than
784 can fit in the dialog box, the input field will be scrolled.
786 On exit, the input string will be printed on \fB\*p\fP's output.
789 .IP "\fB--inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
790 An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box.
791 There are only a few differences between them:
795 The entries are not automatically centered but left adjusted.
798 An extra button (called \fIRename\fP) is implied to rename
799 the current item when it is pressed.
802 It is possible to rename the current entry by pressing the
805 Then \fB\*p\fP will write the following on \fB\*p\fP's output.
811 .IP "\fB--menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
812 As its name suggests, a
814 box is a dialog box that can be used to present a list of choices in
815 the form of a menu for the user to choose.
816 Choices are displayed in the order given.
817 Each menu entry consists of a \fItag\fP string and an \fIitem\fP string.
819 gives the entry a name to distinguish it from the other entries in the
821 The \fIitem\fP is a short description of the option that the entry represents.
822 The user can move between the menu entries by pressing the
823 cursor keys, the first letter of the \fItag\fP
824 as a hot-key, or the number keys
825 .IR 1-9 ". There are"
827 entries displayed in the menu at one time, but the menu will be
828 scrolled if there are more entries than that.
830 On exit the \fItag\fP
831 of the chosen menu entry will be printed on \fB\*p\fP's output.
832 If the "\fB--help-button\fR" option is given, the corresponding help
833 text will be printed if the user selects the help button.
836 .IP "\fB--mixedform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen itype \fR] \fI..."
838 The \fBmixedform\fP dialog displays a form consisting of labels and fields,
839 much like the \fB--form\fP dialog.
840 It differs by adding a field-type parameter to each field's description.
841 Each bit in the type denotes an attribute of the field:
845 hidden, e.g., a password field.
848 readonly, e.g., a label.
851 .IP "\fB--mixedgauge \fItext height width percent \fR[ \fItag1 item1 \fR] \fI..."
854 box displays a meter along the bottom of the box.
855 The meter indicates the percentage.
857 It also displays a list of the \fItag\fP- and \fIitem\fP-values at the
859 See \*l(3) for the tag values.
861 The \fItext\fP is shown as a caption between the list and meter.
862 The \fIpercent\fR value denotes the initial percentage shown in the meter.
864 No provision is made for reading data from the standard input as \fB--gauge\fP
867 On exit, no text is written to \fB\*p\fP's output.
868 The widget accepts no input, so the exit status is always OK.
870 .IP "\fB--msgbox \fItext height width"
871 A \fBmessage\fP box is very similar to a \fByes/no\fP box.
872 The only difference between a \fBmessage\fP box and a \fByes/no\fP
873 box is that a \fBmessage\fP box has only a single \fBOK\fP button.
874 You can use this dialog box to display any message you like.
875 After reading the message, the user can press the \fIENTER\fP key so that
876 \fB\*p\fP will exit and the calling shell script can continue its operation.
878 If the message is too large for the space,
879 \fB\*p\fP may allow you to scroll it,
880 provided that the underlying curses implementation is capable enough.
881 In this case, a percentage is shown in the base of the widget.
883 On exit, no text is written to \fB\*p\fP's output.
884 Only an "OK" button is provided for input,
885 but an ESC exit status may be returned.
887 .IP "\fB--pause \fItext height width seconds\fR"
890 box displays a meter along the bottom of the box.
891 The meter indicates how many seconds remain until the end of the pause.
892 The pause exits when timeout is reached
893 or the user presses the OK button
895 or the user presses the CANCEL button
897 .IP "\fB--passwordbox \fItext height width [init]"
898 A \fBpassword\fP box is similar to an input box,
899 except that the text the user enters is not displayed.
900 This is useful when prompting for passwords or other
901 sensitive information.
902 Be aware that if anything is passed in "init", it
903 will be visible in the system's process table to casual snoopers.
905 is very confusing to the user to provide them with a default password they
907 For these reasons, using "init" is highly discouraged.
908 See "\fB--insecure\fP" if you do not care about your password.
910 On exit, the input string will be printed on \fB\*p\fP's output.
914 .IP "\fB--passwordform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
916 This is identical to \fB--form\fP except that all text fields are
917 treated as \fBpassword\fP widgets rather than \fBinputbox\fP widgets.
920 .IP "\fB--prgbox \fItext command height width"
921 .IP "\fB--prgbox \fIcommand height width"
922 A \fBprgbox\fP is very similar to a \fBprogrambox\fP.
924 This dialog box is used to display the output of a command that is
925 specified as an argument to \fBprgbox\fP.
927 After the command completes, the user can press the \fIENTER\fP key so that
928 \fBdialog\fP will exit and the calling shell script can continue its operation.
930 If three parameters are given, it displays the text under the title,
931 delineated from the scrolling file's contents.
932 If only two parameters are given, this text is omitted.
935 .IP "\fB--programbox \fItext height width"
936 .IP "\fB--programbox \fIheight width"
937 A \fBprogrambox\fP is very similar to a \fBprogressbox\fP.
938 The only difference between a \fBprogram\fP box and a \fBprogress\fP
939 box is that a \fBprogram\fP box displays an \fBOK\fP button
940 (but only after the command completes).
942 This dialog box is used to display the piped output of a command.
943 After the command completes, the user can press the \fIENTER\fP key so that
944 \fBdialog\fP will exit and the calling shell script can continue its operation.
946 If three parameters are given, it displays the text under the title,
947 delineated from the scrolling file's contents.
948 If only two parameters are given, this text is omitted.
951 .IP "\fB--progressbox \fItext height width"
952 .IP "\fB--progressbox \fIheight width"
953 A \fBprogressbox\fP is similar to an \fBtailbox\fP,
957 a) rather than displaying the contents of a file,
958 it displays the piped output of a command and
960 b) it will exit when it reaches the end of the file
961 (there is no "OK" button).
964 If three parameters are given, it displays the text under the title,
965 delineated from the scrolling file's contents.
966 If only two parameters are given, this text is omitted.
969 .IP "\fB--radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
975 The only difference is
976 that you can indicate which entry is currently selected, by setting its
977 .IR status " to " on "."
979 On exit, the name of the selected item is written to \fB\*p\fP's output.
982 .IP "\fB--tailbox \fIfile height width"
983 Display text from a file in a dialog box, as in a "tail -f" command.
984 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
985 A '0' resets the scrolling.
987 On exit, no text is written to \fB\*p\fP's output.
988 Only an "OK" button is provided for input,
989 but an ESC exit status may be returned.
992 .IP "\fB--tailboxbg \fIfile height width"
993 Display text from a file in a dialog box as a background task,
994 as in a "tail -f &" command.
995 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
996 A '0' resets the scrolling.
998 \*L treats the background task specially if there are other
999 widgets (\fB--and-widget\fP) on the screen concurrently.
1000 Until those widgets are closed (e.g., an "OK"),
1001 \fB\*p\fP will perform all of the tailboxbg widgets in the same process,
1002 polling for updates.
1003 You may use a tab to traverse between the widgets on the screen,
1004 and close them individually, e.g., by pressing \fIENTER\fP.
1005 Once the non-tailboxbg widgets are closed, \fB\*p\fP forks a copy of itself
1006 into the background, and prints its process id if the "\fB--no-kill\fP" option
1009 On exit, no text is written to \fB\*p\fP's output.
1010 Only an "EXIT" button is provided for input,
1011 but an ESC exit status may be returned.
1014 Older versions of \fB\*p\fP forked immediately and attempted to
1015 update the screen individually.
1016 Besides being bad for performance,
1018 Some older scripts may not work properly with the polled scheme.
1021 .IP "\fB--textbox \fIfile height width"
1024 box lets you display the contents of a text file in a dialog box.
1025 It is like a simple text file viewer.
1026 The user can move through the file by using the
1027 cursor, page-up, page-down
1028 and \fIHOME/END\fR keys available on most keyboards.
1029 If the lines are too long to be displayed in the box,
1030 the \fILEFT/RIGHT\fP
1031 keys can be used to scroll the text region horizontally.
1032 You may also use vi-style keys h, j, k, l in place of the cursor keys,
1033 and B or N in place of the page-up and page-down keys.
1034 Scroll up/down using vi-style 'k' and 'j', or arrow-keys.
1035 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
1036 A '0' resets the left/right scrolling.
1037 For more convenience,
1038 vi-style forward and backward searching functions are also provided.
1040 On exit, no text is written to \fB\*p\fP's output.
1041 Only an "EXIT" button is provided for input,
1042 but an ESC exit status may be returned.
1045 .IP "\fB--timebox \fItext height [width hour minute second]"
1046 A dialog is displayed which allows you to select hour, minute and second.
1047 If the values for hour, minute or second are missing or negative,
1048 the current date's corresponding values are used.
1049 You can increment or decrement any of those using the
1050 left-, up-, right- and down-arrows.
1051 Use tab or backtab to move between windows.
1053 On exit, the result is printed in the form hour:minute:second.
1054 The format can be overridden using the \fB--time-format\fP option.
1057 .IP "\fB--yesno \fItext height width"
1058 A \fByes/no\fP dialog box of
1059 size \fIheight\fP rows by \fIwidth\fP columns will be displayed.
1060 The string specified by
1062 is displayed inside the dialog box.
1063 If this string is too long to fit
1064 in one line, it will be automatically divided into multiple lines at
1068 string can also contain the sub-string
1071 or newline characters
1073 to control line breaking explicitly.
1074 This dialog box is useful for
1075 asking questions that require the user to answer either yes or no.
1076 The dialog box has a
1080 button, in which the user can switch between by pressing the
1083 On exit, no text is written to \fB\*p\fP's output.
1084 In addition to the "Yes" and "No" exit codes (see DIAGNOSTICS)
1085 an ESC exit status may be returned.
1087 The codes used for "Yes" and "No" match those used for "OK" and "Cancel",
1088 internally no distinction is made.
1090 .\" ************************************************************************
1091 .SS "Obsolete Options"
1092 .\" from cdialog 0.9a (Pako)
1094 This was used to tell the original cdialog that it should make a beep
1095 when the separate processes of the tailboxbg widget would repaint the screen.
1097 .\" from cdialog 0.9a (Pako)
1098 .IP "\fB--beep-after"
1099 Beep after a user has completed a widget by pressing one of the buttons.
1101 .\" ************************************************************************
1102 .SH "RUN-TIME CONFIGURATION"
1105 Create a sample configuration file by typing:
1108 "\*p --create-rc <file>"
1113 determines the settings to use as follows:
1117 if environment variable
1119 is set, its value determines the name of the configuration file.
1122 if the file in (a) is not found, use the file
1123 \fI$HOME/.dialogrc\fP
1124 as the configuration file.
1127 if the file in (b) is not found, try using the GLOBALRC file determined at
1128 compile-time, i.e., \fI/etc/dialogrc\fP.
1131 if the file in (c) is not found, use compiled in defaults.
1135 Edit the sample configuration file and copy it to some place that
1137 can find, as stated in step 2 above.
1139 .\" ************************************************************************
1141 You can override or add to key bindings in \fB\*p\fP
1142 by adding to the configuration file.
1143 \fB\*L\fP's \fBbindkey\fP command maps single keys to its internal coding.
1145 bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP
1148 The \fIwidget\fP name can be "*" (all widgets), or
1149 specific widgets such as \fBtextbox\fP.
1150 Specific widget bindings override the "*" bindings.
1151 User-defined bindings override the built-in bindings.
1153 The \fIcurses_key\fP can be any of the names derived from
1154 \fBcurses.h\fP, e.g., "HELP" from "KEY_HELP".
1155 \fB\*L\fP also recognizes ANSI control characters such as "^A", "^?",
1156 as well as C1-controls such as "~A" and "~?".
1157 Finally, it allows any single character to be escaped with a backslash.
1159 \fB\*L\fP's internal keycode names correspond to the
1160 \fBDLG_KEYS_ENUM\fP type in
1161 \fBdlg_keys.h\fP, e.g., "HELP" from "DLGK_HELP".
1164 Some widgets (such as the formbox) have an area where fields can be edited.
1165 Those are managed in a subwindow of the widget, and
1166 may have separate keybindings from the main widget
1167 because the subwindows are registered using a different name.
1172 \fIWidget\fR/\fIWindow name\fR/\fISubwindow Name\fR
1175 editbox/editbox/editbox2
1176 form/formbox/formfield
1177 fselect/fselect/fselect2
1178 inputbox/inputbox/inputbox2
1182 progressbox/progressbox
1185 textbox/textbox/searchbox
1190 Some widgets are actually other widgets,
1191 using internal settings to modify the behavior.
1192 Those use the same widget name as the actual widget:
1197 \fIWidget\fR/\fIActual Widget\fR
1202 passwordbox/inputbox
1205 programbox/progressbox
1208 .SS Built-in Bindings
1209 This manual page does not list the key bindings for each widget,
1210 because that detailed information can be obtained by running \fB\*p\fP.
1211 If you have set the \fB--trace\fP option,
1212 \fB\*p\fP writes the key-binding information for each widget
1213 as it is registered.
1215 Normally \fB\*p\fP uses different keys for navigating between the buttons
1216 and editing part of a dialog versus navigating within the editing part.
1217 That is, tab (and back-tab) traverse buttons
1218 (or between buttons and the editing part),
1219 while arrow keys traverse fields within the editing part.
1220 Tabs are also recognized as a special case for traversing between
1221 widgets, e.g., when using multiple tailboxbg widgets.
1223 Some users may wish to use the same key for traversing within the
1224 editing part as for traversing between buttons.
1225 The form widget is written to support this sort of redefinition of
1226 the keys, by adding a special group in <code>dlgk_keys.h</code>
1227 for "form" (left/right/next/prev).
1228 Here is an example binding demonstrating how to do this:
1230 bindkey formfield TAB form_NEXT
1231 bindkey formbox TAB form_NEXT
1232 bindkey formfield BTAB form_prev
1233 bindkey formbox BTAB form_prev
1236 That type of redefinition would not be useful in other widgets,
1237 e.g., calendar, due to the potentially large number of fields to traverse.
1239 .\" ************************************************************************
1243 Define this variable to apply any of the common options to each widget.
1244 Most of the common options are reset before processing each widget.
1245 If you set the options in this environment variable,
1246 they are applied to \fB\*p\fP's state after the reset.
1247 As in the "\fB--file\fP" option,
1248 double-quotes and backslashes are interpreted.
1250 The "\fB--file\fP" option is not considered a common option
1251 (so you cannot embed it within this environment variable).
1254 Define this variable if you want to specify the name of the configuration file
1267 \fBDIALOG_ITEM_HELP\fP
1270 Define any of these variables to change the exit code on
1276 Help with \fB--item-help\fP (2),
1278 Normally shell scripts cannot distinguish between -1 and 255.
1281 Set this variable to "1" to provide compatibility with older versions
1282 of \fB\*p\fP which assumed that if the script redirects the standard output,
1283 that the "\fB--stdout\fP" option was given.
1286 \fI$HOME/.dialogrc\fP
1287 default configuration file
1289 The \fB\*p\fP sources contain several samples
1290 of how to use the different box options and how they look.
1291 Just take a look into the directory \fBsamples/\fP of the source.
1293 Exit status is subject to being overridden by environment variables.
1294 The default values and corresponding environment variables
1295 that can override them are:
1299 .BR \*p " is exited by pressing the " Yes " or " OK
1304 .BR No " or " Cancel
1305 button is pressed (DIALOG_CANCEL).
1310 button is pressed (DIALOG_HELP).
1315 button is pressed (DIALOG_EXTRA).
1320 button is pressed (DIALOG_HELP),
1321 or the \fB--item-help\fP option is set
1322 when the \fBHelp\fP button is pressed (DIALOG_ITEM_HELP),
1325 if errors occur inside \fB\*p\fP (DIALOG_ERROR)
1326 or \fB\*p\fP is exited by pressing the \fIESC\fP key (DIALOG_ESC).
1328 .\" ************************************************************************
1330 \fB\*L\fP works with X/Open curses.
1331 However, some implementations have deficiencies:
1335 HPUX curses (and perhaps others) do not open the terminal properly for
1336 the \fInewterm\fP function.
1337 This interferes with \fB\*p\fP's \fB--input-fd\fP option,
1338 by preventing cursor-keys and similar escape sequences from being recognized.
1341 NetBSD 5.1 curses has incomplete support for wide-characters.
1342 \fB\*p\fP will build, but not all examples display properly.
1344 .\" ************************************************************************
1346 You may want to write scripts which run with other \fBdialog\fP "clones".
1348 First, there is the "original" \fBdialog\fP program to consider (versions
1350 It had some misspelled (or inconsistent) options.
1351 The \fB\*p\fP program maps those deprecated options to the preferred ones.
1358 \fIOption\fR \fITreatment\fR
1359 \fB--beep-after\fP ignored
1360 \fB--guage\fP mapped to \fB--gauge\fP
1364 Technically, "\fBXdialog\fP",
1365 this is an X application.
1366 With some care, it is possible to write useful scripts that work
1367 with both \fBXdialog\fP and \fBdialog\fP.
1369 The \fB\*p\fP program ignores these options which are recognized
1376 \fIOption\fR \fITreatment\fR
1377 \fB--allow-close\fP ignored
1378 \fB--auto-placement\fP ignored
1379 \fB--fixed-font\fP ignored
1380 \fB--icon\fP ignored
1381 \fB--keep-colors\fP ignored
1382 \fB--no-close\fP ignored
1383 \fB--no-cr-wrap\fP ignored
1384 \fB--screen-center\fP ignored
1385 \fB--separator\fP mapped to \fB--separate-output\fP
1386 \fB--smooth\fP ignored
1387 \fB--under-mouse\fP ignored
1388 \fB--wmclass\fP ignored
1392 \fBXdialog\fP's manpage has a section discussing its compatibility with \fB\*p\fP.
1394 Then there is \fBwhiptail\fP.
1395 For practical purposes, it is maintained by Debian.
1396 Its documentation claims
1400 whiptail(1) is a lightweight replacement for \*p(1),
1401 to provide dialog boxes for shell scripts.
1403 newt windowing library rather than the ncurses library, allowing
1404 it to be smaller in embedded enviroments such as installers,
1407 whiptail is designed to be drop-in compatible with \*p, but
1408 has less features: some dialog boxes are not implemented, such
1409 as tailbox, timebox, calendarbox, etc.
1413 Comparing actual sizes (Debian testing, 2007/1/10):
1414 The total of sizes for \fBwhiptail\fP, the newt, popt and slang libraries is 757kb.
1415 The comparable number for \fB\*p\fP (counting ncurses) is 520kb.
1416 Disregard the first paragraph.
1418 The second paragraph is misleading, since \fBwhiptail\fP
1419 also does not work for common options of \*p, such as the gauge box.
1420 \fBwhiptail\fP is less compatible with \fB\*p\fP than the decade-old
1421 original dialog 0.4 program.
1423 \fBwhiptail\fP's manpage borrows features from \fB\*p\fP, e.g.,
1424 \fB--default-item\fP (2000),
1425 \fB--output-fd\fP (2002),
1426 but oddly cites only \fB\*p\fP versions up to 0.4 (1996) as a source.
1427 That is, its manpage refers to features which
1428 were borrowed from more recent versions of \fB\*p\fP, e.g.,
1429 the \fB--gauge\fP and \fB--password\fP boxes,
1430 as well as options such as \fB--separate-output\fP (2008).
1431 Somewhat humorously, one may note that the \fBpopt\fP feature
1432 (undocumented in its manpage)
1433 of using a "--" as an escape was documented in \fB\*p\fP's manpage about
1434 a year before it was mentioned in \fBwhiptail\fP's manpage.
1435 \fBwhiptail\fP's manpage incorrectly attributes that to \fBgetopt\fP
1436 (and is inaccurate anyway).
1438 Debian uses \fBwhiptail\fP for the official \fB\*p\fP variation.
1440 The \fB\*p\fP program ignores or maps these options which are recognized
1447 \fIOption\fR \fITreatment\fR
1449 \fB--fullbutton\fP ignored
1450 \fB--nocancel\fP mapped to \fB--no-cancel\fP
1451 \fB--noitem\fP ignored
1454 .\" ************************************************************************
1459 Thomas E. Dickey (updates for 0.9b and beyond)
1461 Kiran Cherupally - the mixed form and mixed gauge widgets.
1463 Tobias C. Rittweiler
1465 Valery Reznic - the form and progressbox widgets.
1467 Yura Kalinichenko adapted the gauge widget as "pause".
1469 This is a rewrite (except as needed to provide compatibility)
1470 of the earlier version of \fB\*p 0.9a\fP,
1471 which lists as authors:
1474 Savio Lam - version 0.3, "dialog"
1476 Stuart Herbert - patch for version 0.4
1478 Marc Ewing - the gauge widget.
1480 Pasquale De Marco "Pako" - version 0.9a, "cdialog"
projects / FreeBSD / FreeBSD.git / blob