gnu/usr.bin/dialog/dialog.1

   1 .TH DIALOG 1 "2 October 1998"
   2 .SH NAME
   3 dialog \- display dialog boxes from shell scripts
   4 .SH SYNOPSIS
   5 .B dialog --clear
   6 .br
   7 .BI "dialog --create-rc " file
   8 .br
   9 .B dialog
  10 [
  11 .BI "\-\-title " title
  12 ]
  13 [
  14 .B \-\-clear
  15 ]
  16 [
  17 .BI "\-\-hline " line
  18 ]
  19 [
  20 .BI "\-\-hfile " file
  21 ]
  22 .B box-options
  23 .SH DESCRIPTION
  24 .B Dialog
  25 is a program which allows you to present a variety of questions or
  26 display messages in dialog box form from a shell script.  The following
  27 types of dialog objects are currently supported:
  28 .LP
  29 .BR yes/no " box," " menu" " box," " input" " box,"
  30 .BR message " box," " text" " box," " info" " box,"
  31 .BR checklist " box," " program" " box,"
  32 .BR ftree " and " tree " boxes."
  33 .SH OPTIONS
  34 .TP
  35 .B \-\-clear
  36 The screen will be cleared to the
  37 .BR "screen attribute" " on exit."
  38 .TP
  39 .BI \-\-create-rc " file"
  40 .RB "Since " dialog " supports run-time configuration,"
  41 this can be used to dump a sample configuration file to the file specified
  42 by
  43 .IR file "."
  44 .TP
  45 .BI \-\-title " title"
  46 Specifies a
  47 .I title
  48 string to be displayed at the top of the dialog box.
  49 .TP
  50 .BI \-\-hline " line"
  51 Specifies a
  52 .I line
  53 string to be displayed at the bottom of the dialog box.
  54 .TP
  55 .BI \-\-hfile " file"
  56 Specifies a
  57 .I file
  58 to be displayed by pressing ? or F1.
  59 .TP
  60 .B Box Options
  61 .TP
  62 .BI \-\-yesno " text height width"
  63 .RB A " yes/no" " dialog box of size"
  64 .I height
  65 rows by
  66 .I width
  67 columns will be displayed. The string specified by
  68 .I text
  69 is displayed inside the dialog box. If this string is too long to fit
  70 in one line, it will be automatically divided into multiple lines at
  71 the appropriate points. The
  72 .I text
  73 string may also contain the sub-string
  74 .I
  75 "\en"
  76 or newline characters
  77 .I `\en\'
  78 to control line breaking explicitly.  This dialog box is useful for
  79 asking questions that require the user to answer either yes or no.
  80 .RB "The dialog box has a" " Yes" " button and a " No
  81 button, in which the user can switch between by pressing the
  82 .IR TAB " key."
  83 .TP
  84 .BI \-\-msgbox " text height width"
  85 .RB A " message" " box is very similar to a" " yes/no" " box."
  86 The only difference between a
  87 .B message
  88 box and a
  89 .B yes/no
  90 box is that a
  91 .B message
  92 box has only a single
  93 .B OK
  94 button. You can use this dialog box to display any message you like.
  95 After reading the message, the user can press the
  96 .I ENTER
  97 key so that
  98 .B dialog
  99 will exit and the calling shell script can continue its operation.
 100 .TP
 101 .BI \-\-infobox " text height width"
 102 .RB An " info" " box is basically a" " message" " box."
 103 However, in this case,
 104 .B dialog
 105 will exit immediately after displaying the message to the user. The
 106 screen is not cleared when
 107 .B dialog
 108 exits, so that the message will remain on the screen until the calling
 109 shell script clears it later. This is useful when you want to inform
 110 the user that some operations are carrying on that may require some
 111 time to finish.
 112 .TP
 113 .BI \-\-inputbox " text height width"
 114 .RB "An " input " box is useful when you want to ask questions that"
 115 require the user to input a string as the answer. When inputing the
 116 string, the
 117 .I BACKSPACE
 118 key can be used to correct typing errors. If the input string is longer than
 119 can be fitted in the dialog box, the input field will be scrolled. On exit,
 120 the input string will be printed on
 121 .IR stderr "."
 122 .TP
 123 .BI \-\-textbox " file height width"
 124 .RB A " text" " box lets you display the contents of a text file in a"
 125 dialog box. It is like a simple text file viewer. The user can move
 126 through the file by using the
 127 .IR UP/DOWN ", " PGUP/PGDN
 128 .RI and " HOME/END" " keys available on most keyboards."
 129 If the lines are too long to be displayed in the box, the
 130 .I LEFT/RIGHT
 131 keys can be used to scroll the text region horizontally. For more
 132 convenience, forward and backward searching functions are also provided.
 133 .IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
 134 As its name suggests, a
 135 .B menu
 136 box is a dialog box that can be used to present a list of choices in
 137 the form of a menu for the user to choose. Each menu entry consists of a
 138 .IR tag " string and an " item " string. The"
 139 .I tag
 140 gives the entry a name to distinguish it from the other entries in the
 141 menu. The
 142 .I item
 143 is a short description of the option that the entry represents. The
 144 user can move between the menu entries by pressing the
 145 .I UP/DOWN
 146 keys, the first letter of the
 147 .I tag
 148 as a hot-key, or the number keys
 149 .IR 1-9 ". There are"
 150 .I menu-height
 151 entries displayed in the menu at one time, but the menu will be
 152 scrolled if there are more entries than that. When
 153 .B dialog
 154 exits, the
 155 .I tag
 156 of the chosen menu entry will be printed on
 157 .IR stderr "."
 158 .TP
 159 .BI \-\-prgbox " command height width"
 160 .RB A " program" " box lets you display output of command in"
 161 dialog box.
 162 .IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
 163 .RB "A " checklist " box is similar to a " menu " box in that there are"
 164 multiple entries presented in the form of a menu. Instead of choosing
 165 one entry among the entries, each entry can be turned on or off by the
 166 user. The initial on/off state of each entry is specified by
 167 .IR status "."
 168 On exit, a list of the
 169 .I tag
 170 strings of those entries that are turned on will be printed on
 171 .IR stderr "."
 172 .IP "\fB\-\-ftree \fIfile FS text height width menu-height"
 173 .B ftree
 174 box is a dialog box showing the tree described by the data from the file
 175 .IR file "."
 176 The data in the file should look like find(1)  output. For the
 177 find output, the field separator
 178 .I FS
 179 will be
 180 .IR \'/\' ". If"
 181 .IR height " and"
 182 .IR width " are"
 183 positive numbers, they set the absolute size of the whole
 184 .BR ftree " box. If"
 185 .IR height " and"
 186 .IR width " are negative numbers, the size of the"
 187 .B ftree
 188 box will be
 189 selected automatically.
 190 .I menu-height
 191 sets the height of the tree subwindow inside the
 192 .B ftree
 193 box and must be set.
 194 .I text
 195 is shown inside the
 196 .B ftree
 197 box above the tree subwindow and can contain newline characters
 198 .I '\en\'
 199 to split lines. One can navigate in the tree by pressing
 200 .IR UP/DOWN " or " \'+\'/\'-\' ", " PG_UP/PG_DOWN " or " \'b\'/SPACE
 201 .RI "and " HOME/END " or " \'g\'/\'G\' "."
 202 A leaf of the tree is selected by pressing
 203 .IR TAB " or " LEFT/RIGHT
 204 the
 205 .B OK
 206 button and pressing
 207 .IR ENTER "."
 208 The selected leaf (to be more
 209 exact, the full path to it from the root of the tree) is printed to
 210 .IR stderr "."
 211 If
 212 .B Cancel
 213 and then
 214 .I ENTER
 215 is pressed, nothing is printed to
 216 .IR stderr "."
 217 .I file
 218 may contain data like find(1)
 219 output, as well as like the output of find(1) with
 220 .I -d
 221 option. Some of the transient paths to the leaves of the tree may be
 222 absent. Such data is corrected when fed from file.
 223 .IP "\fB\-\-tree \fIFS text height width menu-height \fR[ \fIitem \fR] \fI..."
 224 .B tree
 225 box is like
 226 .B ftree
 227 box with some exceptions. First, the data is not
 228 entered from a file, but from the command line as
 229 .I item item ...
 230 Second, the data thus entered is not corrected in any way.
 231 Thus, the data like the output of find(1) with
 232 .I -d
 233 option will look incorrectly.
 234 .SH "RUN-TIME CONFIGURATION"
 235 .TP 4
 236 1.
 237 Create a sample configuration file by typing:
 238 .LP
 239 .in +1i
 240 "dialog --create-rc <file>"
 241 .TP 4
 242 2.
 243 At start,
 244 .B dialog
 245 determines the settings to use as follows:
 246 .RS
 247 .TP 4
 248 a)
 249 if environment variable
 250 .B DIALOGRC
 251 is set, its value determines the name of the configuration file.
 252 .TP 4
 253 b)
 254 if the file in (a) can't be found, use the file
 255 .I $HOME/.dialogrc
 256 as the configuration file.
 257 .TP 4
 258 c)
 259 if the file in (b) can't be found, use compiled in defaults.
 260 .RE
 261 .TP 4
 262 3.
 263 Edit the sample configuration file and copy it to some place that
 264 .B dialog
 265 can find, as stated in step 2 above.
 266 .SH ENVIRONMENT
 267 .TP 15
 268 .B DIALOGRC
 269 Define this variable if you want to specify the name of the configuration file
 270 to use.
 271 .SH FILES
 272 .TP 20
 273 .I $HOME/.dialogrc
 274 default configuration file
 275 .SH DIAGNOSTICS
 276 Exit status is 0 if
 277 .BR dialog " is exited by pressing the " Yes " or " OK
 278 button, and 1 if the
 279 .BR No " or " Cancel
 280 button is pressed. Otherwise, if errors occur inside
 281 .B dialog
 282 or
 283 .B dialog
 284 is exited by pressing the
 285 .I ESC
 286 key, the exit status is -1.
 287 .SH SEE ALSO
 288 dialog(3)
 289 .SH BUGS
 290 Text files containing
 291 .I tab
 292 characters may cause problems with
 293 .B text
 294 box.
 295 .I Tab
 296 characters in text files must first be expanded to spaces before being
 297 .RB "displayed by " text " box."
 298 .sp 1
 299 Screen update is too slow.
 300 .sp 1
 301 The
 302 .B ftree
 303 and
 304 .B tree
 305 boxes do not allow the tree to be moved to the left or to
 306 the right. Thus, if there are many levels of data, some of the leaves can be
 307 rendered invisible. A standard display with 80 characters allows for 17
 308 levels to be visible. Deeper levels are invisible. However, the navigation
 309 in the tree and selection of leaves do work.
 310 .SH AUTHOR
 311 Savio Lam (lam836@cs.cuhk.hk)
 312 .sp 1
 313 Changes by Anatoly A. Orehovsky (tolik@mpeks.tomsk.su) (ftree and tree boxes)