diff options
Diffstat (limited to 'Master/texmf/doc/man/man1/tcdialog.1')
-rw-r--r-- | Master/texmf/doc/man/man1/tcdialog.1 | 1337 |
1 files changed, 0 insertions, 1337 deletions
diff --git a/Master/texmf/doc/man/man1/tcdialog.1 b/Master/texmf/doc/man/man1/tcdialog.1 deleted file mode 100644 index fc993116880..00000000000 --- a/Master/texmf/doc/man/man1/tcdialog.1 +++ /dev/null @@ -1,1337 +0,0 @@ -'\" t -.\" $Id: dialog.1,v 1.126 2011/03/02 01:24:21 tom Exp $ -.\" Copyright 2005-2010,2011 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 -.\" -.de ES -.ne 8 -.IP -.. -.de EX -.RS +10 -.nf -.. -.de EE -.fi -.RE -.. -. -.TH \*D 1 "" "$Date: 2011/03/02 01:24:21 $" -.SH NAME -\*p \- 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 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 \fB\*p\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 prgbox ", " -.BR programbox ", " -.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 \fB\*p\fP 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. -\*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. -.RS -.B \*p --title -- --Not an option -.RE -.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 -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. -. -.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 -\*p \ - --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 -\*p \ - --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 -\*p \ - --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 -\*p \ - --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 \fB\*p\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 \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. -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 -See also the "\fB--no-collapse\fP" and "\fB--trim\fP" options. -. -.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--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, 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 \fB\*p\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 \fB\*p\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 \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--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 \fB\*p\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 \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--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 \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 "\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-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 \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 --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 \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. -. -.IP "\fB--print-version" -Prints \fB\*p\fR's version to \fB\*p\fP's output. -This may be used alone, without other options. -. -.IP "\fB--scrollbar \fIstring" -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 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 \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--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, \fB\*p\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, \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. -. -.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 (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 the command-line parameters and -keystrokes to the given file. -If \fBdialog\fP reads a configure file, it is logged as well. -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. -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. -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 \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 -.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 \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. -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 \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 -.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 \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 -\fBdialog\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--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. -.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 -\fBdialog\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 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 \fB\*p\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 \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, 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--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 \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. -. -.\" ************************************************************************ -.SH "RUN-TIME CONFIGURATION" -.TP 4 -1. -Create a sample configuration file by typing: -.LP -.in +1i -"\*p --create-rc <file>" -.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 -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". -\fB\*L\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 -\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". -. -.\" ************************************************************************ -.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_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 \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 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 DIAGNOSTICS -Exit status is subject to being overridden by environment variables. -Normally they are: -.TP 5 -0 -if -.BR \*p " 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. -4 -if the -.BR Item Help -button is pressed. -.TP 5 --1 -if errors occur inside \fB\*p\fP -or \fB\*p\fP is exited by pressing the \fIESC\fP key. -. -.\" ************************************************************************ -.SH PORTABILITY -\fB\*L\fP works with X/Open curses. -However, some implementations have deficiencies: -.RS 3 -.TP 3 -- -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. -.TP 3 -- -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 \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 \fB\*p\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 \fB\*p\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 \fB\*p\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 \*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 enviroments such as installers, -rescue disks, etc. -.sp -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. -.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 \fB\*p\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 \*p, such as the gauge box. -\fBwhiptail\fP is less compatible with \fB\*p\fP than the decade-old -original dialog 0.4 program. -.PP -\fBwhiptail\fP's manpage borrows features from \fB\*p\fP, e.g., -\fB--default-item\fP, \fB--output-fd\fP, -but oddly cites only \fB\*p\fP versions up to 0.4 as a source. -That is, its manpage refers to features which -were borrowed from more recent versions of \fB\*p\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 \fB\*p\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 \fB\*p\fP variation. -.PP -The \fB\*p\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 \fB\*p 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 |