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