2 .\" $Id: dialog.1,v 1.133 2011/06/29 09:39:29 tom Exp $
3 .\" Copyright 2005-2010,2011 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
39 .TH \*D 1 "" "$Date: 2011/06/29 09:39:29 $"
41 \*p \- display dialog boxes from shell scripts
45 .BI "\*p --create-rc " file
47 \fB\*p --print-maxsize\fP
54 is a program that will let you to present a variety of questions or
55 display messages using dialog boxes from a shell script.
56 These types of dialog boxes are implemented
57 (though not all are necessarily compiled into \fB\*p\fR):
75 .BR msgbox " (message), "
87 .BR yesno " (yes/no)."
92 You can put more than one dialog box into a script:
95 Use the "\fB--and-widget\fP" token to force \fB\*p\fP to proceed to the next
96 dialog unless you have pressed ESC to cancel, or
99 Simply add the tokens for the next dialog box, making a chain.
100 \*L stops chaining when the return code from a dialog is nonzero,
101 e.g., Cancel or No (see DIAGNOSTICS).
103 Some widgets, e.g., checklist, will write text to \fB\*p\fP's output.
104 Normally that is the standard error, but there are options for
105 changing this: "\fB--output-fd\fP", "\fB--stderr\fP" and "\fB--stdout\fP".
106 No text is written if the Cancel button (or ESC) is pressed;
107 \fB\*p\fP exits immediately in that case.
109 .\" ************************************************************************
111 All options begin with "\fB--\fP"
113 for the benefit of those using systems with deranged locale support).
115 A "\fB--\fP" by itself is used as an escape,
116 i.e., the next token on the command-line is not treated as an option.
118 .B \*p --title -- --Not an option
121 The "\fB--args\fP" option tells \fB\*p\fP to list the command-line
122 parameters to the standard error.
123 This is useful when debugging complex scripts using
124 the "\fB--\fP" and "\fB--file\fP",
125 since the command-line may be rewritten as these are expanded.
127 The "\fB--file\fP" option tells \fB\*p\fP to read parameters from
128 the file named as its value.
130 .B \*p --file \fIparameterfile
132 Blanks not within double-quotes are discarded
133 (use backslashes to quote single characters).
134 The result is inserted into the command-line,
135 replacing "\fB--file\fP" and its option value.
136 Interpretation of the command-line resumes from that point.
137 If \fIparameterfile\fP begins with "&", \fB\*p\fP
138 interprets the following text as a file descriptor number
139 rather than a filename.
141 .SS \fBCommon Options\fP
143 .IP "\fB--ascii-lines
144 Rather than draw graphics lines around boxes,
145 draw ASCII "+" and "-" in the same place.
146 See also "\fB--no-lines\fR".
148 .IP "\fB--aspect \fIratio"
149 This gives you some control over the box dimensions when using auto
150 sizing (specifying 0 for height and width).
151 It represents width / height.
152 The default is 9, which means 9 characters wide to every 1 line high.
154 .IP "\fB--backtitle \fIbacktitle"
157 string to be displayed on the backdrop, at the top of the screen.
159 .IP "\fB--begin \fIy x"
160 Specify the position of the upper left corner of a dialog box on the screen.
162 .IP "\fB--cancel-label \fIstring"
163 Override the label used for "Cancel" buttons.
166 Clears the widget screen, keeping only the screen_color background.
167 Use this when you combine widgets with "\fB--and-widget\fR" to erase the
168 contents of a previous widget on the screen, so it won't be seen
169 under the contents of a following widget.
170 Understand this as the complement of "\fB--keep-window\fR".
171 To compare the effects, use these:
174 All three widgets visible, staircase effect, ordered 1,2,3:
177 --begin 2 2 --yesno "" 0 0 \\
178 --and-widget --begin 4 4 --yesno "" 0 0 \\
179 --and-widget --begin 6 6 --yesno "" 0 0
183 Only the last widget is left visible:
186 --clear --begin 2 2 --yesno "" 0 0 \\
187 --and-widget --clear --begin 4 4 --yesno "" 0 0 \\
188 --and-widget --begin 6 6 --yesno "" 0 0
192 All three widgets visible, staircase effect, ordered 3,2,1:
195 --keep-window --begin 2 2 --yesno "" 0 0 \\
196 --and-widget --keep-window --begin 4 4 --yesno "" 0 0 \\
197 --and-widget --begin 6 6 --yesno "" 0 0
201 First and third widget visible, staircase effect, ordered 3,1:
204 --keep-window --begin 2 2 --yesno "" 0 0 \\
205 --and-widget --clear --begin 4 4 --yesno "" 0 0 \\
206 --and-widget --begin 6 6 --yesno "" 0 0
209 Note, if you want to restore original console colors and send your
210 cursor home after the dialog program has exited, use the \fBclear\fR\ (1)
214 Interpret embedded "\\Z" sequences in the dialog text
215 by the following character,
216 which tells \fB\*p\fP to set colors or video attributes:
217 0 through 7 are the ANSI used in curses:
226 Bold is set by 'b', reset by 'B'.
227 Reverse is set by 'r', reset by 'R'.
228 Underline is set by 'u', reset by 'U'.
229 The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text
230 bold (perhaps bright) red.
231 Restore normal settings with "\\Zn".
233 .IP "\fB--column-separator \fIstring"
234 Tell \fB\*p\fP to split data for radio/checkboxes and menus on the
235 occurrences of the given string, and to align the split data into columns.
238 Interpret embedded newlines in the dialog text as a newline on the screen.
239 Otherwise, \fB\*p\fR will only wrap lines where needed to fit inside the text box.
240 Even though you can control line breaks with this,
241 \fB\*L\fR will still wrap any lines that are too long for the width of the box.
242 Without cr-wrap, the layout of your text may be formatted to look nice
243 in the source code of your script without affecting the way it will
246 See also the "\fB--no-collapse\fP" and "\fB--trim\fP" options.
248 .IP "\fB--create-rc \fIfile"
251 supports run-time configuration,
252 this can be used to dump a sample configuration file to the file specified
256 .IP "\fB--date-format \fIformat"
257 If the host provides \fBstrftime\fP,
258 this option allows you to specify the format of the date printed for
259 the \fB--calendar\fP widget.
260 The time of day (hour, minute, second) are the current local time.
263 Make the default value of the
267 Likewise, make the default button of widgets that provide "OK" and "Cancel"
269 If "\fB--nocancel\fP" or "\fB--visit-items\fP" are given
270 those options overrides this,
271 making the default button always "Yes" (internally the same as "OK").
273 .IP "\fB--default-item \fIstring"
274 Set the default item in a checklist, form or menu box.
275 Normally the first item in the box is the default.
277 .IP "\fB--exit-label \fIstring"
278 Override the label used for "EXIT" buttons.
280 .IP "\fB--extra-button"
281 Show an extra button, between "OK" and "Cancel" buttons.
283 .IP "\fB--extra-label \fIstring"
284 Override the label used for "Extra" buttons.
285 Note: for inputmenu widgets, this defaults to "Rename".
288 Prints the help message to the standard output and exits.
289 The help message is also printed if no options are given,
290 or if an unrecognized option is given.
292 .IP "\fB--help-button"
293 Show a help-button after "OK" and "Cancel" buttons,
294 i.e., in checklist, radiolist and menu boxes.
295 If "\fB--item-help\fR" is also given, on exit
296 the return status will be the same as for the "OK" button,
297 and the item-help text will be written to \fB\*p\fP's output after the token "HELP".
298 Otherwise, the return status will indicate that the Help button was pressed,
299 and no message printed.
301 .IP "\fB--help-label \fIstring"
302 Override the label used for "Help" buttons.
304 .IP "\fB--help-status"
305 If the help-button is selected,
306 writes the checklist, radiolist or form information
307 after the item-help "HELP" information.
308 This can be used to reconstruct the state of a checklist after processing
311 .IP "\fB--hfile \fIfilename"
312 Display the given file using a textbox when the user presses F1.
314 .IP "\fB--hline \fIstring"
315 Display the given string centered at the bottom of the widget.
318 Ignore options that \fB\*p\fP does not recognize.
319 Some well-known ones such as "\fB--icon\fP" are ignored anyway,
320 but this is a better choice for compatibility with other implementations.
322 .IP "\fB--input-fd \fIfd"
323 Read keyboard input from the given file descriptor.
324 Most \fB\*p\fR scripts read from the standard input,
325 but the gauge widget reads a pipe (which is always standard input).
326 Some configurations do not work properly when
327 \fB\*p\fP tries to reopen the terminal.
328 Use this option (with appropriate juggling of file-descriptors)
329 if your script must work in that type of environment.
332 Makes the password widget friendlier but less secure,
333 by echoing asterisks for each character.
336 Interpret the tags data for checklist, radiolist and menu boxes
337 adding a column which is displayed in the bottom line of the
338 screen, for the currently selected item.
341 Normally \fB\*p\fP checks to see if it is running in an \fBxterm\fP,
342 and in that case tries to suppress the initialization strings that
343 would make it switch to the alternate screen.
344 Switching between the normal and alternate screens
345 is visually distracting in a script which runs \fB\*p\fP
347 Use this option to allow \fB\*p\fP to use those initialization strings.
349 .IP "\fB--keep-window"
350 Normally when \fB\*p\fR performs several \fBtailboxbg\fR widgets
351 connected by "\fB--and-widget\fR",
352 it clears the old widget from the screen by painting over it.
353 Use this option to suppress that repainting.
355 At exit, \fB\*p\fR repaints all of the widgets which have been
356 marked with "\fB--keep-window\fR", even if they are not \fBtailboxbg\fR widgets.
357 That causes them to be repainted in reverse order.
358 See the discussion of the "\fB--clear\fR" option for examples.
360 .IP "\fB--max-input \fIsize"
361 Limit input strings to the given size.
362 If not specified, the limit is 2048.
366 Suppress the "Cancel" button in checklist, inputbox and menu box modes.
367 A script can still test if the user pressed the ESC key to cancel to quit.
369 .IP "\fB--no-collapse"
370 Normally \fB\*p\fR converts tabs to spaces and reduces multiple
371 spaces to a single space for text which is displayed in a message boxes, etc.
372 Use this option to disable that feature.
373 Note that \fB\*p\fR will still wrap text,
374 subject to the "\fB--cr-wrap\fR" and "\fB--trim\fR" options.
381 box in the background,
382 printing its process id to \fB\*p\fP's output.
383 SIGHUP is disabled for the background process.
385 .IP "\fB--no-label \fIstring"
386 Override the label used for "No" buttons.
389 Rather than draw lines around boxes, draw spaces in the same place.
390 See also "\fB--ascii-lines\fR".
393 Do not enable the mouse.
395 .IP "\fB--no-nl-expand
396 Do not convert "\\n" substrings of the message/prompt text into
401 Suppress the "OK" button in checklist, inputbox and menu box modes.
402 A script can still test if the user pressed the "Enter" key to accept the data.
406 Suppress shadows that would be drawn to the right and bottom of each dialog box.
408 .IP "\fB--ok-label \fIstring"
409 Override the label used for "OK" buttons.
411 .IP "\fB--output-fd \fIfd"
412 Direct output to the given file descriptor.
413 Most \fB\*p\fR scripts write to the standard error,
414 but error messages may also be written there, depending on your script.
416 .IP "\fB--separator \fIstring"
417 .IP "\fB--output-separator\fIstring"
418 Specify a string that will separate the output on \fB\*p\fP's output from
419 checklists, rather than a newline (for --separate-output) or a space.
420 This applies to other widgets such as forms and editboxes which normally
423 .IP "\fB--print-maxsize"
424 Print the maximum size of dialog boxes, i.e., the screen size,
425 to \fB\*p\fP's output.
426 This may be used alone, without other options.
428 .IP "\fB--print-size"
429 Prints the size of each dialog box to \fB\*p\fP's output.
431 .IP "\fB--print-version"
432 Prints \fB\*p\fR's version to \fB\*p\fP's output.
433 This may be used alone, without other options.
434 It does not cause \fBdialog\fP to exit by itself.
437 For widgets holding a scrollable set of data,
438 draw a scrollbar on its right-margin.
439 This does not respond to the mouse.
441 .IP "\fB--separate-output"
442 For checklist widgets, output result one line at a time, with no quoting.
443 This facilitates parsing by another program.
445 .IP "\fB--separate-widget \fIstring"
446 Specify a string that will separate the output on \fB\*p\fP's output from
448 This is used to simplify parsing the result of a dialog with several widgets.
449 If this option is not given,
450 the default separator string is a tab character.
453 Draw a shadow to the right and bottom of each dialog box.
455 .IP "\fB--single-quoted"
456 Use single-quoting as needed (and no quotes if unneeded) for the
457 output of checklist's as well as the item-help text.
458 If this option is not set, \fB\*p\fP uses double quotes around each item.
459 That requires occasional use of backslashes to make the output useful in
463 Check the resulting size of a dialog box before trying to use it,
464 printing the resulting size if it is larger than the screen.
465 (This option is obsolete, since all new-window calls are checked).
467 .IP "\fB--sleep \fIsecs"
468 Sleep (delay) for the given number of seconds after processing a dialog box.
471 Direct output to the standard error.
472 This is the default, since curses normally writes screen updates to
476 Direct output to the standard output.
477 This option is provided for compatibility with Xdialog,
478 however using it in portable scripts is not recommended,
479 since curses normally writes its screen updates to the standard output.
480 If you use this option, \fB\*p\fR attempts to reopen the terminal
481 so it can write to the display.
482 Depending on the platform and your environment, that may fail.
484 .IP "\fB--tab-correct"
485 Convert each tab character to one or more spaces
486 (for the \fBtextbox\fP widget; otherwise to a single space).
487 Otherwise, tabs are rendered according to the curses library's interpretation.
489 .IP "\fB--tab-len \fIn"
490 Specify the number of spaces that a tab character occupies if the
491 "\fB--tab-correct\fP" option is given.
493 This option is only effective for the \fBtextbox\fP widget.
495 .IP "\fB--time-format \fIformat"
496 If the host provides \fBstrftime\fP,
497 this option allows you to specify the format of the time printed for
498 the \fB--timebox\fP widget.
499 The day, month, year values in this case are for the current local time.
501 .IP "\fB--timeout \fIsecs"
502 Timeout (exit with error code)
503 if no user response within the given number of seconds.
504 This is overridden if the background "\fB--tailboxbg\fP is used.
505 A timeout of zero seconds is ignored.
507 .IP "\fB--title \fItitle"
510 string to be displayed at the top of the dialog box.
512 .IP "\fB--trace \fIfilename"
513 logs the command-line parameters and
514 keystrokes to the given file.
515 If \fBdialog\fP reads a configure file, it is logged as well.
516 Piped input to the \fIgauge\fP widget is logged.
517 Use control/T to log a picture of the current dialog window.
520 eliminate leading blanks,
521 trim literal newlines and repeated blanks from message text.
524 See also the "\fB--cr-wrap\fR" and "\fB--no-collapse\fR" options.
527 Prints \fB\*p\fR's version to the standard output, and exits.
528 See also "\fB--print-version\fP".
530 .IP "\fB--visit-items"
531 Modify the tab-traversal of checklist, radiobox, menubox and inputmenu
532 to include the list of items as one of the states.
533 This is useful as a visual aid,
534 i.e., the cursor position helps some users.
536 When this option is given, the cursor is initially placed on the list.
537 Abbreviations (the first letter of the tag) apply to the list items.
538 If you tab to the button row, abbreviations apply to the buttons.
540 .IP "\fB--yes-label \fIstring"
541 Override the label used for "Yes" buttons.
543 .\" ************************************************************************
545 All dialog boxes have at least three parameters:
548 the caption or contents of the box.
551 the height of the dialog box.
554 the width of the dialog box.
556 Other parameters depend on the box type.
559 .IP "\fB--calendar \fItext height width day month year"
560 A \fBcalendar\fP box displays
561 month, day and year in separately adjustable windows.
562 If the values for day, month or year are missing or negative,
563 the current date's corresponding values are used.
564 You can increment or decrement any of those using the
565 left-, up-, right- and down-arrows.
566 Use vi-style h, j, k and l for moving around the array of days in a month.
567 Use tab or backtab to move between windows.
568 If the year is given as zero, the current date is used as an initial value.
570 On exit, the date is printed in the form day/month/year.
571 The format can be overridden using the \fB--date-format\fP option.
574 .IP "\fB--checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
580 multiple entries presented in the form of a menu.
581 Another difference is
582 that you can indicate which entry is currently selected, by setting its
583 .IR status " to " on "."
585 one entry among the entries, each entry can be turned on or off by the user.
586 The initial on/off state of each entry is specified by
589 On exit, a list of the \fItag\fP
590 strings of those entries that are turned on
591 will be printed on \fB\*p\fP's output.
592 If the "\fB--separate-output\fP" option is not given,
593 the strings will be quoted to make it simple for scripts to separate them.
594 See the "\fB--single-quoted\fP" option, which modifies the quoting behavior.
597 .IP "\fB--dselect \fIfilepath height width\fR"
598 The directory-selection dialog displays a text-entry window in which you can type
599 a directory, and above that a windows with directory names.
603 can be a filepath in which case the directory window
604 will display the contents of the path and the text-entry window will contain
605 the preselected directory.
607 Use tab or arrow keys to move between the windows.
608 Within the directory window, use the up/down arrow keys
609 to scroll the current selection.
610 Use the space-bar to copy the current selection into the text-entry
613 Typing any printable characters switches focus to the text-entry window,
614 entering that character as well as scrolling the directory
615 window to the closest match.
617 Use a carriage return or the "OK" button to accept the current value
618 in the text-entry window and exit.
620 On exit, the contents of the text-entry window are written to \fB\*p\fP's output.
622 .IP "\fB--editbox \fIfilepath height width\fR"
623 The edit-box dialog displays a copy of the file.
624 You may edit it using
625 the \fIbackspace\fP, \fIdelete\fP and cursor keys
626 to correct typing errors.
627 It also recognizes pageup/pagedown.
628 Unlike the \fB--inputbox\fP,
629 you must tab to the "OK" or "Cancel" buttons to close the dialog.
630 Pressing the "Enter" key within the box will split the corresponding line.
632 On exit, the contents of the edit window are written to \fB\*p\fP's output.
635 .IP "\fB--form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
637 The \fBform\fP dialog displays a form consisting of labels and fields,
638 which are positioned on a scrollable window by coordinates given in the script.
639 The field length \fIflen\fR and input-length \fIilen\fR tell how long
641 The former defines the length shown for a selected field,
642 while the latter defines the permissible length of the data entered in the
647 If \fIflen\fR is zero, the corresponding field cannot be altered.
648 and the contents of the field determine the displayed-length.
651 If \fIflen\fR is negative, the corresponding field cannot be altered,
652 and the negated value of \fIflen\fR is used as the displayed-length.
655 If \fIilen\fR is zero, it is set to \fIflen\fR.
658 Use up/down arrows (or control/N, control/P) to move between fields.
659 Use tab to move between windows.
661 On exit, the contents of the form-fields are written to \fB\*p\fP's output,
662 each field separated by a newline.
663 The text used to fill non-editable fields
664 (\fIflen\fR is zero or negative)
668 .IP "\fB--fselect \fIfilepath height width\fR"
669 The \fBfselect\fP (file-selection) dialog displays a text-entry window in which you can type
670 a filename (or directory), and above that two windows with directory
675 can be a filepath in which case the file and directory windows
676 will display the contents of the path and the text-entry window will contain
677 the preselected filename.
679 Use tab or arrow keys to move between the windows.
680 Within the directory or filename windows, use the up/down arrow keys
681 to scroll the current selection.
682 Use the space-bar to copy the current selection into the text-entry
685 Typing any printable characters switches focus to the text-entry window,
686 entering that character as well as scrolling the directory and filename
687 windows to the closest match.
689 Typing the space character forces \fB\*p\fP to complete the current
690 name (up to the point where there may be a match against more than one
693 Use a carriage return or the "OK" button to accept the current value
694 in the text-entry window and exit.
696 On exit, the contents of the text-entry window are written to \fB\*p\fP's output.
699 .IP "\fB--gauge \fItext height width [percent]\fR"
702 box displays a meter along the bottom of the box.
703 The meter indicates the percentage.
704 New percentages are read from
705 standard input, one integer per line.
707 to reflect each new percentage.
708 If the standard input reads the string "XXX",
709 then the first line following is taken as an integer percentage,
710 then subsequent lines up to another "XXX" are used for a new prompt.
711 The gauge exits when EOF is reached on the standard input.
713 The \fIpercent\fR value denotes the initial percentage shown in the meter.
714 If not specified, it is zero.
716 On exit, no text is written to \fB\*p\fP's output.
717 The widget accepts no input, so the exit status is always OK.
720 .IP "\fB--infobox \fItext height width"
721 An \fBinfo\fP box is basically a \fBmessage\fP box.
722 However, in this case, \fB\*p\fP
723 will exit immediately after displaying the message to the user.
724 The screen is not cleared when \fB\*p\fP
725 exits, so that the message will remain on the screen until the calling
726 shell script clears it later.
727 This is useful when you want to inform
728 the user that some operations are carrying on that may require some
731 On exit, no text is written to \fB\*p\fP's output.
732 Only an "OK" button is provided for input,
733 but an ESC exit status may be returned.
736 .IP "\fB--inputbox \fItext height width [init]"
739 box is useful when you want to ask questions that
740 require the user to input a string as the answer.
742 it is used to initialize the input string.
743 When entering the string,
744 the \fIbackspace\fP, \fIdelete\fP and cursor keys
745 can be used to correct typing errors.
746 If the input string is longer than
747 can fit in the dialog box, the input field will be scrolled.
749 On exit, the input string will be printed on \fB\*p\fP's output.
752 .IP "\fB--inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
753 An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box.
754 There are only a few differences between them:
758 The entries are not automatically centered but left adjusted.
761 An extra button (called \fIRename\fP) is implied to rename
762 the current item when it is pressed.
765 It is possible to rename the current entry by pressing the
768 Then \fB\*p\fP will write the following on \fB\*p\fP's output.
774 .IP "\fB--menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
775 As its name suggests, a
777 box is a dialog box that can be used to present a list of choices in
778 the form of a menu for the user to choose.
779 Choices are displayed in the order given.
780 Each menu entry consists of a \fItag\fP string and an \fIitem\fP string.
782 gives the entry a name to distinguish it from the other entries in the
784 The \fIitem\fP is a short description of the option that the entry represents.
785 The user can move between the menu entries by pressing the
786 cursor keys, the first letter of the \fItag\fP
787 as a hot-key, or the number keys
788 .IR 1-9 ". There are"
790 entries displayed in the menu at one time, but the menu will be
791 scrolled if there are more entries than that.
793 On exit the \fItag\fP
794 of the chosen menu entry will be printed on \fB\*p\fP's output.
795 If the "\fB--help-button\fR" option is given, the corresponding help
796 text will be printed if the user selects the help button.
799 .IP "\fB--mixedform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen itype \fR] \fI..."
801 The \fBmixedform\fP dialog displays a form consisting of labels and fields,
802 much like the \fB--form\fP dialog.
803 It differs by adding a field-type parameter to each field's description.
804 Each bit in the type denotes an attribute of the field:
808 hidden, e.g., a password field.
811 readonly, e.g., a label.
814 .IP "\fB--mixedgauge \fItext height width percent \fR[ \fItag1 item1 \fR] \fI..."
817 box displays a meter along the bottom of the box.
818 The meter indicates the percentage.
820 It also displays a list of the \fItag\fP- and \fIitem\fP-values at the
822 See \*l(3) for the tag values.
824 The \fItext\fP is shown as a caption between the list and meter.
825 The \fIpercent\fR value denotes the initial percentage shown in the meter.
827 No provision is made for reading data from the standard input as \fB--gauge\fP
830 On exit, no text is written to \fB\*p\fP's output.
831 The widget accepts no input, so the exit status is always OK.
833 .IP "\fB--msgbox \fItext height width"
834 A \fBmessage\fP box is very similar to a \fByes/no\fP box.
835 The only difference between a \fBmessage\fP box and a \fByes/no\fP
836 box is that a \fBmessage\fP box has only a single \fBOK\fP button.
837 You can use this dialog box to display any message you like.
838 After reading the message, the user can press the \fIENTER\fP key so that
839 \fB\*p\fP will exit and the calling shell script can continue its operation.
841 If the message is too large for the space,
842 \fB\*p\fP may allow you to scroll it,
843 provided that the underlying curses implementation is capable enough.
844 In this case, a percentage is shown in the base of the widget.
846 On exit, no text is written to \fB\*p\fP's output.
847 Only an "OK" button is provided for input,
848 but an ESC exit status may be returned.
850 .IP "\fB\-\-pause \fItext height width seconds\fR"
853 box displays a meter along the bottom of the box.
854 The meter indicates how many seconds remain until the end of the pause.
855 The pause exits when timeout is reached
856 or the user presses the OK button
858 or the user presses the CANCEL button
860 .IP "\fB--passwordbox \fItext height width [init]"
861 A \fBpassword\fP box is similar to an input box,
862 except that the text the user enters is not displayed.
863 This is useful when prompting for passwords or other
864 sensitive information.
865 Be aware that if anything is passed in "init", it
866 will be visible in the system's process table to casual snoopers.
868 is very confusing to the user to provide them with a default password they
870 For these reasons, using "init" is highly discouraged.
871 See "\fB--insecure\fP" if you do not care about your password.
873 On exit, the input string will be printed on \fB\*p\fP's output.
877 .IP "\fB--passwordform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
879 This is identical to \fB--form\fP except that all text fields are
880 treated as \fBpassword\fP widgets rather than \fBinputbox\fP widgets.
883 .IP "\fB--prgbox \fItext command height width"
884 .IP "\fB--prgbox \fIcommand height width"
885 A \fBprgbox\fP is very similar to a \fBprogrambox\fP.
887 This dialog box is used to display the output of a command that is
888 specified as an argument to \fBprgbox\fP.
890 After the command completes, the user can press the \fIENTER\fP key so that
891 \fBdialog\fP will exit and the calling shell script can continue its operation.
893 If three parameters are given, it displays the text under the title,
894 delineated from the scrolling file's contents.
895 If only two parameters are given, this text is omitted.
898 .IP "\fB--programbox \fItext height width"
899 .IP "\fB--programbox \fIheight width"
900 A \fBprogrambox\fP is very similar to a \fBprogressbox\fP.
901 The only difference between a \fBprogram\fP box and a \fBprogress\fP
902 box is that a \fBprogram\fP box displays an \fBOK\fP button.
904 This dialog box is used to display the piped output of a command.
905 After the command completes, the user can press the \fIENTER\fP key so that
906 \fBdialog\fP will exit and the calling shell script can continue its operation.
908 If three parameters are given, it displays the text under the title,
909 delineated from the scrolling file's contents.
910 If only two parameters are given, this text is omitted.
913 .IP "\fB--progressbox \fItext height width"
914 .IP "\fB--progressbox \fIheight width"
915 A \fBprogressbox\fP is similar to an \fBtailbox\fP,
916 except that it will exit when it reaches the end of the file.
917 If three parameters are given, it displays the text under the title,
918 delineated from the scrolling file's contents.
919 If only two parameters are given, this text is omitted.
922 .IP "\fB--radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
928 The only difference is
929 that you can indicate which entry is currently selected, by setting its
930 .IR status " to " on "."
932 On exit, the name of the selected item is written to \fB\*p\fP's output.
935 .IP "\fB--tailbox \fIfile height width"
936 Display text from a file in a dialog box, as in a "tail -f" command.
937 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
938 A '0' resets the scrolling.
940 On exit, no text is written to \fB\*p\fP's output.
941 Only an "OK" button is provided for input,
942 but an ESC exit status may be returned.
945 .IP "\fB--tailboxbg \fIfile height width"
946 Display text from a file in a dialog box as a background task,
947 as in a "tail -f &" command.
948 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
949 A '0' resets the scrolling.
951 \*L treats the background task specially if there are other
952 widgets (\fB--and-widget\fP) on the screen concurrently.
953 Until those widgets are closed (e.g., an "OK"),
954 \fB\*p\fP will perform all of the tailboxbg widgets in the same process,
956 You may use a tab to traverse between the widgets on the screen,
957 and close them individually, e.g., by pressing \fIENTER\fP.
958 Once the non-tailboxbg widgets are closed, \fB\*p\fP forks a copy of itself
959 into the background, and prints its process id if the "\fB--no-kill\fP" option
962 On exit, no text is written to \fB\*p\fP's output.
963 Only an "EXIT" button is provided for input,
964 but an ESC exit status may be returned.
967 Older versions of \fB\*p\fP forked immediately and attempted to
968 update the screen individually.
969 Besides being bad for performance,
971 Some older scripts may not work properly with the polled scheme.
974 .IP "\fB--textbox \fIfile height width"
977 box lets you display the contents of a text file in a dialog box.
978 It is like a simple text file viewer.
979 The user can move through the file by using the
980 cursor, page-up, page-down
981 and \fIHOME/END\fR keys available on most keyboards.
982 If the lines are too long to be displayed in the box,
984 keys can be used to scroll the text region horizontally.
985 You may also use vi-style keys h, j, k, l in place of the cursor keys,
986 and B or N in place of the page-up and page-down keys.
987 Scroll up/down using vi-style 'k' and 'j', or arrow-keys.
988 Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
989 A '0' resets the left/right scrolling.
990 For more convenience,
991 vi-style forward and backward searching functions are also provided.
993 On exit, no text is written to \fB\*p\fP's output.
994 Only an "EXIT" button is provided for input,
995 but an ESC exit status may be returned.
998 .IP "\fB--timebox \fItext height [width hour minute second]"
999 A dialog is displayed which allows you to select hour, minute and second.
1000 If the values for hour, minute or second are missing or negative,
1001 the current date's corresponding values are used.
1002 You can increment or decrement any of those using the
1003 left-, up-, right- and down-arrows.
1004 Use tab or backtab to move between windows.
1006 On exit, the result is printed in the form hour:minute:second.
1007 The format can be overridden using the \fB--time-format\fP option.
1010 .IP "\fB--yesno \fItext height width"
1011 A \fByes/no\fP dialog box of
1012 size \fIheight\fP rows by \fIwidth\fP columns will be displayed.
1013 The string specified by
1015 is displayed inside the dialog box.
1016 If this string is too long to fit
1017 in one line, it will be automatically divided into multiple lines at
1021 string can also contain the sub-string
1024 or newline characters
1026 to control line breaking explicitly.
1027 This dialog box is useful for
1028 asking questions that require the user to answer either yes or no.
1029 The dialog box has a
1033 button, in which the user can switch between by pressing the
1036 On exit, no text is written to \fB\*p\fP's output.
1037 In addition to the "Yes" and "No" exit codes (see DIAGNOSTICS)
1038 an ESC exit status may be returned.
1040 The codes used for "Yes" and "No" match those used for "OK" and "Cancel",
1041 internally no distinction is made.
1043 .\" ************************************************************************
1044 .SS "Obsolete Options"
1045 .\" from cdialog 0.9a (Pako)
1047 This was used to tell the original cdialog that it should make a beep
1048 when the separate processes of the tailboxbg widget would repaint the screen.
1050 .\" from cdialog 0.9a (Pako)
1051 .IP "\fB--beep-after"
1052 Beep after a user has completed a widget by pressing one of the buttons.
1054 .\" ************************************************************************
1055 .SH "RUN-TIME CONFIGURATION"
1058 Create a sample configuration file by typing:
1061 "\*p --create-rc <file>"
1066 determines the settings to use as follows:
1070 if environment variable
1072 is set, its value determines the name of the configuration file.
1075 if the file in (a) is not found, use the file
1076 \fI$HOME/.dialogrc\fP
1077 as the configuration file.
1080 if the file in (b) is not found, try using the GLOBALRC file determined at
1081 compile-time, i.e., \fI/etc/dialogrc\fP.
1084 if the file in (c) is not found, use compiled in defaults.
1088 Edit the sample configuration file and copy it to some place that
1090 can find, as stated in step 2 above.
1092 .\" ************************************************************************
1094 You can override or add to key bindings in \fB\*p\fP
1095 by adding to the configuration file.
1096 \fB\*L\fP's \fBbindkey\fP command maps single keys to its internal coding.
1098 bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP
1100 The \fIwidget\fP name can be "*" (all widgets), or
1101 specific widgets such as \fBtextbox\fP.
1102 Specific widget bindings override the "*" bindings.
1103 User-defined bindings override the built-in bindings.
1105 The \fIcurses_key\fP can be any of the names derived from
1106 \fBcurses.h\fP, e.g., "HELP" from "KEY_HELP".
1107 \fB\*L\fP also recognizes ANSI control characters such as "^A", "^?",
1108 as well as C1-controls such as "~A" and "~?".
1109 Finally, it allows any single character to be escaped with a backslash.
1111 \fB\*L\fP's internal keycode names correspond to the
1112 \fBDLG_KEYS_ENUM\fP type in
1113 \fBdlg_keys.h\fP, e.g., "HELP" from "DLGK_HELP".
1115 .\" ************************************************************************
1119 Define this variable to apply any of the common options to each widget.
1120 Most of the common options are reset before processing each widget.
1121 If you set the options in this environment variable,
1122 they are applied to \fB\*p\fP's state after the reset.
1123 As in the "\fB--file\fP" option,
1124 double-quotes and backslashes are interpreted.
1126 The "\fB--file\fP" option is not considered a common option
1127 (so you cannot embed it within this environment variable).
1130 Define this variable if you want to specify the name of the configuration file
1143 \fBDIALOG_ITEM_HELP\fP
1146 Define any of these variables to change the exit code on
1152 Help with --item-help (2),
1154 Normally shell scripts cannot distinguish between -1 and 255.
1157 Set this variable to "1" to provide compatibility with older versions
1158 of \fB\*p\fP which assumed that if the script redirects the standard output,
1159 that the "\fB--stdout\fP" option was given.
1162 \fI$HOME/.dialogrc\fP
1163 default configuration file
1165 The \fB\*p\fP sources contain several samples
1166 of how to use the different box options and how they look.
1167 Just take a look into the directory \fBsamples/\fP of the source.
1169 Exit status is subject to being overridden by environment variables.
1174 .BR \*p " is exited by pressing the " Yes " or " OK
1179 .BR No " or " Cancel
1197 if errors occur inside \fB\*p\fP
1198 or \fB\*p\fP is exited by pressing the \fIESC\fP key.
1200 .\" ************************************************************************
1202 \fB\*L\fP works with X/Open curses.
1203 However, some implementations have deficiencies:
1207 HPUX curses (and perhaps others) do not open the terminal properly for
1208 the \fInewterm\fP function.
1209 This interferes with \fB\*p\fP's \fB--input-fd\fP option,
1210 by preventing cursor-keys and similar escape sequences from being recognized.
1213 NetBSD 5.1 curses has incomplete support for wide-characters.
1214 \fB\*p\fP will build, but not all examples display properly.
1216 .\" ************************************************************************
1218 You may want to write scripts which run with other \fBdialog\fP "clones".
1220 First, there is the "original" \fBdialog\fP program to consider (versions
1222 It had some misspelled (or inconsistent) options.
1223 The \fB\*p\fP program maps those deprecated options to the preferred ones.
1230 \fIOption\fR \fITreatment\fR
1231 \fB--beep-after\fP ignored
1232 \fB--guage\fP mapped to \fB--gauge\fP
1236 Technically, "\fBXdialog\fP",
1237 this is an X application.
1238 With some care, it is possible to write useful scripts that work
1239 with both \fBXdialog\fP and \fBdialog\fP.
1241 The \fB\*p\fP program ignores these options which are recognized
1248 \fIOption\fR \fITreatment\fR
1249 \fB--allow-close\fP ignored
1250 \fB--auto-placement\fP ignored
1251 \fB--fixed-font\fP ignored
1252 \fB--icon\fP ignored
1253 \fB--keep-colors\fP ignored
1254 \fB--no-close\fP ignored
1255 \fB--no-cr-wrap\fP ignored
1256 \fB--screen-center\fP ignored
1257 \fB--separator\fP mapped to \fB--separate-output\fP
1258 \fB--smooth\fP ignored
1259 \fB--under-mouse\fP ignored
1260 \fB--wmclass\fP ignored
1264 \fBXdialog\fP's manpage has a section discussing its compatibility with \fB\*p\fP.
1266 Then there is \fBwhiptail\fP.
1267 For practical purposes, it is maintained by Debian.
1268 Its documentation claims
1272 whiptail(1) is a lightweight replacement for \*p(1),
1273 to provide dialog boxes for shell scripts. It is built on the
1274 newt windowing library rather than the ncurses library, allowing
1275 it to be smaller in embedded enviroments such as installers,
1278 whiptail is designed to be drop-in compatible with \*p, but
1279 has less features: some dialog boxes are not implemented, such
1280 as tailbox, timebox, calendarbox, etc.
1284 Comparing actual sizes (Debian testing, 2007/1/10):
1285 The total of sizes for \fBwhiptail\fP, the newt, popt and slang libraries is 757kb.
1286 The comparable number for \fB\*p\fP (counting ncurses) is 520kb.
1287 Disregard the first paragraph.
1289 The second paragraph is misleading, since \fBwhiptail\fP
1290 also does not work for common options of \*p, such as the gauge box.
1291 \fBwhiptail\fP is less compatible with \fB\*p\fP than the decade-old
1292 original dialog 0.4 program.
1294 \fBwhiptail\fP's manpage borrows features from \fB\*p\fP, e.g.,
1295 \fB--default-item\fP (2000),
1296 \fB--output-fd\fP (2002),
1297 but oddly cites only \fB\*p\fP versions up to 0.4 (1996) as a source.
1298 That is, its manpage refers to features which
1299 were borrowed from more recent versions of \fB\*p\fP, e.g.,
1300 the \fB--gauge\fP and \fB--password\fP boxes,
1301 as well as options such as \fB-separate-output\fP (2008).
1302 Somewhat humorously, one may note that the \fBpopt\fP feature
1303 (undocumented in its manpage)
1304 of using a "--" as an escape was documented in \fB\*p\fP's manpage about
1305 a year before it was mentioned in \fBwhiptail\fP's manpage.
1306 \fBwhiptail\fP's manpage incorrectly attributes that to \fBgetopt\fP
1307 (and is inaccurate anyway).
1309 Debian uses \fBwhiptail\fP for the official \fB\*p\fP variation.
1311 The \fB\*p\fP program ignores or maps these options which are recognized
1318 \fIOption\fR \fITreatment\fR
1320 \fB--fullbutton\fP ignored
1321 \fB--nocancel\fP mapped to \fB--no-cancel\fP
1322 \fB--noitem\fP ignored
1325 .\" ************************************************************************
1330 Thomas E. Dickey (updates for 0.9b and beyond)
1332 Kiran Cherupally - the mixed form and mixed gauge widgets.
1334 Tobias C. Rittweiler
1336 Valery Reznic - the form and progressbox widgets.
1338 Yura Kalinichenko adapted the gauge widget as "pause".
1340 This is a rewrite (except as needed to provide compatibility)
1341 of the earlier version of \fB\*p 0.9a\fP,
1342 which lists as authors:
1345 Savio Lam - version 0.3, "dialog"
1347 Stuart Herbert - patch for version 0.4
1349 Marc Ewing - the gauge widget.
1351 Pasquale De Marco "Pako" - version 0.9a, "cdialog"