gnu/usr.bin/dialog/dialog.1

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