diff options
Diffstat (limited to 'Build/source/utils/dialog/dialog-1.1-20080819/dialog.1')
| -rw-r--r-- | Build/source/utils/dialog/dialog-1.1-20080819/dialog.1 | 1247 |
1 files changed, 1247 insertions, 0 deletions
diff --git a/Build/source/utils/dialog/dialog-1.1-20080819/dialog.1 b/Build/source/utils/dialog/dialog-1.1-20080819/dialog.1 new file mode 100644 index 00000000000..c99e4fbd8ce --- /dev/null +++ b/Build/source/utils/dialog/dialog-1.1-20080819/dialog.1 @@ -0,0 +1,1247 @@ +'\" t +.\" $Id: dialog.1,v 1.115 2008/07/27 22:49:40 tom Exp $ +.\" Copyright 2005-2007,2008 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. +.de ES +.ne 8 +.IP +.. +.de EX +.RS +10 +.nf +.. +.de EE +.fi +.RE +.. +. +.TH DIALOG 1 "" "$Date: 2008/07/27 22:49:40 $" +.SH NAME +dialog \- display dialog boxes from shell scripts +.SH SYNOPSIS +\fBdialog --clear\fP +.br +.BI "dialog --create-rc " file +.br +\fBdialog --print-maxsize\fP +.br +\fBdialog\fP +\fIcommon-options\fP +\fIbox-options\fP +.SH DESCRIPTION +\fBDialog\fP +is a program that will let you to 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 \fBdialog\fR): +.RS +.LP +.nh +.na +.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 progressbox ", " +.BR radiolist ", " +.BR tailbox ", " +.BR tailboxbg ", " +.BR textbox ", " +.BR timebox ", and " +.BR yesno " (yes/no)." +.ad +.hy +.RE +.PP +You can put more than one dialog box into a script: +.TP 5 +- +Use the "\fB--and-widget\fP" token to force Dialog to proceed to the next +dialog unless you have pressed ESC to cancel, or +.TP 5 +- +Simply add the tokens for the next dialog box, making a chain. +Dialog 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 \fBdialog\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; +\fBdialog\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. +.RS +.B dialog --title -- --Not an option +.RE +.PP +The "\fB--args\fP" option tells \fBdialog\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 \fBdialog\fP to read parameters from +the file named as its value. +.RS +.B dialog --file \fIparameterfile +.RE +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 "&", \fBdialog\fP +interprets the following text as a file descriptor number +rather than a filename. +. +.SS \fBCommon Options\fP +. +.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 +dialog --begin 2 2 --yesno "" 0 0 \\ + --and-widget --begin 4 4 --yesno "" 0 0 \\ + --and-widget --begin 6 6 --yesno "" 0 0 +.EE +. +.ES +Only the last widget is left visible: +.EX +dialog --clear --begin 2 2 --yesno "" 0 0 \\ + --and-widget --clear --begin 4 4 --yesno "" 0 0 \\ + --and-widget --begin 6 6 --yesno "" 0 0 +.EE +. +.ES +All three widgets visible, staircase effect, ordered 3,2,1: +.EX +dialog --keep-window --begin 2 2 --yesno "" 0 0 \\ + --and-widget --keep-window --begin 4 4 --yesno "" 0 0 \\ + --and-widget --begin 6 6 --yesno "" 0 0 +.EE +. +.ES +First and third widget visible, staircase effect, ordered 3,1: +.EX +dialog --keep-window --begin 2 2 --yesno "" 0 0 \\ + --and-widget --clear --begin 4 4 --yesno "" 0 0 \\ + --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. +. +.IP "\fB--colors" +Interpret embedded "\\Z" sequences in the dialog text +by the following character, +which tells \fBdialog\fP to set colors or video attributes: +0 through 7 are the ANSI used in curses: +black, +red, +green, +yellow, +blue, +magenta, +cyan and +white respectively. +Bold is set by 'b', reset by 'B'. +Reverse is set by 'r', reset by 'R'. +Underline is set by 'u', reset by 'U'. +The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text +bold (perhaps bright) red. +Restore normal settings with "\\Zn". +. +.IP "\fB--column-separator \fIstring" +Tell \fBdialog\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, \fBdialog\fR will only wrap lines where needed to fit inside the text box. +Even though you can control line breaks with this, +\fBdialog\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 +See also the "\fB--no-collapse\fP" and "\fB--trim\fP" options. +. +.IP "\fB--create-rc \fIfile" +When +\fBdialog\fP +supports run-time configuration, +this can be used to dump a sample configuration file to the file specified +by +.IR file "." +. +.IP "\fB--defaultno" +Make the default value of the +\fByes/no\fP +box a +.BR No . +Likewise, make the default button of widgets that provide "OK" and "Cancel" +a \fBCancel\fP. +If "\fB--nocancel\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-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--exit-label \fIstring" +Override the label used for "EXIT" buttons. +. +.IP "\fB--extra-button" +Show an extra button, between "OK" and "Cancel" buttons. +. +.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 \fBdialog\fP's output. +The help message is printed if no options are given. +. +.IP "\fB--help-button" +Show a help-button after "OK" and "Cancel" buttons, +i.e., in checklist, radiolist and menu boxes. +If "\fB--item-help\fR" is also given, on exit +the return status will be the same as for the "OK" button, +and the item-help text will be written to \fBdialog\fP's output after the token "HELP". +Otherwise, the return status will indicate that the Help button was pressed, +and no message printed. +. +.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--ignore" +Ignore options that \fBdialog\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 \fBdialog\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 +\fBdialog\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--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" +Normally \fBdialog\fP 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 \fBdialog\fP +several times. +Use this option to allow \fBdialog\fP to use those initialization strings. +. +.IP "\fB--keep-window" +Normally when \fBdialog\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, \fBdialog\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--max-input \fIsize" +Limit input strings to the given size. +If not specified, the limit is 2048. +. +.IP "\fB--no-cancel" +.IP "\fB--nocancel" +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 \fBdialog\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 \fBdialog\fR will still wrap text, +subject to the "\fB--cr-wrap\fR" and "\fB--trim\fR" options. +. +.IP "\fB--no-kill" +Tells +\fBdialog\fP +to put the +\fBtailboxbg\fP +box in the background, +printing its process id to \fBdialog\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-ok" +.IP "\fB--nook" +Suppress the "OK" button in checklist, inputbox and menu box modes. +A script can still test if the user pressed the "Enter" key to accept the data. +. +. +.IP "\fB--no-shadow" +Suppress shadows that would be drawn to the right and bottom of each dialog box. +. +.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 \fBdialog\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 \fBdialog\fP's output from +checklists, rather than a newline (for --separate-output) 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 \fBdialog\fP's output. +This may be used alone, without other options. +. +.IP "\fB--print-size" +Prints the size of each dialog box to \fBdialog\fP's output. +. +.IP "\fB--print-version" +Prints \fBdialog\fR's version to \fBdialog\fP's output. +This may be used alone, without other options. +. +.IP "\fB--separate-output" +For checklist widgets, 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 \fBdialog\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--shadow" +Draw a shadow to the right and bottom of each dialog box. +. +.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. +If this option is not set, \fBdialog\fP uses double quotes around each item. +That requires occasional use of backslashes to make the output useful in +shell scripts. +. +.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, \fBdialog\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. +. +.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--timeout \fIsecs" +Timeout (exit with error code) +if no user response within the given number of seconds. +This is overridden if the background "\fB--tailboxbg\fP is used. +A timeout of zero seconds is ignored. +. +.IP "\fB--title \fItitle" +Specifies a +\fItitle\fP +string to be displayed at the top of the dialog box. +. +.IP "\fB--trace \fIfilename" +logs keystrokes to the given file. +Use control/T to log a picture of the current dialog window. +. +.IP "\fB--trim" +eliminate leading blanks, +trim literal newlines and repeated blanks from message text. +. +.IP +See also the "\fB--cr-wrap\fR" and "\fB--no-collapse\fR" options. +. +.IP "\fB--version" +Same as "\fB--print-version\fP". +. +.IP "\fB--visit-items" +Modify the tab-traversal of checklist, radiobox, 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 5 +\fItext\fP +the caption or contents of the box. +.TP 5 +\fIheight\fP +the height of the dialog box. +.TP 5 +\fIwidth\fP +the width of the dialog box. +.PP +Other parameters depend on the box type. +. +. +.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. +. +. +.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. +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 \fBdialog\fP's output. +If the "\fB--separate-output\fP" option is not given, +the strings will be quoted to make it simple for scripts to separate them. +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 \fBdialog\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 \fBdialog\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 +.TP 3 +- +If \fIflen\fR is zero, the corresponding field cannot be altered. +and the contents of the field determine the displayed-length. +.TP 3 +- +If \fIflen\fR is negative, the corresponding field cannot be altered, +and the negated value of \fIflen\fR is used as the displayed-length. +.TP 3 +- +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 \fBdialog\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 \fBdialog\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 \fBdialog\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 \fBdialog\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, \fBdialog\fP +will exit immediately after displaying the message to the user. +The screen is not cleared when \fBdialog\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 \fBdialog\fP's output. +Only an "OK" button is provided for input, +but an ESC exit status may be 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 \fBdialog\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 \fBdialog\fP will write the following on \fBdialog\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 +.IR 1-9 ". 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 \fBdialog\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 dialog(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 \fBdialog\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 +\fBdialog\fP will exit and the calling shell script can continue its operation. +.IP +If the message is too large for the space, +\fBdialog\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 \fBdialog\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 \fBdialog\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--progressbox \fItext height width" +.IP "\fB--progressbox \fIheight width" +A \fBprogressbox\fP is similar to an \fBtailbox\fP, +except that it will exit when it reaches the end of the file. +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 name of the selected item is written to \fBdialog\fP's output. +. +. +.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 \fBdialog\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 +Dialog 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"), +\fBdialog\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, \fBdialog\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 \fBdialog\fP's output. +Only an "EXIT" button is provided for input, +but an ESC exit status may be returned. +.IP +NOTE: +Older versions of \fBdialog\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, 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 \fBdialog\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. +. +. +.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 +.I +"\en" +or newline characters +\fI`\en'\fP +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 \fBdialog\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. +. +.\" ************************************************************************ +.SH "RUN-TIME CONFIGURATION" +.TP 4 +1. +Create a sample configuration file by typing: +.LP +.in +1i +"dialog --create-rc <file>" +.TP 4 +2. +At start, +\fBdialog\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 +\fBdialog\fP +can find, as stated in step 2 above. +. +.\" ************************************************************************ +.SH "KEY BINDINGS" +You can override or add to key bindings in \fBdialog\fP +by adding to the configuration file. +\fBDialog\fP's \fBbindkey\fP command maps single keys to its internal coding. +.EX +bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP +.EE +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 any of the names derived from +\fBcurses.h\fP, e.g., "HELP" from "KEY_HELP". +\fBDialog\fP also recognizes ANSI control characters such as "^A", "^?", +as well as C1-controls such as "~A" and "~?". +Finally, it allows any single character to be escaped with a backslash. +.PP +\fBDialog\fP's internal keycode names correspond to the +\fBDLG_KEYS_ENUM\fP type in +\fBdlg_keys.h\fP, e.g., "HELP" from "DLGK_HELP". +. +.\" ************************************************************************ +.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 \fBdialog\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_OK\fP +Define any of these variables to change the exit code on +Cancel (1), +error (-1), +ESC (255), +Extra (3), +Help (2), +Help with --item-help (2), +or OK (0). +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 \fBdialog\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 EXAMPLES +The \fBdialog\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 DIAGNOSTICS +Exit status is subject to being overridden by environment variables. +Normally they are: +.TP 5 +0 +if +.BR dialog " is exited by pressing the " Yes " or " OK +button. +.TP 5 +1 +if the +.BR No " or " Cancel +button is pressed. +.TP 5 +2 +if the +.BR Help +button is pressed. +.TP 5 +3 +if the +.BR Extra +button is pressed. +.TP 5 +-1 +if errors occur inside \fBdialog\fP +or \fBdialog\fP is exited by pressing the \fIESC\fP key. +. +.\" ************************************************************************ +.SH COMPATIBILITY +You may want to write scripts which run with other \fBdialog\fP "clones". +.SS ORIGINAL DIALOG +First, there is the "original" \fBdialog\fP program to consider (versions +0.3 to 0.9). +It had some misspelled (or inconsistent) options. +The \fBdialog\fP program maps those deprecated options to the preferred ones. +They include: +.RS +.TS +l l +_ _ +l l. +\fIOption\fR \fITreatment\fR +\fB--beep-after\fP ignored +\fB--guage\fP mapped to \fB--gauge\fP +.TE +.RE +.SS XDIALOG +Technically, "\fBXdialog\fP", +this is an X application. +With some care, it is possible to write useful scripts that work +with both \fBXdialog\fP and \fBdialog\fP. +.PP +The \fBdialog\fP program ignores these options which are recognized +by \fBXdialog\fP: +.RS +.TS +l l +_ _ +l l. +\fIOption\fR \fITreatment\fR +\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 \fBdialog\fP. +.SS WHIPTAIL +Then there is \fBwhiptail\fP. +For practical purposes, it is maintained by Debian. +Its documentation claims +.RS +.sp +.nf +whiptail(1) is a lightweight replacement for dialog(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 enviroments such as installers, +rescue disks, etc. +.sp +whiptail is designed to be drop-in compatible with dialog, but +has less features: some dialog boxes are not implemented, such +as tailbox, timebox, calendarbox, etc. +.fi +.RE +.PP +Comparing actual sizes (Debian testing, 2007/1/10): +The total of sizes for \fBwhiptail\fP, the newt, popt and slang libraries is 757kb. +The comparable number for \fBdialog\fP (counting ncurses) is 520kb. +Disregard the first paragraph. +.PP +The second paragraph is misleading, since \fBwhiptail\fP +also does not work for common options of dialog, such as the gauge box. +\fBwhiptail\fP is less compatible with \fBdialog\fP than the decade-old +original dialog 0.4 program. +.PP +\fBwhiptail\fP's manpage borrows features from \fBdialog\fP, e.g., +\fB--default-item\fP, \fB--output-fd\fP, +but oddly cites only \fBdialog\fP versions up to 0.4 as a source. +That is, its manpage refers to features which +were borrowed from more recent versions of \fBdialog\fP, e.g., +the \fB--gauge\fP and \fB--password\fP boxes, +as well as options such as \fB-separate-output\fP. +Somewhat humorously, one may note that the \fBpopt\fP feature +(undocumented in its manpage) +of using a "--" as an escape was documented in \fBdialog\fP's manpage about +a year before it was mentioned in \fBwhiptail\fP's manpage. +\fBwhiptail\fP's manpage incorrectly attributes that to \fBgetopt\fP +(and is inaccurate anyway). +.PP +Debian uses \fBwhiptail\fP for the official \fBdialog\fP variation. +.PP +The \fBdialog\fP program ignores or maps these options which are recognized +by \fBwhiptail\fP: +.RS +.TS +l l +_ _ +l l. +\fIOption\fR \fITreatment\fR +\fB--fb\fP ignored +\fB--fullbutton\fP ignored +\fB--nocancel\fP mapped to \fB--no-cancel\fP +\fB--noitem\fP ignored +.TE +.RE +.\" ************************************************************************ +.SH BUGS +Perhaps. +.SH AUTHOR +.LP +Thomas E. Dickey (updates for 0.9b and beyond) +.SH CONTRIBUTORS +Kiran Cherupally - the mixed form and mixed gauge widgets. +.LP +Tobias C. Rittweiler +.LP +Valery Reznic - 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 \fBdialog 0.9a\fP, +which lists as authors: +.RS +.LP +Savio Lam - version 0.3, "dialog" +.LP +Stuart Herbert - patch for version 0.4 +.LP +Marc Ewing - the gauge widget. +.LP +Pasquale De Marco "Pako" - version 0.9a, "cdialog" +.RE |