diff options
Diffstat (limited to 'upstream/fedora-40/man1/dialog.1')
| -rw-r--r-- | upstream/fedora-40/man1/dialog.1 | 2083 |
1 files changed, 2083 insertions, 0 deletions
diff --git a/upstream/fedora-40/man1/dialog.1 b/upstream/fedora-40/man1/dialog.1 new file mode 100644 index 00000000..62aea4ac --- /dev/null +++ b/upstream/fedora-40/man1/dialog.1 @@ -0,0 +1,2083 @@ +'\" t +.\" $Id: dialog.1,v 1.236 2024/01/01 11:24:25 tom Exp $ +.\" Copyright 2005-2023,2024 Thomas E. Dickey +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU Lesser General Public License, version 2.1 +.\" as published by the Free Software Foundation. +.\" +.\" This program is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" Lesser General Public License for more details. +.\" +.\" You should have received a copy of the GNU Lesser General Public +.\" License along with this program; if not, write to +.\" Free Software Foundation, Inc. +.\" 51 Franklin St., Fifth Floor +.\" Boston, MA 02110, USA. +.\" +.\" definitions for renaming +.ds p dialog +.ds l dialog +.ds L Dialog +.ds D DIALOG +.\" +.ie n .ds CW R +.el \{ +.ie \n(.g .ds CW CR +.el .ds CW CW +.\} +. +.de ES +.ne 8 +.IP +.. +.de Ex +.RS +7 +.PP +.nf +.ft \*(CW +.. +.de Ee +.fi +.ft R +.RE +.. +.\" Bulleted paragraph +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.ds ' \(aq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.ie t .ds ' \(aq +.el .ds ' ' +.\}", +. +.TH \*D "" 2024-01-01 "" "User commands" +.SH NAME +dialog \- +display dialog boxes from shell scripts +.SH SYNOPSIS +\fB\*p \-\-clear\fP +.br +.BI "\*p \-\-create\-rc " file +.br +\fB\*p \-\-print\-maxsize\fP +.br +\fB\*p\fP +\fIcommon-options\fP +\fIbox-options\fP +.SH DESCRIPTION +\fB\*L\fP +is a program that will let you present a variety of questions or +display messages using dialog boxes from a shell script. +These types of dialog boxes are implemented +(though not all are necessarily compiled into \fB\*p\fR): +.RS +.LP +.nh +.na +.BR buildlist ", " +.BR calendar ", " +.BR checklist ", " +.BR dselect ", " +.BR editbox ", " +.BR form ", " +.BR fselect ", " +.BR gauge ", " +.BR infobox ", " +.BR inputbox ", " +.BR inputmenu ", " +.BR menu ", " +.BR mixedform ", " +.BR mixedgauge ", " +.BR msgbox " (message), " +.BR passwordbox ", " +.BR passwordform ", " +.BR pause ", " +.BR prgbox ", " +.BR programbox ", " +.BR progressbox ", " +.BR radiolist ", " +.BR rangebox ", " +.BR tailbox ", " +.BR tailboxbg ", " +.BR textbox ", " +.BR timebox ", " +.BR treeview ", and " +.BR yesno " (yes/no)." +.ad +.RE +.PP +You can put more than one dialog box into a script: +.bP +Use the "\fB\-\-and\-widget\fP" token to force \fB\*p\fP to proceed to the next +dialog unless you have pressed ESC to cancel, or +.bP +Simply add the tokens for the next dialog box, making a chain. +\*L stops chaining when the return code from a dialog is nonzero, +e.g., Cancel or No (see DIAGNOSTICS). +.PP +Some widgets, e.g., checklist, will write text to \fB\*p\fP's output. +Normally that is the standard error, but there are options for +changing this: +\*(``\fB\-\-output\-fd\fP\*('', +\*(``\fB\-\-stderr\fP\*('' and +\*(``\fB\-\-stdout\fP\*(''. +No text is written if the Cancel button (or ESC) is pressed; +\fB\*p\fP exits immediately in that case. +. +.\" ************************************************************************ +.SH OPTIONS +All options begin with \*(``\fB\-\-\fP\*('' +(two ASCII hyphens, +for the benefit of those using systems with deranged locale support). +.PP +A \*(``\fB\-\-\fP\*('' by itself is used as an escape, +i.e., the next token on the command-line is not treated as an option. +This is different from \fBgetopt\fP(1), +which uses that token to treat the remaining tokens as \fIparameters\fP +rather than \fIoptions\fP. +.RS +.PP +.B \*p \-\-title \-\- \-\-Not an option +.br +.B \*p \-\-title This \-\- \-\-title is not an option +.RE +.PP +\fB\*L\fP +uses no \fIparameters\fP, +and uses its own \fIoptions\fP parser. +.PP +When a common (e.g., non-widget) option is repeated, +the last found is the one that is used. +Boolean options are handled specially so they can be cancelled, +by adding (or omitting) a \*(``no\*('' modifier +after the leading \*(``\fB\-\-\fP\*(''. +For instance, \fB\-\-no\-shadow\fP is documented here, +but \fB\-\-shadow\fP also is accepted. +.PP +The \*(``\fB\-\-args\fP\*('' option tells \fB\*p\fP to list the command-line +parameters to the standard error. +This is useful when debugging complex scripts using +the \*(``\fB\-\-\fP\*('' and \*(``\fB\-\-file\fP\*('', +since the command-line may be rewritten as these are expanded. +.PP +The \*(``\fB\-\-file\fP\*('' option tells \fB\*p\fP to read parameters from +the file named as its value. +.RS +.B \*p \-\-file \fIparameterfile +.RE +.PP +Blanks not within double-quotes are discarded +(use backslashes to quote single characters). +The result is inserted into the command-line, +replacing \*(``\fB\-\-file\fP\*('' and its option value. +Interpretation of the command-line resumes from that point. +If \fIparameterfile\fP begins with \*(``&\*('', \fB\*p\fP +interprets the following text as a file descriptor number +rather than a filename. +.PP +Most widgets accept \fIheight\fP and \fIwidth\fP parameters, +which can be used to automatically size the widget to accommodate +multi-line message \fIprompt\fP values: +.bP +If the parameter is negative, +\fB\*l\fP uses the screen's size. +.bP +If the parameter is zero, +\fB\*l\fP uses minimum size for the widget to display the \fIprompt\fP +and data. +.bP +Otherwise, \fB\*l\fP uses the given size for the widget. +. +.SS \fBCommon Options\fP +Most of the common options are reset before processing each widget. +. +.IP "\fB\-\-ascii\-lines" +Rather than draw graphics lines around boxes, +draw ASCII \*(``+\*('' and \*(``-\*('' in the same place. +See also \*(``\fB\-\-no\-lines\fR\*(''. +. +.IP "\fB\-\-aspect \fIratio" +This gives you some control over the box dimensions when using auto +sizing (specifying 0 for height and width). +It represents width / height. +The default is 9, which means 9 characters wide to every 1 line high. +. +.IP "\fB\-\-backtitle \fIbacktitle" +Specifies a +\fIbacktitle\fP +string to be displayed on the backdrop, at the top of the screen. +. +.IP "\fB\-\-begin \fIy x" +Specify the position of the upper left corner of a dialog box on the screen. +. +.IP "\fB\-\-cancel\-label \fIstring" +Override the label used for \*(``Cancel\*('' buttons. +. +.IP "\fB\-\-clear" +Clears the widget screen, keeping only the screen_color background. +Use this when you combine widgets +with \*(``\fB\-\-and\-widget\fR\*('' to erase the +contents of a previous widget on the screen, so it won't be seen +under the contents of a following widget. +Understand this as the complement of \*(``\fB\-\-keep\-window\fR\*(''. +To compare the effects, use these: +. +.ES +All three widgets visible, staircase effect, ordered 1,2,3: +.Ex +\*p \e + \-\-begin 2 2 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 4 4 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0 +.Ee +. +.ES +Only the last widget is left visible: +.Ex +\*p \e + \-\-clear \-\-begin 2 2 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-clear \-\-begin 4 4 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0 +.Ee +. +.ES +All three widgets visible, staircase effect, ordered 3,2,1: +.Ex +\*p \e + \-\-keep\-window \-\-begin 2 2 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-keep\-window \-\-begin 4 4 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0 +.Ee +. +.ES +First and third widget visible, staircase effect, ordered 3,1: +.Ex +\*p \e + \-\-keep\-window \-\-begin 2 2 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-clear \-\-begin 4 4 \-\-yesno "" 0 0 \e + \-\-and\-widget \-\-begin 6 6 \-\-yesno "" 0 0 +.Ee +.IP +Note, if you want to restore original console colors and send your +cursor home after the dialog program has exited, use the \fBclear\fR(1) +command. +Conversely, if you want to clear the screen and send your cursor to +the lower left after the \fB\*p\fP program has exited, use the +\fB\-\-erase\-on\-exit\fR\ option. +. +.IP "\fB\-\-colors" +Interpret embedded \*(``\eZ\*('' sequences in the dialog text +by the following character, +which tells \fB\*p\fP to set colors or video attributes: +.RS +.bP +0 through 7 are the ANSI color numbers used in curses: +black, +red, +green, +yellow, +blue, +magenta, +cyan and +white respectively. +.bP +Bold is set by 'b', reset by 'B'. +.bP +Reverse is set by 'r', reset by 'R'. +.bP +Underline is set by 'u', reset by 'U'. +.bP +The settings are cumulative, e.g., \*(``\eZb\eZ1\*('' makes the following text +bold (perhaps bright) red. +.bP +Restore normal settings with \*(``\eZn\*(''. +.RE +. +.IP "\fB\-\-column\-separator \fIstring" +Tell \fB\*p\fP to split data for radio/checkboxes and menus on the +occurrences of the given string, and to align the split data into columns. +. +.IP "\fB\-\-cr\-wrap" +Interpret embedded newlines in the dialog text as a newline on the screen. +Otherwise, \fB\*p\fR will only wrap lines +where needed to fit inside the text box. +.IP +Even though you can control line breaks with this, +\fB\*L\fR will still wrap any lines that are too long for the width of the box. +Without cr-wrap, the layout of your text may be formatted to look nice +in the source code of your script without affecting the way it will +look in the dialog. +.IP +The \fIcr\-wrap\fP feature is implemented subject to these conditions: +.RS +.bP +the string contains \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option is +not used, or +.bP +the \fB\-\-trim\fP option is used. +.RE +.IP +For more information, see \fBWhitespace Options\fP. +. +.IP "\fB\-\-create\-rc \fIfile" +When +\fB\*p\fP +supports run-time configuration, +this can be used to dump a sample configuration file to the file specified +by +.IR file "." +. +.IP "\fB\-\-cursor\-off\-label" +Place the terminal cursor at the end of a button instead of on the +first character of the button label. +This is useful to reduce visual confusion when the cursor coloration +interacts poorly with the button-label text colors. +. +.IP "\fB\-\-date\-format \fIformat" +If the host provides \fBstrftime\fP, +this option allows you to specify the format of the date printed for +the \fB\-\-calendar\fP widget. +The time of day (hour, minute, second) are the current local time. +. +.IP "\fB\-\-defaultno" +Make the default value of the +\fByes/no\fP +box a +.BR No . +Likewise, treat the default button of widgets that provide +\*(``OK\*('' and \*(``Cancel\*('' +as a \fICancel\fP. +If \*(``\fB\-\-no\-cancel\fP\*('' or \*(``\fB\-\-visit\-items\fP\*('' are given +those options overrides this, +making the default button always \*(``Yes\*('' +(internally the same as \*(``OK\*(''). +. +.IP "\fB\-\-default\-button \fIstring" +Set the default (preselected) button in a widget. +By preselecting a button, +a script makes it possible for the user to simply press \fIEnter\fP +to proceed through a dialog with minimum interaction. +.IP +The option's value is the name of the button: +.IR ok , +.IR yes , +.IR cancel , +.IR no , +.IR help "\ or" +.IR extra . +.IP +Normally the first button in each widget is the default. +The first button shown is determined by the widget +together with the \*(``\fB\-\-no\-ok\fP\*('' +and \*(``\fB\-\-no\-cancel\fP\*('' options. +If this option is not given, there is no default button assigned. +. +.IP "\fB\-\-default\-item \fIstring" +Set the default item in a checklist, form or menu box. +Normally the first item in the box is the default. +. +.IP "\fB\-\-erase\-on\-exit" +When \fB\*p\fP exits, remove the dialog widget, erasing the entire +screen to its native background color, and place the terminal cursor +at the lower left corner. +. +.IP "\fB\-\-exit\-label \fIstring" +Override the label used for \*(``EXIT\*('' buttons. +. +.IP "\fB\-\-extra\-button" +Show an extra button, between \*(``OK\*('' and \*(``Cancel\*('' buttons. +.IP +The extra button appears between \*(``Yes\*('' and \*(``No\*('' +for the \fIyesno\fP widget. +. +.IP "\fB\-\-extra\-label \fIstring" +Override the label used for \*(``Extra\*('' buttons. +Note: for inputmenu widgets, this defaults to \*(``Rename\*(''. +. +.IP "\fB\-\-help" +Prints the help message to the standard output and exits. +The help message is also printed if no options are given, +or if an unrecognized option is given. +. +.IP "\fB\-\-help\-button" +Show a help-button after \*(``OK\*('' and \*(``Cancel\*('' buttons +in boxes which have a list of tagged items +(i.e., checklist, radiolist, menu, and treeview boxes). +.IP +The help-button appears after \*(``Yes\*('' and \*(``No\*('' +for the \fIyesno\fP widget. +.IP +On exit, the return status indicates that the Help button was pressed. +\fB\*L\fP also writes a message to its output +after the token \*(``HELP\*('': +.RS +.bP +If "\fB\-\-item\-help\fR" is also given, the item-help text is written. +.bP +Otherwise, the item's tag (the first field) is written. +.RE +.IP +You can use the \fB\-\-help\-tags\fP option and/or set the DIALOG_ITEM_HELP +environment variable to modify these messages and exit-status. +.IP +This option can be applied to other widgets, +which have an \*(``OK\*('' button, +whether or not the \*(``Cancel\*('' button is used. +The return status and output are not treated specially for the other widgets; +the help-button is just an extra button. +. +.IP "\fB\-\-help\-label \fIstring" +Override the label used for \*(``Help\*('' buttons. +. +.IP "\fB\-\-help\-status" +If the help-button is selected, +writes the checklist, radiolist or form information +after the item-help \*(``HELP\*('' information. +This can be used to reconstruct the state of a checklist after processing +the help request. +. +.IP "\fB\-\-help\-tags" +Modify the messages written on exit for \fB\-\-help\-button\fP +by making them always just the item's tag. +This does not affect the exit status code. +. +.IP "\fB\-\-hfile \fIfilename" +Display the given file using a textbox when the user presses F1. +. +.IP "\fB\-\-hline \fIstring" +Display the given string centered at the bottom of the widget. +. +.IP "\fB\-\-ignore" +Ignore options that \fB\*p\fP does not recognize. +Some well-known ones such as \*(``\fB\-\-icon\fP\*('' are ignored anyway, +but this is a better choice for compatibility with other implementations. +. +.IP "\fB\-\-input\-fd \fIfd" +Read keyboard input from the given file descriptor. +Most \fB\*p\fR scripts read from the standard input, +but the gauge widget reads a pipe (which is always standard input). +Some configurations do not work properly when +\fB\*p\fP tries to reopen the terminal. +Use this option (with appropriate juggling of file-descriptors) +if your script must work in that type of environment. +. +.IP "\fB\-\-insecure" +Makes the password widget friendlier but less secure, +by echoing asterisks for each character. +. +.IP "\fB\-\-iso\-week" +Set the starting point for the week-number +shown in the \*(``\fB\-\-calendar\fP\*('' option +according to ISO-8601, which starts numbering +with the first week which includes a Thursday in January. +. +.IP "\fB\-\-item\-help" +Interpret the tags data for checklist, radiolist and menu boxes +adding a column which is displayed in the bottom line of the +screen, for the currently selected item. +. +.IP "\fB\-\-keep\-tite" +When built with \fBncurses\fP, +\fB\*p\fP normally checks to see if it is running in an \fBxterm\fP, +and in that case tries to suppress the initialization strings that +would make it switch to the alternate screen. +Switching between the normal and alternate screens +is visually distracting in a script which runs \fB\*p\fP +several times. +Use this option to allow \fB\*p\fP to use those initialization strings. +. +.IP "\fB\-\-keep\-window" +Normally when \fB\*p\fR performs several \fBtailboxbg\fR widgets +connected by \*(``\fB\-\-and\-widget\fR\*('', +it clears the old widget from the screen by painting over it. +Use this option to suppress that repainting. +.IP +At exit, \fB\*p\fR repaints all of the widgets which have been +marked with \*(``\fB\-\-keep\-window\fR\*('', +even if they are not \fBtailboxbg\fR widgets. +That causes them to be repainted in reverse order. +See the discussion of the \*(``\fB\-\-clear\fR\*('' option for examples. +. +.IP "\fB\-\-last\-key" +At exit, report the last key which the user entered. +This is the curses key code rather than a symbol or literal character, +and is only reported for keys which are bound to an action. +It can be used by scripts to distinguish between two keys which are +bound to the same action. +. +.IP "\fB\-\-max\-input \fIsize" +Limit input strings to the given size. +If not specified, the limit is 2048. +. +.IP "\fB\-\-no\-cancel" +Suppress the \*(``Cancel\*('' button in checklist, inputbox and menu box modes. +A script can still test if the user pressed the ESC key to cancel to quit. +. +.IP "\fB\-\-no\-collapse" +Normally \fB\*p\fR converts tabs to spaces and reduces multiple +spaces to a single space for text which is displayed in a message boxes, etc. +Use this option to disable that feature. +Note that \fB\*p\fR will still wrap text, +subject to the \*(``\fB\-\-cr\-wrap\fR\*('' +and \*(``\fB\-\-trim\fR\*('' options. +.IP +The \fIno\-collapse\fP feature is implemented subject to these conditions: +.RS +.bP +the string contains \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option is +not used, or +.bP +the \fB\-\-trim\fP option is not used. +.RE +.IP +For more information, see \fBWhitespace Options\fP. +. +.IP "\fB\-\-no\-hot\-list" +Tells +\fB\*p\fP +to suppress the hotkey feature for lists, e.g., the checkbox, menus. +.IP +Normally, the first uppercase character of a list entry will be highlighted, +and typing that character will move the focus to that entry. +This option suppresses both the highlighting and the movement. +.IP +Hotkeys for buttons (\*(``OK\*('' , \*(``Cancel\*('', etc.) are unaffected. +. +.IP "\fB\-\-no\-items" +Some widgets (checklist, inputmenu, radiolist, menu) display a list +with two columns (a \*(``tag\*('' and \*(``item\*('', +i.e., \*(``description\*(''). +This option tells \fB\*p\fP to read shorter rows, +omitting the \*(``item\*('' part of the list. +This is occasionally useful, e.g., if the tags provide enough information. +.IP +See also \fB\-\-no\-tags\fP. +If both options are given, this one is ignored. +. +.IP "\fB\-\-no\-kill" +Tells +\fB\*p\fP +to put the +\fBtailboxbg\fP +box in the background, +printing its process id to \fB\*p\fP's output. +SIGHUP is disabled for the background process. +. +.IP "\fB\-\-no-label \fIstring" +Override the label used for \*(``No\*('' buttons. +. +.IP "\fB\-\-no\-lines" +Rather than draw lines around boxes, draw spaces in the same place. +See also \*(``\fB\-\-ascii\-lines\fR\*(''. +. +.IP "\fB\-\-no\-mouse" +Do not enable the mouse. +. +.IP "\fB\-\-no\-nl\-expand" +Do not convert \*(``\en\*('' substrings of the message/prompt text into +literal newlines. +.IP +The \fIno\-nl\-expand\fP feature is used only if +the string contains \*(``\en\*('' so that there is something to convert. +.IP +For more information, see \fBWhitespace Options\fP. +. +.IP "\fB\-\-no\-ok" +Suppress the \*(``OK\*('' button, so that it is not displayed. +A script can still test if the user pressed +the \*(``Enter\*('' key to accept the data: +.RS +.bP +The \*(``Enter\*('' key is always handled as the \*(``OK\*('' button +when the \fB\-\-no\-ok\fP option is used. +That is, by default it is bound to the \fILEAVE\fP virtual key. +.IP +When \fB\-\-no\-ok\fP is not used, +you can use the the \fITab\fP key to move the cursor through the +fields and buttons on the widget. +In that case, the \*(``Enter\*('' key activates the current button +if the cursor is positioned on a button. +.bP +To provide for the case where you want to activate a button +when using \fB\-\-no\-ok\fP, +there is another virtual key \fILEAVE\fP, +which activates the current button. +By default, \fB^D\fP (EOF) is bound to that key. +.RE +. +.IP "\fB\-\-no\-shadow" +Suppress shadows that would be drawn to the right and bottom of each dialog box. +. +.IP "\fB\-\-no\-tags" +Some widgets (checklist, inputmenu, radiolist, menu) display a list +with two columns (a \*(``tag\*('' and \*(``description\*(''). +The tag is useful for scripting, but may not help the user. +The \fB\-\-no\-tags\fP option (from Xdialog) may be used to suppress the +column of tags from the display. +Unlike the \fB\-\-no\-items\fP option, +this does not affect the data which is read from the script. +.IP +Xdialog does not display the tag column for the analogous buildlist +and treeview widgets; \fB\*p\fP does the same. +.IP +Normally \fB\*p\fP allows you to quickly move to entries on the displayed list, +by matching a single character to the first character of the tag. +When the \fB\-\-no\-tags\fP option is given, \fB\*p\fP matches against +the first character of the description. +In either case, the matchable character is highlighted. +. +.IP "\fB\-\-ok\-label \fIstring" +Override the label used for \*(``OK\*('' buttons. +. +.IP "\fB\-\-output\-fd \fIfd" +Direct output to the given file descriptor. +Most \fB\*p\fR scripts write to the standard error, +but error messages may also be written there, depending on your script. +. +.IP "\fB\-\-separator \fIstring" +.IP "\fB\-\-output\-separator \fIstring" +Specify a string that will separate the output on \fB\*p\fP's output from +checklists, rather than a newline (for \fB\-\-separate\-output\fP) or a space. +This applies to other widgets such as forms and editboxes which normally +use a newline. +. +.IP "\fB\-\-print\-maxsize" +Print the maximum size of dialog boxes, i.e., the screen size, +to \fB\*p\fP's output. +This may be used alone, without other options. +. +.IP "\fB\-\-print\-size" +Prints the size of each dialog box to \fB\*p\fP's output +when the box is initialized. +. +.IP "\fB\-\-print\-text\-only \fIstring [ height [ width ] ]" +Prints the string as it would be wrapped in a message box +to \fB\*p\fP's output. +.IP +Because the optional \fIheight\fP and \fIwidth\fP default to zero, +if they are omitted, \fB\*p\fP autosizes according to the screen dimensions. +. +.IP "\fB\-\-print\-text\-size \fIstring [ height [ width ] ]" +Prints the size of the string as it would be wrapped in a message box, +to \fB\*p\fP's output, +as +.Ex +height width +.Ee +.IP +Because the optional \fIheight\fP and \fIwidth\fP parameters default to zero, +if they are omitted, \fB\*p\fP autosizes according to the screen dimensions. +. +.IP "\fB\-\-print\-version" +Prints \fB\*p\fR's version to \fB\*p\fP's output. +This may be used alone, without other options. +It does not cause \fB\*l\fP to exit by itself. +. +.IP "\fB\-\-quoted" +Normally \fB\*p\fP quotes the strings returned by checklist's +as well as the item-help text. +Use this option to quote all string results as needed +(i.e., if the string contains whitespace or a single or double-quote character). +. +.IP "\fB\-\-reorder" +By default, the buildlist widget uses the same order for the output (right) +list as for the input (left). +Use this option to tell \fB\*p\fP to use the order +in which a user adds selections to the output list. +. +.IP "\fB\-\-scrollbar" +For widgets holding a scrollable set of data, +draw a scrollbar on its right-margin. +This does not respond to the mouse. +. +.IP "\fB\-\-separate\-output" +For certain widgets (buildlist, checklist, treeview), +output result one line at a time, with no quoting. +This facilitates parsing by another program. +. +.IP "\fB\-\-separate\-widget \fIstring" +Specify a string that will separate the output on \fB\*p\fP's output from +each widget. +This is used to simplify parsing the result of a dialog with several widgets. +If this option is not given, +the default separator string is a tab character. +. +.IP "\fB\-\-single\-quoted" +Use single-quoting as needed (and no quotes if unneeded) for the +output of checklist's as well as the item-help text. +.IP +If this option is not set, \fB\*p\fP may use double quotes around each item. +In either case, +\fB\*p\fP adds backslashes to make the output useful in shell scripts. +.IP +Single quotes would be needed if +the string contains whitespace or a single or double-quote character. +. +.IP "\fB\-\-size\-err" +Check the resulting size of a dialog box before trying to use it, +printing the resulting size if it is larger than the screen. +(This option is obsolete, since all new-window calls are checked). +. +.IP "\fB\-\-sleep \fIsecs" +Sleep (delay) for the given number of seconds after processing a dialog box. +. +.IP "\fB\-\-stderr" +Direct output to the standard error. +This is the default, since curses normally writes screen updates to +the standard output. +. +.IP "\fB\-\-stdout" +Direct output to the standard output. +This option is provided for compatibility with Xdialog, +however using it in portable scripts is not recommended, +since curses normally writes its screen updates to the standard output. +If you use this option, \fB\*p\fR attempts to reopen the terminal +so it can write to the display. +Depending on the platform and your environment, that may fail. +. +.IP "\fB\-\-tab\-correct" +Convert each tab character to one or more spaces +(for the \fBtextbox\fP widget; otherwise to a single space). +Otherwise, tabs are rendered according to the curses library's interpretation. +The \fB\-\-no\-collapse\fP option disables tab expansion. +. +.IP "\fB\-\-tab\-len \fIn" +Specify the number of spaces that a tab character occupies if the +\*(``\fB\-\-tab\-correct\fP\*('' option is given. +The default is 8. +This option is only effective for the \fBtextbox\fP widget. +. +.IP "\fB\-\-time\-format \fIformat" +If the host provides \fBstrftime\fP, +this option allows you to specify the format of the time printed for +the \fB\-\-timebox\fP widget. +The day, month, year values in this case are for the current local time. +. +.IP "\fB\-\-timeout \fIsecs" +Timeout if no user response within the given number of seconds. +A timeout of zero seconds is ignored. +.IP +Normally a timeout causes an ESC character to be entered in the current widget, +cancelling it. +Other widgets may still be on the screen; +these are not cancelled. +Set the \fBDIALOG_TIMEOUT\fP environment variable to tell \fB\*l\fP to +directly exit instead, i.e., cancelling all widgets on the screen. +.IP +This option is ignored by the \*(``\fB\-\-pause\fP\*('' widget. +It is also overridden +if the background \*(``\fB\-\-tailboxbg\fP\*('' option is used +to set up multiple concurrent widgets. +. +.IP "\fB\-\-title \fItitle" +Specifies a +\fItitle\fP +string to be displayed at the top of the dialog box. +. +.IP "\fB\-\-trace \fIfilename" +logs the command-line parameters, +keystrokes and other information to the given file. +If \fB\*l\fP reads a configure file, it is logged as well. +Piped input to the \fIgauge\fP widget is logged. +Use control/T to log a picture of the current dialog window. +.IP +The \fB\*p\fR program handles some command-line parameters specially, +and removes them from the parameter list as they are processed. +For example, if the first option is \fB\-\-trace\fP, +then that is processed (and removed) before \fB\*p\fR initializes the display. +. +.IP "\fB\-\-week\-start \fIday" +sets the starting day for the week, +used in the \*(``\fB\-\-calendar\fP\*('' option. +The \fIday\fP parameter can be +.RS +.bP +a number (0 to 6, Sunday through Saturday using POSIX) or +.bP +the special value \*(``locale\*('' (this works with systems using glibc, +providing an extension to the \fBlocale\fP command, +the \fBfirst_weekday\fP value). +.bP +a string matching one of the abbreviations for the day of the week +shown in the \fBcalendar\fP widget, e.g., \*(``Mo\*('' for \*(``Monday\*(''. +.RE +. +.IP "\fB\-\-trim" +eliminate leading blanks, +trim literal newlines and repeated blanks from message text. +.IP +The \fItrim\fP feature is implemented subject to these conditions: +.RS +.bP +the string does not contain \*(``\en\*('' or +.bP +the \fB\-\-no\-nl\-expand\fP option is used. +.RE +.IP +For more information, see \fBWhitespace Options\fP. +. +.IP +See also the \*(``\fB\-\-cr\-wrap\fR\*('' +and \*(``\fB\-\-no\-collapse\fR\*('' options. +. +.IP "\fB\-\-version" +Prints \fB\*p\fR's version to the standard output, and exits. +See also \*(``\fB\-\-print\-version\fP\*(''. +. +.IP "\fB\-\-visit\-items" +Modify the tab-traversal of checklist, radiolist, menubox and inputmenu +to include the list of items as one of the states. +This is useful as a visual aid, +i.e., the cursor position helps some users. +.IP +When this option is given, the cursor is initially placed on the list. +Abbreviations (the first letter of the tag) apply to the list items. +If you tab to the button row, abbreviations apply to the buttons. +. +.IP "\fB\-\-yes-label \fIstring" +Override the label used for \*(``Yes\*('' buttons. +. +.\" ************************************************************************ +.SS Box Options +All dialog boxes have at least three parameters: +.TP 7 +\fItext\fP +the caption or contents of the box. +.TP 7 +\fIheight\fP +the height of the dialog box. +.TP 7 +\fIwidth\fP +the width of the dialog box. +.PP +Other parameters depend on the box type. +. +. +.IP "\fB\-\-buildlist \fItext height width list-height \fR[ \fItag item status \fR] \fI..." +A \fBbuildlist\fP dialog displays two lists, side-by-side. +The list on the left shows unselected items. +The list on the right shows selected items. +As items are selected or unselected, they move between the lists. +.IP +Use a carriage return or the \*(``OK\*('' button to accept the current value +in the selected-window and exit. +The results are written using the order displayed in the selected-window. +.IP +The initial on/off state of each entry is specified by +.IR status "." +.IP +The dialog behaves like a \fBmenu\fP, using the \fB\-\-visit\-items\fP +to control whether the cursor is allowed to visit the lists directly. +.RS +.bP +If \fB\-\-visit\-items\fP is not given, +tab-traversal uses two states (OK/Cancel). +.bP +If \fB\-\-visit\-items\fP is given, +tab-traversal uses four states (Left/Right/OK/Cancel). +.RE +.IP +Whether or not \fB\-\-visit\-items\fP is given, +it is possible to move the highlight between the two lists using +the default \*(``^\*('' (left-column) and \*(``$\*('' (right-column) keys. +.IP +On exit, a list of the \fItag\fP +strings of those entries that are turned on +will be printed on \fB\*p\fP's output. +.IP +If the "\fB\-\-separate\-output\fP" option is not given, +the strings will be quoted as needed +to make it simple for scripts to separate them. +By default, this uses double-quotes, as needed. +See the \*(``\fB\-\-single\-quoted\fP\*('' option, +which modifies the quoting behavior. +. +.IP "\fB\-\-calendar \fItext height width day month year" +A \fBcalendar\fP box displays +month, day and year in separately adjustable windows. +If the values for day, month or year are missing or negative, +the current date's corresponding values are used. +You can increment or decrement any of those using the +left-, up-, right-, and down-arrows. +Use vi-style h, j, k and l for moving around the array of days in a month. +Use tab or backtab to move between windows. +If the year is given as zero, the current date is used as an initial value. +.IP +On exit, the date is printed in the form day/month/year. +The format can be overridden using the \fB\-\-date\-format\fP option. +. +.IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..." +A \fBchecklist\fP box is similar to a \fBmenu\fP box; +there are multiple entries presented in the form of a menu. +Another difference is +that you can indicate which entry is currently selected, by setting its +.IR status " to " on "." +Instead of choosing +one entry among the entries, each entry can be turned on or off by the user. +The initial on/off state of each entry is specified by +.IR status "." +.IP +On exit, a list of the \fItag\fP +strings of those entries that are turned on +will be printed on \fB\*p\fP's output. +.IP +If the \*(``\fB\-\-separate\-output\fP\*('' option is not given, +the strings will be quoted as needed +to make it simple for scripts to separate them. +By default, this uses double-quotes (as needed). +See the \*(``\fB\-\-single\-quoted\fP\*('' option, +which modifies the quoting behavior. +. +.IP "\fB\-\-dselect \fIfilepath height width\fR" +The directory-selection dialog displays a text-entry window +in which you can type a directory, +and above that a windows with directory names. +.IP +Here +\fBfilepath\fP +can be a filepath in which case the directory window +will display the contents of the path and the text-entry window will contain +the preselected directory. +.IP +Use tab or arrow keys to move between the windows. +Within the directory window, use the up/down arrow keys +to scroll the current selection. +Use the space-bar to copy the current selection into the text-entry +window. +.IP +Typing any printable characters switches focus to the text-entry window, +entering that character as well as scrolling the directory +window to the closest match. +.IP +Use a carriage return or the \*(``OK\*('' button to accept the current value +in the text-entry window and exit. +.IP +On exit, the contents of the text-entry window are written +to \fB\*p\fP's output. +. +.IP "\fB\-\-editbox \fIfilepath height width\fR" +The edit-box dialog displays a copy of the file. +You may edit it using +the \fIbackspace\fP, \fIdelete\fP and cursor keys +to correct typing errors. +It also recognizes pageup/pagedown. +Unlike the \fB\-\-inputbox\fP, +you must tab to the \*(``OK\*('' or \*(``Cancel\*('' buttons +to close the dialog. +Pressing the \*(``Enter\*('' key within the box will split +the corresponding line. +.IP +On exit, the contents of the edit window are written to \fB\*p\fP's output. +. +.nf +.IP "\fB\-\-form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..." +.fi +The \fBform\fP dialog displays a form consisting of labels and fields, +which are positioned on a scrollable window by coordinates given in the script. +The field length \fIflen\fR and input-length \fIilen\fR tell how long +the field can be. +The former defines the length shown for a selected field, +while the latter defines the permissible length of the data entered in the +field. +.RS +.bP +If \fIflen\fR is zero, the corresponding field cannot be altered. +and the contents of the field determine the displayed-length. +.bP +If \fIflen\fR is negative, the corresponding field cannot be altered, +and the negated value of \fIflen\fR is used as the displayed-length. +.bP +If \fIilen\fR is zero, it is set to \fIflen\fR. +.RE +.IP +Use up/down arrows (or control/N, control/P) to move between fields. +Use tab to move between windows. +.IP +On exit, the contents of the form-fields are written to \fB\*p\fP's output, +each field separated by a newline. +The text used to fill non-editable fields +(\fIflen\fR is zero or negative) +is not written out. +. +. +.IP "\fB\-\-fselect \fIfilepath height width\fR" +The \fBfselect\fP (file-selection) dialog displays a text-entry window +in which you can type a filename (or directory), +and above that two windows with directory names and filenames. +.IP +Here +\fBfilepath\fP +can be a filepath in which case the file and directory windows +will display the contents of the path and the text-entry window will contain +the preselected filename. +.IP +Use tab or arrow keys to move between the windows. +Within the directory or filename windows, use the up/down arrow keys +to scroll the current selection. +Use the space-bar to copy the current selection into the text-entry +window. +.IP +Typing any printable characters switches focus to the text-entry window, +entering that character as well as scrolling the directory and filename +windows to the closest match. +.IP +Typing the space character forces \fB\*p\fP to complete the current +name (up to the point where there may be a match against more than one +entry). +.IP +Use a carriage return or the \*(``OK\*('' button to accept the current value +in the text-entry window and exit. +.IP +On exit, the contents of the text-entry window are written +to \fB\*p\fP's output. +. +. +.IP "\fB\-\-gauge \fItext height width [percent]\fR" +A +\fBgauge\fP +box displays a meter along the bottom of the box. +The meter indicates the percentage. +New percentages are read from +standard input, one integer per line. +The meter is updated +to reflect each new percentage. +If the standard input reads the string \*(``XXX\*('', +then the first line following is taken as an integer percentage, +then subsequent lines up to another \*(``XXX\*('' are used for a new prompt. +The gauge exits when EOF is reached on the standard input. +.IP +The \fIpercent\fR value denotes the initial percentage shown in the meter. +If not specified, it is zero. +.IP +On exit, no text is written to \fB\*p\fP's output. +The widget accepts no input, so the exit status is always OK. +. +. +.IP "\fB\-\-infobox \fItext height width" +An \fBinfo\fP box is basically a \fBmessage\fP box. +However, in this case, \fB\*p\fP +will exit immediately after displaying the message to the user. +The screen is not cleared when \fB\*p\fP +exits, so that the message will remain on the screen until the calling +shell script clears it later. +This is useful when you want to inform +the user that some operations are carrying on that may require some +time to finish. +.IP +On exit, no text is written to \fB\*p\fP's output. +An OK exit status is returned. +. +. +.IP "\fB\-\-inputbox \fItext height width [init]" +An +\fBinput\fP +box is useful when you want to ask questions that +require the user to input a string as the answer. +If init is supplied +it is used to initialize the input string. +When entering the string, +the \fIbackspace\fP, \fIdelete\fP and cursor keys +can be used to correct typing errors. +If the input string is longer than +can fit in the dialog box, the input field will be scrolled. +.IP +On exit, the input string will be printed on \fB\*p\fP's output. +. +. +.IP "\fB\-\-inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..." +An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box. +There are only a few differences between them: +.RS +.TP 4 +1. +The entries are not automatically centered but left adjusted. +.TP +2. +An extra button (called \fIRename\/\fP) is implied to rename +the current item when it is pressed. +.TP +3. +It is possible to rename the current entry by pressing the +\fIRename\fP +button. +Then \fB\*p\fP will write the following on \fB\*p\fP's output. +.IP +RENAMED <tag> <item> +.RE +. +. +.IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..." +As its name suggests, a +\fBmenu\fP +box is a dialog box that can be used to present a list of choices in +the form of a menu for the user to choose. +Choices are displayed in the order given. +Each menu entry consists of a \fItag\fP string and an \fIitem\fP string. +The \fItag\fP +gives the entry a name to distinguish it from the other entries in the +menu. +The \fIitem\fP is a short description of the option that the entry represents. +The user can move between the menu entries by pressing the +cursor keys, the first letter of the \fItag\fP +as a hot-key, or the number keys \fI1\fP through \fI9\fP. +There are \fImenu-height\fP +entries displayed in the menu at one time, but the menu will be +scrolled if there are more entries than that. +.IP +On exit the \fItag\fP +of the chosen menu entry will be printed on \fB\*p\fP's output. +If the \*(``\fB\-\-help\-button\fR\*('' option is given, the corresponding help +text will be printed if the user selects the help button. +. +.nf +.IP "\fB\-\-mixedform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen itype \fR] \fI..." +.fi +The \fBmixedform\fP dialog displays a form consisting of labels and fields, +much like the \fB\-\-form\fP dialog. +It differs by adding a field-type parameter to each field's description. +Each bit in the type denotes an attribute of the field: +.RS +.TP 5 +1 +hidden, e.g., a password field. +.TP 5 +2 +readonly, e.g., a label. +.RE +. +.IP "\fB\-\-mixedgauge \fItext height width percent \fR[ \fItag1 item1 \fR] \fI..." +A \fBmixedgauge\fP box displays a meter along the bottom of the box. +The meter indicates the percentage. +.IP +It also displays a list of the \fItag\/\fP- and \fIitem\/\fP-values at the +top of the box. +See \*l(3) for the tag values. +.IP +The \fItext\fP is shown as a caption between the list and meter. +The \fIpercent\fR value denotes the initial percentage shown in the meter. +.IP +No provision is made for reading data from the standard input as \fB\-\-gauge\fP +does. +.IP +On exit, no text is written to \fB\*p\fP's output. +The widget accepts no input, so the exit status is always OK. +. +.IP "\fB\-\-msgbox \fItext height width" +A \fBmessage\fP box is very similar to a \fByes/no\fP box. +The only difference between a \fBmessage\fP box and a \fByes/no\fP +box is that a \fBmessage\fP box has only a single \fBOK\fP button. +You can use this dialog box to display any message you like. +After reading the message, the user can press the \fIENTER\fP key so that +\fB\*p\fP will exit and the calling shell script can continue its operation. +.IP +If the message is too large for the space, +\fB\*p\fP may allow you to scroll it, +provided that the underlying curses implementation is capable enough. +In this case, a percentage is shown in the base of the widget. +.IP +On exit, no text is written to \fB\*p\fP's output. +Only an \*(``OK\*('' button is provided for input, +but an ESC exit status may be returned. +. +.IP "\fB\-\-pause \fItext height width seconds\fR" +A +\fBpause\fP +box displays a meter along the bottom of the box. +The meter indicates how many seconds remain until the end of the pause. +The pause exits when timeout is reached +or the user presses the OK button +(status OK) +or the user presses the CANCEL button +or Esc key. +.IP "\fB\-\-passwordbox \fItext height width [init]" +A \fBpassword\fP box is similar to an input box, +except that the text the user enters is not displayed. +This is useful when prompting for passwords or other +sensitive information. +Be aware that if anything is passed in \*(``init\*('', it +will be visible in the system's process table to casual snoopers. +Also, it +is very confusing to the user to provide them with a default password they +cannot see. +For these reasons, using \*(``init\*('' is highly discouraged. +See \*(``\fB\-\-insecure\fP\*('' if you do not care about your password. +.IP +On exit, the input string will be printed on \fB\*p\fP's output. +. +. +.nf +.IP "\fB\-\-passwordform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..." +.fi +This is identical to \fB\-\-form\fP except that all text fields are +treated as \fBpassword\fP widgets rather than \fBinputbox\fP widgets. +. +. +.IP "\fB\-\-prgbox \fItext command height width" +.IP "\fB\-\-prgbox \fIcommand height width" +A \fBprgbox\fP is very similar to a \fBprogrambox\fP. +.IP +This dialog box is used to display the output of a command that is +specified as an argument to \fBprgbox\fP. +.IP +After the command completes, the user can press the \fIENTER\fP key so that +\fB\*l\fP will exit and the calling shell script can continue its operation. +.IP +If four parameters are given, it displays the text under the title, +delineated from the scrolling file's contents. +If only three parameters are given, this text is omitted. +. +. +.IP "\fB\-\-programbox \fItext height width" +.IP "\fB\-\-programbox \fIheight width" +A \fBprogrambox\fP is very similar to a \fBprogressbox\fP. +The only difference between a \fBprogram\fP box and a \fBprogress\fP +box is that a \fBprogram\fP box displays an \fBOK\fP button +(but only after the command completes). +.IP +This dialog box is used to display the piped output of a command. +After the command completes, the user can press the \fIENTER\fP key so that +\fB\*l\fP will exit and the calling shell script can continue its operation. +.IP +If three parameters are given, it displays the text under the title, +delineated from the scrolling file's contents. +If only two parameters are given, this text is omitted. +. +. +.IP "\fB\-\-progressbox \fItext height width" +.IP "\fB\-\-progressbox \fIheight width" +A \fBprogressbox\fP is similar to an \fBtailbox\fP, +except that +.RS +.TP 3 +a) rather than displaying the contents of a file, +it displays the piped output of a command and +.TP 3 +b) it will exit when it reaches the end of the file +(there is no \*(``OK\*('' button). +.RE +.IP +If three parameters are given, it displays the text under the title, +delineated from the scrolling file's contents. +If only two parameters are given, this text is omitted. +. +. +.IP "\fB\-\-radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..." +A \fBradiolist\fP box is similar to a \fBmenu\fP box. +The only difference is +that you can indicate which entry is currently selected, by setting its +.IR status " to " on "." +.IP +On exit, the tag of the selected item is written to \fB\*p\fP's output. +. +. +.nf +.IP "\fB\-\-rangebox \fItext height width min-value max-value default-value" +.fi +Allow the user to select from a range of values, e.g., using a slider. +The dialog shows the current value as a bar (like the gauge dialog). +Tabs or arrow keys move the cursor between the buttons and the value. +When the cursor is on the value, +you can edit it by: +.RS +.TP 5 +left/right cursor movement to select a digit to modify +.TP 5 ++/- +characters to increment/decrement the digit by one +.TP 5 +0 through 9 +to set the digit to the given value +.RE +.IP +Some keys are also recognized in all cursor positions: +.RS +.TP 5 +home/end +set the value to its maximum or minimum +.TP 5 +pageup/pagedown +increment the value so that the slider moves by one column +.RE +. +. +.IP "\fB\-\-tailbox \fIfile height width" +Display text from a file in a dialog box, +as in a \*(``tail -f\*('' command. +Scroll left/right using vi-style 'h' and 'l', or arrow-keys. +A '0' resets the scrolling. +.IP +On exit, no text is written to \fB\*p\fP's output. +Only an \*(``OK\*('' button is provided for input, +but an ESC exit status may be returned. +. +. +.IP "\fB\-\-tailboxbg \fIfile height width" +Display text from a file in a dialog box as a background task, +as in a \*(``tail -f &\*('' command. +Scroll left/right using vi-style 'h' and 'l', or arrow-keys. +A '0' resets the scrolling. +.IP +\*L treats the background task specially if there are other +widgets (\fB\-\-and\-widget\fP) on the screen concurrently. +Until those widgets are closed (e.g., an \*(``OK\*(''), +\fB\*p\fP will perform all of the tailboxbg widgets in the same process, +polling for updates. +You may use a tab to traverse between the widgets on the screen, +and close them individually, e.g., by pressing \fIENTER\fP. +Once the non-tailboxbg widgets are closed, +\fB\*p\fP forks a copy of itself into the background, +and prints its process id if the \*(``\fB\-\-no\-kill\fP\*('' option +is given. +.IP +On exit, no text is written to \fB\*p\fP's output. +Only an \*(``EXIT\*('' button is provided for input, +but an ESC exit status may be returned. +.IP +NOTE: +Older versions of \fB\*p\fP forked immediately and attempted to +update the screen individually. +Besides being bad for performance, +it was unworkable. +Some older scripts may not work properly with the polled scheme. +. +. +.IP "\fB\-\-textbox \fIfile height width" +A +\fBtext\fP +box lets you display the contents of a text file in a dialog box. +It is like a simple text file viewer. +The user can move through the file by using the +cursor, page-up, page-down +and \fIHOME/END\fR keys available on most keyboards. +If the lines are too long to be displayed in the box, +the \fILEFT/RIGHT\fP +keys can be used to scroll the text region horizontally. +You may also use vi-style keys h, j, k, and l in place of the cursor keys, +and B or N in place of the page-up and page-down keys. +Scroll up/down using vi-style 'k' and 'j', or arrow-keys. +Scroll left/right using vi-style 'h' and 'l', or arrow-keys. +A '0' resets the left/right scrolling. +For more convenience, +vi-style forward and backward searching functions are also provided. +.IP +On exit, no text is written to \fB\*p\fP's output. +Only an \*(``EXIT\*('' button is provided for input, +but an ESC exit status may be returned. +. +. +.IP "\fB\-\-timebox \fItext height [width hour minute second]" +A dialog is displayed which allows you to select hour, minute and second. +If the values for hour, minute or second are missing or negative, +the current date's corresponding values are used. +You can increment or decrement any of those using the +left-, up-, right- and down-arrows. +Use tab or backtab to move between windows. +.IP +On exit, the result is printed in the form hour:minute:second. +The format can be overridden using the \fB\-\-time\-format\fP option. +. +. +.IP "\fB\-\-treeview \fItext height width list-height \fR[ \fItag item status depth \fR] \fI..." +Display data organized as a tree. +Each group of data contains a tag, +the text to display for the item, +its status (\*(``on\*('' or \*(``off\*('') +and the depth of the item in the tree. +.IP +Only one item can be selected (like the \fBradiolist\fP). +The tag is not displayed. +.IP +On exit, the tag of the selected item is written to \fB\*p\fP's output. +. +. +.IP "\fB\-\-yesno \fItext height width" +A \fByes/no\fP dialog box of +size \fIheight\fP rows by \fIwidth\fP columns will be displayed. +The string specified by +\fItext\fP +is displayed inside the dialog box. +If this string is too long to fit +in one line, it will be automatically divided into multiple lines at +appropriate places. +The +\fItext\fP +string can also contain the sub-string +.RI """" \en """" +or newline characters +.RI ` \en ' +to control line breaking explicitly. +This dialog box is useful for +asking questions that require the user to answer either yes or no. +The dialog box has a +\fBYes\fP +button and a +\fBNo\fP +button, in which the user can switch between by pressing the +.IR TAB " key." +.IP +On exit, no text is written to \fB\*p\fP's output. +In addition to the \*(``Yes\*('' and \*(``No\*('' exit codes (see DIAGNOSTICS) +an ESC exit status may be returned. +.IP +The codes used for \*(``Yes\*('' and \*(``No\*('' +match those used for \*(``OK\*('' and \*(``Cancel\*('', +internally no distinction is made. +. +.\" ************************************************************************ +.SS "Obsolete Options" +.\" from cdialog 0.9a (Pako) +.IP "\fB\-\-beep" +This was used to tell the original cdialog that it should make a beep +when the separate processes of the tailboxbg widget would repaint the screen. +. +.\" from cdialog 0.9a (Pako) +.IP "\fB\-\-beep\-after" +Beep after a user has completed a widget by pressing one of the buttons. +. +.\" ************************************************************************ +.SS "Whitespace Options" +These options can be used to transform whitespace (space, tab, newline) +as dialog reads the script: +.RS +.BR \-\-cr\-wrap , +.BR \-\-no\-collapse , +.BR \-\-no\-nl\-expand ", and" +.B \-\-trim +.RE +.PP +The options are not independent: +.bP +\fB\*L\fP checks if the script contains at least one \*(``\en\*('' +and (unless \fB\-\-no\-nl\-expand\fP is set) will ignore the +\fB\-\-no\-collapse\fP and \fB\-\-trim\fP options. +.bP +After checking for \*(``\en\*('' and the \fB\-\-no\-nl\-expand\fP option, +\fB\*l\fP handles the \fB\-\-trim\fP option. +.IP +If the \fB\-\-trim\fP option takes effect, +then \fB\*l\fP ignores \fB\-\-no\-collapse\fP. +It changes sequences of tabs, spaces +(and newlines unless \fB\-cr\-wrap\fP is set) to a single space. +.bP +If neither the \*(``\en\*('' or \fB\-\-trim\fP cases apply, +\fB\*l\fP checks \fB\-\-no\-collapse\fP to decide whether to reduce +sequences of tabs and spaces to a single space. +.IP +In this case, \fB\*l\fP ignores \fB\-\-cr\-wrap\fP and does not modify newlines. +.PP +Taking those dependencies into account, +here is a table summarizing the behavior +for the various combinations of options. +The table assumes that the script contains at least one \*(``\en\*('' +when the \fB\-\-no\-nl\-expand\fP option is not set. +.na +.RS 5 +.TS +tab(/) ; +lB lB lB lB lB +lB lB lB lB lB +_ _ _ _ _ +lw4 lw4 lw4 lw4 lw29. +cr-/no-/no-/trim/Result +wrap/collapse/nl\-expand +no/no/no/no/T{ +Convert tab to space. +Convert newline to space. +Convert \*(``\en\*('' to newline. +T} +no/no/no/yes/T{ +Convert tab to space. +Convert newline to space. +Convert \*(``\en\*('' to newline. +T} +no/no/yes/no/T{ +Convert tab to space. +Do not convert newline to space. +Convert multiple-space to single. +Show \*(``\en\*('' literally. +T} +no/no/yes/yes/T{ +Convert tab to space. +Convert multiple-space to single. +Convert newline to space. +Show \*(``\en\*('' literally. +T} +no/yes/no/no/T{ +Convert newline to space. +Convert \*(``\en\*('' to newline. +T} +no/yes/no/yes/T{ +Convert newline to space. +Convert \*(``\en\*('' to newline. +T} +no/yes/yes/no/T{ +Do not convert newline to space. +Do not reduce multiple blanks. +Show \*(``\en\*('' literally. +T} +no/yes/yes/yes/T{ +Convert multiple-space to single. +Convert newline to space. +Show \*(``\en\*('' literally. +T} +yes/no/no/no/T{ +Convert tab to space. +Wrap on newline. +Convert \*(``\en\*('' to newline. +T} +yes/no/no/yes/T{ +Convert tab to space. +Wrap on newline. +Convert \*(``\en\*('' to newline. +T} +yes/no/yes/no/T{ +Convert tab to space. +Do not convert newline to space. +Convert multiple-space to single. +Show \*(``\en\*('' literally. +T} +yes/no/yes/yes/T{ +Convert tab to space. +Convert multiple-space to single. +Wrap on newline. +Show \*(``\en\*('' literally. +T} +yes/yes/no/no/T{ +Wrap on newline. +Convert \*(``\en\*('' to newline. +T} +yes/yes/no/yes/T{ +Wrap on newline. +Convert \*(``\en\*('' to newline. +T} +yes/yes/yes/no/T{ +Do not convert newline to space. +Do not reduce multiple blanks. +Show \*(``\en\*('' literally. +T} +yes/yes/yes/yes/T{ +Convert multiple-space to single. +Wrap on newline. +Show \*(``\en\*('' literally. +T} +.TE +.RE +.ad +. +.\" ************************************************************************ +.SH "RUN-TIME CONFIGURATION" +.TP 4 +1. +Create a sample configuration file by typing: +.LP +.Ex +\*p \-\-create\-rc \fIfile\fP +.Ee +.TP 4 +2. +At start, +\fB\*p\fP +determines the settings to use as follows: +.RS +.TP 4 +a) +if environment variable +\fBDIALOGRC\fP +is set, its value determines the name of the configuration file. +.TP 4 +b) +if the file in (a) is not found, use the file +\fI$HOME/.dialogrc\fP +as the configuration file. +.TP 4 +c) +if the file in (b) is not found, try using the GLOBALRC file determined at +compile-time, i.e., \fI/etc/dialogrc\fP. +.TP 4 +d) +if the file in (c) is not found, use compiled in defaults. +.RE +.TP 4 +3. +Edit the sample configuration file and copy it to some place that +\fB\*p\fP +can find, as stated in step 2 above. +. +.\" ************************************************************************ +.SH "KEY BINDINGS" +You can override or add to key bindings in \fB\*p\fP +by adding to the configuration file. +\fB\*L\fP's \fBbindkey\fP command maps single keys to its internal coding. +.Ex +bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP +.Ee +.PP +The \fIwidget\fP name can be \*(``*\*('' (all widgets), or +specific widgets such as \fBtextbox\fP. +Specific widget bindings override the \*(``*\*('' bindings. +User-defined bindings override the built-in bindings. +.PP +The \fIcurses_key\fP can be expressed in different forms: +.bP +It may be any of the names derived from +\fBcurses.h\fP, e.g., \*(``HELP\*('' from \*(``KEY_HELP\*(''. +.bP +\fB\*L\fP also recognizes ANSI control characters +such as \*(``^A\*('', \*(``^?\*('', +as well as C1-controls such as \*(``~A\*('' and \*(``~?\*(''. +.bP +Finally, \fB\*l\fP allows backslash escapes as in C. +Those can be octal character values such as \*(``\\033\*('' +(the ASCII escape character), +or the characters listed in this table: +.RS 10 +.TS +tab(/) ; +lI lI +_ _ +l l . +Escaped/Actual +\\b/backspace +\\f/form feed +\\n/new line (line feed) +\\r/carriage return +\\s/space +\\t/tab +\\^/\*(``^\*('' (caret) +\\?/\*(``?\*('' (question mark) +\\\\/\*(``\\\*('' (backslash) +_ +.TE +.RE +.PP +\fB\*L\fP's internal keycode names correspond to the +\fBDLG_KEYS_ENUM\fP type in +\fBdlg_keys.h\fP, e.g., \*(``HELP\*('' from \*(``DLGK_HELP\*(''. +.SS Widget Names +Some widgets (such as the formbox) have an area where fields can be edited. +Those are managed in a subwindow of the widget, and +may have separate keybindings from the main widget +because the subwindows are registered using a different name. +.RS 5 +.TS +tab(/) ; +lI lI lI +_ _ _ +l l l . +Widget/Window name/Subwindow Name +calendar/calendar +checklist/checklist +editbox/editbox/editbox2 +form/formbox/formfield +fselect/fselect/fselect2 +inputbox/inputbox/inputbox2 +menu/menubox/menu +msgbox/msgbox +pause/pause +progressbox/progressbox +radiolist/radiolist +tailbox/tailbox +textbox/textbox/searchbox +timebox/timebox +yesno/yesno +_ +.TE +.RE +.PP +Some widgets are actually other widgets, +using internal settings to modify the behavior. +Those use the same widget name as the actual widget: +.RS 5 +.TS +tab(/) ; +lI lI +_ _ +l l . +Widget/Actual Widget +dselect/fselect +infobox/msgbox +inputmenu/menu +mixedform/form +passwordbox/inputbox +passwordform/form +prgbox/progressbox +programbox/progressbox +tailboxbg/tailbox +_ +.TE +.RE +.SS Built-in Bindings +This manual page does not list the key bindings for each widget, +because that detailed information can be obtained by running \fB\*p\fP. +If you have set the \fB\-\-trace\fP option, +\fB\*p\fP writes the key-binding information for each widget +as it is registered. +.PP +A few bindings are built-in, independent of particular widgets: +.TS +tab(/) ; +lI lI +_ _ +l l . +Key/Purpose +Control-I/forward tab-traversal, e.g., with \fB\-\-tailboxbg\fP. +Control-L/repaints the screen. +Control-T/writes a screen dump to the \fB\-\-trace\fP file. +Control-V/suppresses special-keys for the next input byte. +DLGK_FIELD_NEXT/forward tab-traversal, like Control-I. +DLGK_FIELD_PREV/backward tab-traversal, like back-tab. +DLGK_HELPFILE/displays the help-file specified with \fB\-\-hfile\fP. +KEY_BTAB/backward tab-traversal, e.g., with \fB\-\-tailboxbg\fP. +_ +.TE + +.SS Example +Normally \fB\*p\fP uses different keys for navigating between the buttons +and editing part of a dialog versus navigating within the editing part. +That is, tab (and back-tab) traverse buttons +(or between buttons and the editing part), +while arrow keys traverse fields within the editing part. +Tabs are also recognized as a special case for traversing between +widgets, e.g., when using multiple tailboxbg widgets. +.PP +Some users may wish to use the same key for traversing within the +editing part as for traversing between buttons. +The form widget is written to support this sort of redefinition of +the keys, by adding a special group in \fBdlgk_keys.h\fP +for \*(``form\*('' (left/right/next/prev). +Here is an example binding demonstrating how to do this: +.Ex +bindkey formfield TAB form_NEXT +bindkey formbox TAB form_NEXT +bindkey formfield BTAB form_prev +bindkey formbox BTAB form_prev +.Ee +.PP +That type of redefinition would not be useful in other widgets, +e.g., calendar, due to the potentially large number of fields to traverse. +. +.SH EXIT STATUS +Exit status is subject to being overridden by environment variables. +The default values and corresponding environment variables +that can override them are: +.TP 5 +0 +if the \fBYES\fP or \fBOK\fP button is pressed (DIALOG_OK). +.TP 5 +1 +if the +.BR No " or " Cancel +button is pressed (DIALOG_CANCEL). +.TP 5 +2 +if the +.B Help +button is pressed (DIALOG_HELP), +.br +except as noted below about DIALOG_ITEM_HELP. +.TP 5 +3 +if the +.B Extra +button is pressed (DIALOG_EXTRA). +.TP 5 +4 +if the +.B Help +button is pressed, +.br +and the \fB\-\-item\-help\fP option is set +.br +and the DIALOG_ITEM_HELP environment variable is set to 4. +.IP +While any of the exit-codes can be overridden using environment variables, +this special case was introduced in 2004 to simplify compatibility. +\fB\*L\fP uses DIALOG_ITEM_HELP (4) internally, +but unless the environment variable is also set, +it changes that to DIALOG_HELP (2) on exit. +.TP 5 +5 +if a timeout expires and the \fBDIALOG_TIMEOUT\fP variable is set to 5. +.TP 5 +\-1 +if errors occur inside \fB\*p\fP (DIALOG_ERROR) +or \fB\*p\fP exits because the \fIESC\fP key (DIALOG_ESC) was pressed. +.\" ************************************************************************ +.SH ENVIRONMENT +.TP 15 +\fBDIALOGOPTS\fP +Define this variable to apply any of the common options to each widget. +Most of the common options are reset before processing each widget. +If you set the options in this environment variable, +they are applied to \fB\*p\fP's state after the reset. +As in the \*(``\fB\-\-file\fP\*('' option, +double-quotes and backslashes are interpreted. +.IP +The \*(``\fB\-\-file\fP\*('' option is not considered a common option +(so you cannot embed it within this environment variable). +.TP 15 +\fBDIALOGRC\fP +Define this variable if you want to specify the name of the configuration file +to use. +.TP 15 +\fBDIALOG_CANCEL\fP +.TP 15 +\fBDIALOG_ERROR\fP +.TP 15 +\fBDIALOG_ESC\fP +.TP 15 +\fBDIALOG_EXTRA\fP +.TP 15 +\fBDIALOG_HELP\fP +.TP 15 +\fBDIALOG_ITEM_HELP\fP +.TP 15 +\fBDIALOG_TIMEOUT\fP +.TP 15 +\fBDIALOG_OK\fP +Define any of these variables to change the exit code on +.RS +.bP +Cancel (1), +.bP +error (\-1), +.bP +ESC (255), +.bP +Extra (3), +.bP +Help (2), +.bP +Help with \fB\-\-item\-help\fP (2), +.bP +Timeout (5), or +.bP +OK (0). +.RE +.IP +Normally shell scripts cannot distinguish between \-1 and 255. +.TP 15 +\fBDIALOG_TTY\fP +Set this variable to \*(``1\*('' to provide compatibility with older versions +of \fB\*p\fP which assumed that if the script redirects the standard output, +that the \*(``\fB\-\-stdout\fP\*('' option was given. +.\" ************************************************************************ +.SH FILES +.TP 20 +\fI$HOME/.dialogrc\fP +default configuration file +.\" ************************************************************************ +.SH PORTABILITY +\fB\*L\fP works with X/Open curses. +However, some implementations have deficiencies: +.RS 3 +.bP +HPUX curses (and perhaps others) do not open the terminal properly for +the \fInewterm\fP function. +This interferes with \fB\*p\fP's \fB\-\-input\-fd\fP option, +by preventing cursor-keys and similar escape sequences from being recognized. +.bP +NetBSD 5.1 curses has incomplete support for wide-characters. +\fB\*p\fP will build, but not all examples display properly. +.RE +.\" ************************************************************************ +.SH COMPATIBILITY +You may want to write scripts which run with +other \fB\*l\fP \*(``clones\*(''. +.SS Original Dialog +First, there is the \*(``original\*('' \fB\*p\fP program to consider +(versions 0.3 to 0.9). +It had some misspelled (or inconsistent) options. +The \fB\*p\fP program maps those deprecated options to the preferred ones. +They include: +.RS +.TS +tab(/) ; +lI lI +_ _ +l l. +Option/Treatment +\fB\-\-beep\-after\fP/ignored +\fB\-\-guage\fP/mapped to \fB\-\-gauge\fP +_ +.TE +.RE +.SS Xdialog +This is an X application, rather than a terminal program. +With some care, it is possible to write useful scripts that work +with both \fBXdialog\fP and \fB\*p\fP. +.PP +The \fB\*p\fP program ignores these options which are recognized +by \fBXdialog\fP: +.RS +.TS +tab(/) ; +lI lI +_ _ +l l. +Option/Treatment +\fB\-\-allow\-close\fP/ignored +\fB\-\-auto\-placement\fP/ignored +\fB\-\-fixed\-font\fP/ignored +\fB\-\-icon\fP/ignored +\fB\-\-keep\-colors\fP/ignored +\fB\-\-no\-close\fP/ignored +\fB\-\-no\-cr\-wrap\fP/ignored +\fB\-\-screen\-center\fP/ignored +\fB\-\-separator\fP/mapped to \fB\-\-separate\-output\fP +\fB\-\-smooth\fP/ignored +\fB\-\-under\-mouse\fP/ignored +\fB\-\-wmclass\fP/ignored +_ +.TE +.RE +.PP +\fBXdialog\fP's manpage has a section discussing its compatibility +with \fB\*p\fP. +There are some differences not shown in the manpage. +For example, the html documentation states +.RS +.PP +Note: former Xdialog releases used the \*(``\en\*('' (line feed) as a +results separator for the checklist widget; +this has been changed to \*(``/\*('' in Xdialog v1.5.0 +to make it compatible with (c)dialog. +In your old scripts using the Xdialog checklist, you +will then have to add the \fB\-\-separate\-output\fP option before the +\fB\-\-checklist\fP one. +.RE +.PP +\fB\*L\fP has not used a different separator; +the difference was likely due to confusion regarding some script. +.SS Whiptail +Then there is \fBwhiptail\fP. +For practical purposes, it is maintained by Debian +(very little work is done by its upstream developers). +Its documentation (README.whiptail) claims +.Ex +\fBwhiptail\fP(1) is a lightweight replacement for \*p(1), +to provide dialog boxes for shell scripts. +It is built on the +newt windowing library rather than the ncurses library, allowing +it to be smaller in embedded environments such as installers, +rescue disks, etc. + +whiptail is designed to be drop-in compatible with \*p, but +has less features: some dialog boxes are not implemented, such +as tailbox, timebox, calendarbox, etc. +.Ee +.PP +Comparing actual sizes (Debian testing, 2007/1/10): +The total of sizes for \fBwhiptail\fP, +the newt, popt and slang libraries is 757\ KB. +The comparable number for \fB\*p\fP (counting ncurses) is 520\ KB. +Disregard the first paragraph. +.PP +The second paragraph is misleading, since \fBwhiptail\fP +also does not work for common options of \fB\*p\fP, +such as the gauge box. +\fBwhiptail\fP is less compatible with \fB\*p\fP than the +original mid-1990s dialog 0.4 program. +.PP +\fBwhiptail\fP's manpage borrows features from \fB\*p\fP, e.g., +but oddly cites only \fB\*p\fP versions up to 0.4 (1994) as a source. +That is, its manpage refers to features which +were borrowed from more recent versions of \fB\*p\fP, e.g., +.bP +\fB\-\-gauge\fP (from 0.5) +.bP +\fB\-\-passwordbox\fP (from Debian changes in 1999), +.bP +\fB\-\-default\-item\fP (from \fB\*p\fP 2000/02/22), +.bP +\fB\-\-output\-fd\fP (from \fB\*p\fP 2002/08/14). +.PP +Debian uses \fBwhiptail\fP for the official \fB\*p\fP variation. +.PP +The \fB\*p\fP program ignores or maps these options which are recognized +by \fBwhiptail\fP: +.RS +.TS +tab(/) ; +lI lI +_ _ +l l. +Option/Treatment +\fB\-\-cancel\-button\fP/mapped to \fB\-\-cancel\-label\fP +\fB\-\-fb\fP/ignored +\fB\-\-fullbutton\fP/ignored +\fB\-\-no\-button\fP/mapped to \fB\-\-no\-label\fP +\fB\-\-nocancel\fP/mapped to \fB\-\-no\-cancel\fP +\fB\-\-noitem\fP/mapped to \fB\-\-no\-items\fP +\fB\-\-notags\fP/mapped to \fB\-\-no\-tags\fP +\fB\-\-ok\-button\fP/mapped to \fB\-\-ok\-label\fP +\fB\-\-scrolltext\fP/mapped to \fB\-\-scrollbar\fP +\fB\-\-topleft\fP/mapped to \fB\-\-begin 0 0\fP +\fB\-\-yes\-button\fP/mapped to \fB\-\-yes\-label\fP +_ +.TE +.RE +.LP +There are visual differences which are not addressed by command-line options: +.bP +\fB\*p\fP centers lists within the window. +\fBwhiptail\fP typically puts lists against the left margin. +.bP +\fBwhiptail\fP uses angle brackets (\*(``<\*('' and \*(``>\*('') +for marking buttons. +\fB\*p\fP uses square brackets. +.bP +\fBwhiptail\fP marks the limits of subtitles with vertical bars. +\fB\*p\fP does not mark the limits. +.bP +\fBwhiptail\fP attempts to mark the top/bottom cells of a scrollbar +with up/down arrows. +When it cannot do this, +it fills those cells with the background color +of the scrollbar and confusing the user. +\fB\*p\fP uses the entire scrollbar space, +thereby getting better resolution. +.\" ************************************************************************ +.SH BUGS +Perhaps. +.\" ************************************************************************ +.SH EXAMPLES +The \fB\*p\fP sources contain several samples +of how to use the different box options and how they look. +Just take a look into the directory \fBsamples/\fP of the source. +.\" ************************************************************************ +.SH AUTHORS +Thomas E.\& Dickey (updates for 0.9b and beyond) +.LP +Kiran Cherupally \(en the mixed form and mixed gauge widgets. +.LP +Tobias C.\& Rittweiler +.LP +Valery Reznic \(en the form and progressbox widgets. +.LP +Yura Kalinichenko adapted the gauge widget as \*(``pause\*(''. +.PP +This is a rewrite (except as needed to provide compatibility) +of the earlier version of \fB\*p 0.9a\fP, +which lists as authors: +.bP +Savio Lam \(en version 0.3, \*(``dialog\*('' +.bP +Stuart Herbert \(en patch for version 0.4 +.bP +Marc Ewing \(en the gauge widget. +.bP +Pasquale De Marco \*(``Pako\*('' \(en version 0.9a, \*(``cdialog\*('' |