diff options
Diffstat (limited to 'contrib/dialog/dialog.1')
| -rw-r--r-- | contrib/dialog/dialog.1 | 217 |
1 files changed, 44 insertions, 173 deletions
diff --git a/contrib/dialog/dialog.1 b/contrib/dialog/dialog.1 index 89f4918..8fd4de1 100644 --- a/contrib/dialog/dialog.1 +++ b/contrib/dialog/dialog.1 @@ -1,6 +1,6 @@ '\" t -.\" $Id: dialog.1,v 1.145 2012/07/03 08:32:33 tom Exp $ -.\" Copyright 2005-2011,2012 Thomas E. Dickey +.\" $Id: dialog.1,v 1.133 2011/06/29 09:39:29 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 @@ -27,17 +27,16 @@ .ne 8 .IP .. -.de Ex -.RS +7 -.PP +.de EX +.RS +10 .nf .. -.de Ee +.de EE .fi .RE .. . -.TH \*D 1 "" "$Date: 2012/07/03 08:32:33 $" +.TH \*D 1 "" "$Date: 2011/06/29 09:39:29 $" .SH NAME \*p \- display dialog boxes from shell scripts .SH SYNOPSIS @@ -173,39 +172,39 @@ To compare the effects, use these: . .ES All three widgets visible, staircase effect, ordered 1,2,3: -.Ex -\*p \\ +.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 +.EE . .ES Only the last widget is left visible: -.Ex -\*p \\ +.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 +.EE . .ES All three widgets visible, staircase effect, ordered 3,2,1: -.Ex -\*p \\ +.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 +.EE . .ES First and third widget visible, staircase effect, ordered 3,1: -.Ex -\*p \\ +.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 +.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) @@ -238,7 +237,6 @@ 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 @@ -272,25 +270,6 @@ 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-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--nook\fP" and "\fB--nocancel\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. @@ -359,14 +338,13 @@ 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, +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. +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 @@ -455,11 +433,6 @@ Prints \fB\*p\fR's version to \fB\*p\fP's output. This may be used alone, without other options. It does not cause \fBdialog\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. -. .IP "\fB--scrollbar" For widgets holding a scrollable set of data, draw a scrollbar on its right-margin. @@ -483,8 +456,8 @@ Draw a shadow to the right and bottom of each dialog box. 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. -In either case, -\fB\*p\fP adds backslashes to make the output useful in shell scripts. +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, @@ -528,11 +501,8 @@ 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 -This option is ignored by the "\fB--pause\fP" widget. -It is also overridden if the background "\fB--tailboxbg\fP" option is used -to setup multiple concurrent widgets. . .IP "\fB--title \fItitle" Specifies a @@ -540,16 +510,11 @@ Specifies a 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. +logs the command-line parameters and +keystrokes to the given file. If \fBdialog\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. -.PP -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--trim" eliminate leading blanks, @@ -624,10 +589,8 @@ The initial on/off state of each entry is specified by 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. +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. . . @@ -658,7 +621,7 @@ 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 +You may edit it using the \fIbackspace\fP, \fIdelete\fP and cursor keys to correct typing errors. It also recognizes pageup/pagedown. @@ -884,7 +847,7 @@ 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" +.IP "\fB\-\-pause \fItext height width seconds\fR" A \fBpause\fP box displays a meter along the bottom of the box. @@ -936,8 +899,7 @@ If only two parameters are given, this text is omitted. .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). +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 @@ -951,16 +913,7 @@ 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 +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. @@ -1141,10 +1094,9 @@ can find, as stated in step 2 above. 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 +.EX bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP -.Ee -.PP +.EE The \fIwidget\fP name can be "*" (all widgets), or specific widgets such as \fBtextbox\fP. Specific widget bindings override the "*" bindings. @@ -1159,82 +1111,6 @@ Finally, it allows any single character to be escaped with a backslash. \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 -.PP -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. -.TS -center tab(/) ; -l l l -l l l . -\fIWidget\fR/\fIWindow name\fR/\fISubwindow Name\fR -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 -.PP -Some widgets are actually other widgets, -using internal settings to modify the behavior. -Those use the same widget name as the actual widget: -.TS -center tab(/) ; -l l -l l . -\fIWidget\fR/\fIActual Widget\fR -dselect/fselect -infobox/msgbox -inputmenu/menu -mixedform/form -passwordbox/inputbox -passwordform/form -prgbox/progressbox -programbox/progressbox -tailboxbg/tailbox -.TE -.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. -.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 <code>dlgk_keys.h</code> -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 ENVIRONMENT @@ -1273,7 +1149,7 @@ error (-1), ESC (255), Extra (3), Help (2), -Help with \fB--item-help\fP (2), +Help with --item-help (2), or OK (0). Normally shell scripts cannot distinguish between -1 and 255. .TP 15 @@ -1291,39 +1167,35 @@ 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. -The default values and corresponding environment variables -that can override them are: +Normally they are: .TP 5 0 if .BR \*p " is exited by pressing the " Yes " or " OK -button (DIALOG_OK). +button. .TP 5 1 if the .BR No " or " Cancel -button is pressed (DIALOG_CANCEL). +button is pressed. .TP 5 2 if the .BR Help -button is pressed (DIALOG_HELP). +button is pressed. .TP 5 3 if the .BR Extra -button is pressed (DIALOG_EXTRA). -.TP 5 +button is pressed. 4 if the -.BR Help -button is pressed (DIALOG_HELP), -or the \fB--item-help\fP option is set -when the \fBHelp\fP button is pressed (DIALOG_ITEM_HELP), +.BR Item Help +button is pressed. .TP 5 -1 -if errors occur inside \fB\*p\fP (DIALOG_ERROR) -or \fB\*p\fP is exited by pressing the \fIESC\fP key (DIALOG_ESC). +if errors occur inside \fB\*p\fP +or \fB\*p\fP is exited by pressing the \fIESC\fP key. . .\" ************************************************************************ .SH PORTABILITY @@ -1398,8 +1270,7 @@ Its documentation claims .sp .nf whiptail(1) is a lightweight replacement for \*p(1), -to provide dialog boxes for shell scripts. -It is built on the +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. @@ -1427,7 +1298,7 @@ but oddly cites only \fB\*p\fP versions up to 0.4 (1996) 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 (2008). +as well as options such as \fB-separate-output\fP (2008). 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 |
