1DIALOG(1)                   General Commands Manual                  DIALOG(1)
2
3
4

NAME

6       dialog - display dialog boxes from shell scripts
7

SYNOPSIS

9       dialog --clear
10       dialog --create-rc file
11       dialog --print-maxsize
12       dialog common-options box-options
13

DESCRIPTION

15       Dialog is a program that will let you present a variety of questions or
16       display messages using dialog boxes from a shell script.   These  types
17       of  dialog  boxes  are implemented (though not all are necessarily com‐
18       piled into dialog):
19
20              buildlist, calendar, checklist, dselect, editbox, form, fselect,
21              gauge, infobox, inputbox, inputmenu, menu, mixedform,
22              mixedgauge, msgbox (message), passwordbox, passwordform, pause,
23              prgbox, programbox, progressbox, radiolist, rangebox, tailbox,
24              tailboxbg, textbox, timebox, treeview, and yesno (yes/no).
25
26       You can put more than one dialog box into a script:
27
28       ·   Use the "--and-widget" token to force dialog to proceed to the next
29           dialog unless you have pressed ESC to cancel, or
30
31       ·   Simply add the tokens for the next dialog box, making a chain.  Di‐
32           alog stops chaining when the return code from a dialog is  nonzero,
33           e.g., Cancel or No (see DIAGNOSTICS).
34
35       Some  widgets,  e.g.,  checklist,  will  write text to dialog's output.
36       Normally that is the standard error, but there are options for changing
37       this:  “--output-fd”, “--stderr” and “--stdout”.  No text is written if
38       the Cancel button (or ESC) is pressed; dialog exits immediately in that
39       case.
40

OPTIONS

42       All  options  begin  with  “--”  (two ASCII hyphens, for the benefit of
43       those using systems with deranged locale support).
44
45       A “--” by itself is used as an escape, i.e., the next token on the com‐
46       mand-line is not treated as an option.
47              dialog --title -- --Not an option
48
49       The “--args” option tells dialog to list the command-line parameters to
50       the standard error.  This is useful when debugging complex scripts  us‐
51       ing  the  “--” and “--file”, since the command-line may be rewritten as
52       these are expanded.
53
54       The “--file” option tells dialog to read parameters from the file named
55       as its value.
56              dialog --file parameterfile
57
58       Blanks not within double-quotes are discarded (use backslashes to quote
59       single characters).  The result is inserted into the command-line,  re‐
60       placing  “--file” and its option value.  Interpretation of the command-
61       line resumes from that point.  If parameterfile begins with “&”, dialog
62       interprets the following text as a file descriptor number rather than a
63       filename.
64
65       Most widgets accept height and width parameters, which can be  used  to
66       automatically  size the widget to accommodate multi-line message prompt
67       values:
68
69       ·   If the parameter is negative, dialog uses the screen's size.
70
71       ·   If the parameter is zero, dialog uses minimum size for  the  widget
72           to display the prompt and data.
73
74       ·   Otherwise, dialog uses the given size for the widget.
75
76   Common Options
77       Most of the common options are reset before processing each widget.
78
79       --ascii-lines
80              Rather than draw graphics lines around boxes, draw ASCII “+” and
81              “-” in the same place.  See also “--no-lines”.
82
83       --aspect ratio
84              This gives you some control over the box dimensions  when  using
85              auto  sizing (specifying 0 for height and width).  It represents
86              width / height.  The default is 9, which means 9 characters wide
87              to every 1 line high.
88
89       --backtitle backtitle
90              Specifies a backtitle string to be displayed on the backdrop, at
91              the top of the screen.
92
93       --begin y x
94              Specify the position of the upper left corner of a dialog box on
95              the screen.
96
97       --cancel-label string
98              Override the label used for “Cancel” buttons.
99
100       --clear
101              Clears  the  widget  screen, keeping only the screen_color back‐
102              ground.  Use this when you combine widgets  with  “--and-widget
103              to  erase the contents of a previous widget on the screen, so it
104              won't be seen under the contents of a following widget.   Under‐
105              stand this as the complement of “--keep-window”.  To compare the
106              effects, use these:
107
108              All three widgets visible, staircase effect, ordered 1,2,3:
109
110              dialog \
111                                             --begin 2 2 --yesno "" 0 0 \
112                  --and-widget               --begin 4 4 --yesno "" 0 0 \
113                  --and-widget               --begin 6 6 --yesno "" 0 0
114
115              Only the last widget is left visible:
116
117              dialog \
118                               --clear       --begin 2 2 --yesno "" 0 0 \
119                  --and-widget --clear       --begin 4 4 --yesno "" 0 0 \
120                  --and-widget               --begin 6 6 --yesno "" 0 0
121
122              All three widgets visible, staircase effect, ordered 3,2,1:
123
124              dialog \
125                               --keep-window --begin 2 2 --yesno "" 0 0 \
126                  --and-widget --keep-window --begin 4 4 --yesno "" 0 0 \
127                  --and-widget               --begin 6 6 --yesno "" 0 0
128
129              First and third widget visible, staircase effect, ordered 3,1:
130
131              dialog \
132                               --keep-window --begin 2 2 --yesno "" 0 0 \
133                  --and-widget --clear       --begin 4 4 --yesno "" 0 0 \
134                  --and-widget               --begin 6 6 --yesno "" 0 0
135
136              Note, if you want to restore original console  colors  and  send
137              your  cursor  home  after the dialog program has exited, use the
138              clear (1) command.
139
140       --colors
141              Interpret embedded “\Z” sequences in the dialog text by the fol‐
142              lowing  character, which tells dialog to set colors or video at‐
143              tributes:
144
145              ·   0 through 7 are the  ANSI  color  numbers  used  in  curses:
146                  black, red, green, yellow, blue, magenta, cyan and white re‐
147                  spectively.
148
149              ·   Bold is set by 'b', reset by 'B'.
150
151              ·   Reverse is set by 'r', reset by 'R'.
152
153              ·   Underline is set by 'u', reset by 'U'.
154
155              ·   The settings are cumulative, e.g., “\Zb\Z1” makes  the  fol‐
156                  lowing text bold (perhaps bright) red.
157
158              ·   Restore normal settings with “\Zn”.
159
160       --column-separator string
161              Tell  dialog to split data for radio/checkboxes and menus on the
162              occurrences of the given string, and to align the split data in‐
163              to columns.
164
165       --cr-wrap
166              Interpret  embedded  newlines in the dialog text as a newline on
167              the screen.  Otherwise, dialog will only wrap lines where needed
168              to fit inside the text box.
169
170              Even  though  you can control line breaks with this, Dialog will
171              still wrap any lines that are too long for the width of the box.
172              Without  cr-wrap,  the  layout  of your text may be formatted to
173              look nice in the source code of your  script  without  affecting
174              the way it will look in the dialog.
175
176              The cr-wrap feature is implemented subject to these conditions:
177
178              ·   the  string  contains  “\n” and the --no-nl-expand option is
179                  not used, or
180
181              ·   the --trim option is used.
182
183              For more information, see Whitespace Options.
184
185       --create-rc file
186              When dialog supports run-time configuration, this can be used to
187              dump a sample configuration file to the file specified by file.
188
189       --date-format format
190              If the host provides strftime, this option allows you to specify
191              the format of the date printed for the --calendar  widget.   The
192              time of day (hour, minute, second) are the current local time.
193
194       --defaultno
195              Make  the default value of the yes/no box a No.  Likewise, treat
196              the default button of widgets that provide “OK” and “Cancel”  as
197              a  Cancel.   If  “--nocancel” or “--visit-items” are given those
198              options overrides this, making the default button  always  “Yes”
199              (internally the same as “OK”).
200
201       --default-button string
202              Set the default (preselected) button in a widget.  By preselect‐
203              ing a button, a script makes it possible for the user to  simply
204              press  Enter  to  proceed through a dialog with minimum interac‐
205              tion.
206
207              The option's value is the name of the button: ok,  yes,  cancel,
208              no, help or extra.
209
210              Normally  the  first  button in each widget is the default.  The
211              first button shown is determined by the widget together with the
212--nook” and “--nocancel” options.  If this option is not given,
213              there is no default button assigned.
214
215       --default-item string
216              Set the default item in a checklist, form or menu box.  Normally
217              the first item in the box is the default.
218
219       --exit-label string
220              Override the label used for “EXIT” buttons.
221
222       --extra-button
223              Show an extra button, between “OK” and “Cancel” buttons.
224
225       --extra-label string
226              Override  the  label used for “Extra” buttons.  Note: for input‐
227              menu widgets, this defaults to “Rename”.
228
229       --help Prints the help message to the standard output and  exits.   The
230              help  message  is also printed if no options are given, or if an
231              unrecognized option is given.
232
233       --help-button
234              Show a help-button after “OK”  and  “Cancel”  buttons  in  boxes
235              which  have  a list of tagged items (i.e., checklist, radiolist,
236              menu, and treeview boxes).
237
238              On exit, the return status indicates that the  Help  button  was
239              pressed.   Dialog  also writes a message to its output after the
240              token “HELP”:
241
242              ·   If "--item-help" is also given, the item-help text is  writ‐
243                  ten.
244
245              ·   Otherwise, the item's tag (the first field) is written.
246
247              You   can  use  the  --help-tags  option  and/or  set  the  DIA‐
248              LOG_ITEM_HELP environment variable to modify these messages  and
249              exit-status.
250
251              This  option can be applied to other widgets, which have an “OK”
252              button, whether or not the “Cancel” button is used.  The  return
253              status  and  output are not treated specially for the other wid‐
254              gets; the help-button is just an extra button.
255
256       --help-label string
257              Override the label used for “Help” buttons.
258
259       --help-status
260              If the help-button is selected, writes the checklist,  radiolist
261              or  form  information  after  the  item-help “HELP” information.
262              This can be used to reconstruct the state of a  checklist  after
263              processing the help request.
264
265       --help-tags
266              Modify  the messages written on exit for --help-button by making
267              them always just the item's tag.  This does not affect the  exit
268              status code.
269
270       --hfile filename
271              Display the given file using a textbox when the user presses F1.
272
273       --hline string
274              Display the given string centered at the bottom of the widget.
275
276       --ignore
277              Ignore  options that dialog does not recognize.  Some well-known
278              ones such as “--icon” are ignored anyway, but this is  a  better
279              choice for compatibility with other implementations.
280
281       --input-fd fd
282              Read keyboard input from the given file descriptor.  Most dialog
283              scripts read from the standard input, but the gauge widget reads
284              a pipe (which is always standard input).  Some configurations do
285              not work properly when dialog tries to reopen the terminal.  Use
286              this  option  (with appropriate juggling of file-descriptors) if
287              your script must work in that type of environment.
288
289       --insecure
290              Makes the password widget friendlier but less secure, by echoing
291              asterisks for each character.
292
293       --iso-week
294              Set  the starting point for the week-number shown in the “--cal‐
295              endar” option according to ISO-8601, which starts numbering with
296              the first week which includes a Thursday in January.
297
298       --item-help
299              Interpret  the tags data for checklist, radiolist and menu boxes
300              adding a column which is displayed in the  bottom  line  of  the
301              screen, for the currently selected item.
302
303       --keep-tite
304              When  built with ncurses, dialog normally checks to see if it is
305              running in an xterm, and in that case tries to suppress the ini‐
306              tialization  strings  that would make it switch to the alternate
307              screen.  Switching between the normal and alternate  screens  is
308              visually  distracting  in  a  script  which  runs dialog several
309              times.  Use this option to allow dialog to use those initializa‐
310              tion strings.
311
312       --keep-window
313              Normally when dialog performs several tailboxbg widgets connect‐
314              ed by “--and-widget”, it clears the old widget from  the  screen
315              by  painting over it.  Use this option to suppress that repaint‐
316              ing.
317
318              At exit, dialog repaints all of  the  widgets  which  have  been
319              marked with “--keep-window”, even if they are not tailboxbg wid‐
320              gets.  That causes them to be repainted in reverse  order.   See
321              the discussion of the “--clear” option for examples.
322
323       --last-key
324              At  exit,  report  the last key which the user entered.  This is
325              the curses key code rather than a symbol or  literal  character,
326              and  is only reported for keys which are bound to an action.  It
327              can be used by scripts to distinguish between two keys which are
328              bound to the same action.
329
330       --max-input size
331              Limit  input  strings  to the given size.  If not specified, the
332              limit is 2048.
333
334       --no-cancel
335
336       --nocancel
337              Suppress the “Cancel” button in checklist, inputbox and menu box
338              modes.   A script can still test if the user pressed the ESC key
339              to cancel to quit.
340
341       --no-collapse
342              Normally dialog converts tabs to  spaces  and  reduces  multiple
343              spaces  to  a single space for text which is displayed in a mes‐
344              sage boxes, etc.  Use this option to disable that feature.  Note
345              that dialog will still wrap text, subject to the “--cr-wrap” and
346--trim” options.
347
348              The no-collapse feature is implemented subject to  these  condi‐
349              tions:
350
351              ·   the  string  contains  “\n” and the --no-nl-expand option is
352                  not used, or
353
354              ·   the --trim option is not used.
355
356              For more information, see Whitespace Options.
357
358       --no-items
359              Some widgets (checklist, inputmenu, radiolist, menu)  display  a
360              list with two columns (a “tag” and “item”, i.e., “description”).
361              This option tells dialog to  read  shorter  rows,  omitting  the
362              “item”  part of the list.  This is occasionally useful, e.g., if
363              the tags provide enough information.
364
365              See also --no-tags.  If both options are given, this one is  ig‐
366              nored.
367
368       --no-kill
369              Tells  dialog to put the tailboxbg box in the background, print‐
370              ing its process id to dialog's output.  SIGHUP is  disabled  for
371              the background process.
372
373       --no-label string
374              Override the label used for “No” buttons.
375
376       --no-lines
377              Rather  than  draw  lines  around boxes, draw spaces in the same
378              place.  See also “--ascii-lines”.
379
380       --no-mouse
381              Do not enable the mouse.
382
383       --no-nl-expand
384              Do not convert “\n” substrings of the message/prompt  text  into
385              literal newlines.
386
387              The  no-nl-expand  feature  is  used only if the string contains
388              “\n” so that there is something to convert.
389
390              For more information, see Whitespace Options.
391
392       --no-ok
393
394       --nook Suppress the “OK” button in checklist,  inputbox  and  menu  box
395              modes.   A script can still test if the user pressed the “Enter”
396              key to accept the data.
397
398       --no-shadow
399              Suppress shadows that would be drawn to the right and bottom  of
400              each dialog box.
401
402       --no-tags
403              Some  widgets  (checklist, inputmenu, radiolist, menu) display a
404              list with two columns (a “tag” and “description”).  The  tag  is
405              useful  for scripting, but may not help the user.  The --no-tags
406              option (from Xdialog) may be used to suppress the column of tags
407              from  the  display.  Unlike the --no-items option, this does not
408              affect the data which is read from the script.
409
410              Xdialog does not  display  the  tag  column  for  the  analogous
411              buildlist and treeview widgets; dialog does the same.
412
413              Normally  dialog  allows  you  to quickly move to entries on the
414              displayed list, by matching a  single  character  to  the  first
415              character  of the tag.  When the --no-tags option is given, dia‐
416              log matches against the first character of the description.   In
417              either case, the matchable character is highlighted.
418
419       --ok-label string
420              Override the label used for “OK” buttons.
421
422       --output-fd fd
423              Direct output to the given file descriptor.  Most dialog scripts
424              write to the standard error, but  error  messages  may  also  be
425              written there, depending on your script.
426
427       --separator string
428
429       --output-separator string
430              Specify  a string that will separate the output on dialog's out‐
431              put from checklists, rather than a newline (for  --separate-out‐
432              put)  or  a  space.  This applies to other widgets such as forms
433              and editboxes which normally use a newline.
434
435       --print-maxsize
436              Print the maximum size of dialog boxes, i.e., the  screen  size,
437              to  dialog's  output.  This may be used alone, without other op‐
438              tions.
439
440       --print-size
441              Prints the size of each dialog box to dialog's output  when  the
442              box is initialized.
443
444       --print-text-only string [ height [ width ] ]
445              Prints the string as it would be wrapped in a message box to di‐
446              alog's output.
447
448              Because the optional height and width default to zero,  if  they
449              are  omitted,  dialog  autosizes  according to the screen dimen‐
450              sions.
451
452       --print-text-size string [ height [ width ] ]
453              Prints the size of the string as it would be wrapped in  a  mes‐
454              sage box, to dialog's output, as
455
456              height width
457
458              Because  the optional height and width parameters default to ze‐
459              ro, if they are  omitted,  dialog  autosizes  according  to  the
460              screen dimensions.
461
462       --print-version
463              Prints  dialog's  version  to dialog's output.  This may be used
464              alone, without other options.  It does not cause dialog to  exit
465              by itself.
466
467       --quoted
468              Normally  dialog  quotes  the strings returned by checklist's as
469              well as the item-help text.  Use this option to quote all string
470              results  as needed (i.e., if the string contains whitespace or a
471              single or double-quote character).
472
473       --reorder
474              By default, the buildlist widget uses the  same  order  for  the
475              output (right) list as for the input (left).  Use this option to
476              tell dialog to use the order in which a user adds selections  to
477              the output list.
478
479       --scrollbar
480              For  widgets  holding a scrollable set of data, draw a scrollbar
481              on its right-margin.  This does not respond to the mouse.
482
483       --separate-output
484              For certain widgets (buildlist, checklist, treeview), output re‐
485              sult  one  line  at  a  time, with no quoting.  This facilitates
486              parsing by another program.
487
488       --separate-widget string
489              Specify a string that will separate the output on dialog's  out‐
490              put  from each widget.  This is used to simplify parsing the re‐
491              sult of a dialog with several widgets.  If this  option  is  not
492              given, the default separator string is a tab character.
493
494       --shadow
495              Draw a shadow to the right and bottom of each dialog box.
496
497       --single-quoted
498              Use single-quoting as needed (and no quotes if unneeded) for the
499              output of checklist's as well as the item-help text.
500
501              If this option is not set, dialog may use double  quotes  around
502              each  item.  In either case, dialog adds backslashes to make the
503              output useful in shell scripts.
504
505              Single quotes would be needed if the string contains  whitespace
506              or a single or double-quote character.
507
508       --size-err
509              Check  the  resulting  size of a dialog box before trying to use
510              it, printing the resulting size if it is larger than the screen.
511              (This  option  is  obsolete,  since  all  new-window  calls  are
512              checked).
513
514       --sleep secs
515              Sleep (delay) for the given number of seconds after processing a
516              dialog box.
517
518       --stderr
519              Direct output to the standard error.  This is the default, since
520              curses normally writes screen updates to the standard output.
521
522       --stdout
523              Direct output to the standard output.  This option  is  provided
524              for  compatibility  with  Xdialog,  however using it in portable
525              scripts is not recommended, since  curses  normally  writes  its
526              screen  updates to the standard output.  If you use this option,
527              dialog attempts to reopen the terminal so it can  write  to  the
528              display.   Depending  on the platform and your environment, that
529              may fail.
530
531       --tab-correct
532              Convert each tab character  to  one  or  more  spaces  (for  the
533              textbox  widget;  otherwise to a single space).  Otherwise, tabs
534              are rendered according to the curses  library's  interpretation.
535              The --no-collapse option disables tab expansion.
536
537       --tab-len n
538              Specify  the  number  of spaces that a tab character occupies if
539              the “--tab-correct” option is given.  The default  is  8.   This
540              option is only effective for the textbox widget.
541
542       --time-format format
543              If the host provides strftime, this option allows you to specify
544              the format of the time printed for the  --timebox  widget.   The
545              day,  month,  year values in this case are for the current local
546              time.
547
548       --timeout secs
549              Timeout (exit with error code) if no user  response  within  the
550              given number of seconds.  A timeout of zero seconds is ignored.
551
552              This  option  is  ignored  by  the “--pause” widget.  It is also
553              overridden if the background “--tailboxbg” option is used to set
554              up multiple concurrent widgets.
555
556       --title title
557              Specifies  a title string to be displayed at the top of the dia‐
558              log box.
559
560       --trace filename
561              logs the command-line parameters, keystrokes and other  informa‐
562              tion to the given file.  If dialog reads a configure file, it is
563              logged as well.  Piped input to the gauge widget is logged.  Use
564              control/T to log a picture of the current dialog window.
565
566              The dialog program handles some command-line parameters special‐
567              ly, and removes them from the parameter list as  they  are  pro‐
568              cessed.   For example, if the first option is --trace, then that
569              is processed (and removed) before dialog  initializes  the  dis‐
570              play.
571
572       --week-start day
573              sets the starting day for the week, used in the “--calendar” op‐
574              tion.  The day parameter can be
575
576              ·   a number (0 to 6, Sunday through Saturday using POSIX) or
577
578              ·   the special value “locale” (this works  with  systems  using
579                  glibc,  providing  an  extension  to the locale command, the
580                  first_weekday value).
581
582              ·   a string matching one of the abbreviations for  the  day  of
583                  the  week shown in the calendar widget, e.g., “Mo” for “Mon‐
584                  day”.
585
586       --trim eliminate leading blanks, trim  literal  newlines  and  repeated
587              blanks from message text.
588
589              The trim feature is implemented subject to these conditions:
590
591              ·   the string does not contain “\n” or
592
593              ·   the --no-nl-expand option is used.
594
595              For more information, see Whitespace Options.
596
597              See also the “--cr-wrap” and “--no-collapse” options.
598
599       --version
600              Prints  dialog's version to the standard output, and exits.  See
601              also “--print-version”.
602
603       --visit-items
604              Modify the tab-traversal of checklist,  radiolist,  menubox  and
605              inputmenu  to  include  the  list of items as one of the states.
606              This is useful as a visual aid, i.e., the cursor position  helps
607              some users.
608
609              When this option is given, the cursor is initially placed on the
610              list.  Abbreviations (the first letter of the tag) apply to  the
611              list  items.   If you tab to the button row, abbreviations apply
612              to the buttons.
613
614       --yes-label string
615              Override the label used for “Yes” buttons.
616
617   Box Options
618       All dialog boxes have at least three parameters:
619
620       text   the caption or contents of the box.
621
622       height the height of the dialog box.
623
624       width  the width of the dialog box.
625
626       Other parameters depend on the box type.
627
628       --buildlist text height width list-height [ tag item status ] ...
629              A buildlist dialog displays two lists, side-by-side.   The  list
630              on the left shows unselected items.  The list on the right shows
631              selected items.  As items are selected or unselected, they  move
632              between the lists.
633
634              Use  a  carriage return or the “OK” button to accept the current
635              value in the selected-window and exit.  The results are  written
636              using the order displayed in the selected-window.
637
638              The initial on/off state of each entry is specified by status.
639
640              The  dialog behaves like a menu, using the --visit-items to con‐
641              trol whether the cursor is allowed to visit the lists directly.
642
643              ·   If --visit-items is not given, tab-traversal uses two states
644                  (OK/Cancel).
645
646              ·   If  --visit-items  is  given, tab-traversal uses four states
647                  (Left/Right/OK/Cancel).
648
649              Whether or not --visit-items is given, it is  possible  to  move
650              the highlight between the two lists using the default “^” (left-
651              column) and “$” (right-column) keys.
652
653              On exit, a list of the tag strings of  those  entries  that  are
654              turned on will be printed on dialog's output.
655
656              If the "--separate-output" option is not given, the strings will
657              be quoted as needed to make it simple for  scripts  to  separate
658              them.   By default, this uses double-quotes, as needed.  See the
659--single-quoted” option, which modifies the quoting behavior.
660
661       --calendar text height width day month year
662              A calendar box displays month, day and year  in  separately  ad‐
663              justable  windows.   If  the  values  for day, month or year are
664              missing or negative, the current date's corresponding values are
665              used.   You  can  increment  or decrement any of those using the
666              left-, up-, right-, and down-arrows.  Use vi-style h, j, k and l
667              for  moving  around  the  array  of days in a month.  Use tab or
668              backtab to move between windows.  If the year is given as  zero,
669              the current date is used as an initial value.
670
671              On  exit,  the  date is printed in the form day/month/year.  The
672              format can be overridden using the --date-format option.
673
674       --checklist text height width list-height [ tag item status ] ...
675              A checklist box is similar to a menu box; there are multiple en‐
676              tries  presented  in  the form of a menu.  Another difference is
677              that you can indicate which entry is currently selected, by set‐
678              ting  its status to on.  Instead of choosing one entry among the
679              entries, each entry can be turned on or off by  the  user.   The
680              initial on/off state of each entry is specified by status.
681
682              On  exit,  a  list  of the tag strings of those entries that are
683              turned on will be printed on dialog's output.
684
685              If the “--separate-output” option is not given, the strings will
686              be  quoted  as  needed to make it simple for scripts to separate
687              them.  By default, this uses double-quotes (as needed).  See the
688--single-quoted” option, which modifies the quoting behavior.
689
690       --dselect filepath height width
691              The  directory-selection  dialog displays a text-entry window in
692              which you can type a directory, and above that  a  windows  with
693              directory names.
694
695              Here filepath can be a filepath in which case the directory win‐
696              dow will display the contents of the  path  and  the  text-entry
697              window will contain the preselected directory.
698
699              Use  tab  or arrow keys to move between the windows.  Within the
700              directory window, use the up/down arrow keys to scroll the  cur‐
701              rent selection.  Use the space-bar to copy the current selection
702              into the text-entry window.
703
704              Typing any printable characters switches focus to the text-entry
705              window,  entering that character as well as scrolling the direc‐
706              tory window to the closest match.
707
708              Use a carriage return or the “OK” button to accept  the  current
709              value in the text-entry window and exit.
710
711              On  exit,  the  contents of the text-entry window are written to
712              dialog's output.
713
714       --editbox filepath height width
715              The edit-box dialog displays a copy of the file.  You  may  edit
716              it using the backspace, delete and cursor keys to correct typing
717              errors.  It also recognizes pageup/pagedown.  Unlike  the  --in‐
718              putbox,  you  must  tab to the “OK” or “Cancel” buttons to close
719              the dialog.  Pressing the “Enter” key within the box will  split
720              the corresponding line.
721
722              On exit, the contents of the edit window are written to dialog's
723              output.
724
725       --form text height width formheight [ label y x item y x flen ilen ] ...
726              The form dialog displays a form consisting of labels and fields,
727              which are positioned on a scrollable window by coordinates given
728              in the script.  The field length flen and input-length ilen tell
729              how  long the field can be.  The former defines the length shown
730              for a selected field, while the latter defines  the  permissible
731              length of the data entered in the field.
732
733              ·   If  flen is zero, the corresponding field cannot be altered.
734                  and the contents  of  the  field  determine  the  displayed-
735                  length.
736
737              ·   If  flen  is negative, the corresponding field cannot be al‐
738                  tered, and the negated value of flen is  used  as  the  dis‐
739                  played-length.
740
741              ·   If ilen is zero, it is set to flen.
742
743              Use  up/down  arrows  (or  control/N, control/P) to move between
744              fields.  Use tab to move between windows.
745
746              On exit, the contents of the form-fields are written to dialog's
747              output,  each  field  separated  by a newline.  The text used to
748              fill non-editable fields (flen is zero or negative) is not writ‐
749              ten out.
750
751       --fselect filepath height width
752              The fselect (file-selection) dialog displays a text-entry window
753              in which you can type a filename (or directory), and above  that
754              two windows with directory names and filenames.
755
756              Here  filepath  can be a filepath in which case the file and di‐
757              rectory windows will display the contents of the  path  and  the
758              text-entry window will contain the preselected filename.
759
760              Use  tab  or arrow keys to move between the windows.  Within the
761              directory or filename windows, use the  up/down  arrow  keys  to
762              scroll  the  current  selection.   Use the space-bar to copy the
763              current selection into the text-entry window.
764
765              Typing any printable characters switches focus to the text-entry
766              window,  entering that character as well as scrolling the direc‐
767              tory and filename windows to the closest match.
768
769              Typing the space character forces dialog to complete the current
770              name  (up  to  the point where there may be a match against more
771              than one entry).
772
773              Use a carriage return or the “OK” button to accept  the  current
774              value in the text-entry window and exit.
775
776              On  exit,  the  contents of the text-entry window are written to
777              dialog's output.
778
779       --gauge text height width [percent]
780              A gauge box displays a meter along the bottom of the  box.   The
781              meter  indicates  the percentage.  New percentages are read from
782              standard input, one integer per line.  The meter is  updated  to
783              reflect  each  new  percentage.  If the standard input reads the
784              string “XXX”, then the first line following is taken as an inte‐
785              ger  percentage,  then  subsequent lines up to another “XXX” are
786              used for a new prompt.  The gauge exits when EOF is  reached  on
787              the standard input.
788
789              The  percent  value  denotes the initial percentage shown in the
790              meter.  If not specified, it is zero.
791
792              On exit, no text is written to dialog's output.  The widget  ac‐
793              cepts no input, so the exit status is always OK.
794
795       --infobox text height width
796              An  info box is basically a message box.  However, in this case,
797              dialog will exit immediately after displaying the message to the
798              user.   The screen is not cleared when dialog exits, so that the
799              message will remain on the screen until the calling shell script
800              clears it later.  This is useful when you want to inform the us‐
801              er that some operations are carrying on that  may  require  some
802              time to finish.
803
804              On exit, no text is written to dialog's output.  An OK exit sta‐
805              tus is returned.
806
807       --inputbox text height width [init]
808              An input box is useful when you want to ask questions  that  re‐
809              quire the user to input a string as the answer.  If init is sup‐
810              plied it is used to initialize the input string.  When  entering
811              the string, the backspace, delete and cursor keys can be used to
812              correct typing errors.  If the input string is longer  than  can
813              fit in the dialog box, the input field will be scrolled.
814
815              On exit, the input string will be printed on dialog's output.
816
817       --inputmenu text height width menu-height [ tag item ] ...
818              An inputmenu box is very similar to an ordinary menu box.  There
819              are only a few differences between them:
820
821              1.  The entries are not automatically centered but left  adjust‐
822                  ed.
823
824              2.  An  extra  button  (called  Rename) is implied to rename the
825                  current item when it is pressed.
826
827              3.  It is possible to rename the current entry by  pressing  the
828                  Rename button.  Then dialog will write the following on dia‐
829                  log's output.
830
831                  RENAMED <tag> <item>
832
833       --menu text height width menu-height [ tag item ] ...
834              As its name suggests, a menu box is a dialog  box  that  can  be
835              used  to present a list of choices in the form of a menu for the
836              user to choose.  Choices are displayed in the order given.  Each
837              menu entry consists of a tag string and an item string.  The tag
838              gives the entry a name to distinguish it from the other  entries
839              in the menu.  The item is a short description of the option that
840              the entry represents.  The user can move between  the  menu  en‐
841              tries  by  pressing the cursor keys, the first letter of the tag
842              as a hot-key, or the number keys 1 through 9.  There  are  menu-
843              height  entries  displayed in the menu at one time, but the menu
844              will be scrolled if there are more entries than that.
845
846              On exit the tag of the chosen menu entry will be printed on dia‐
847              log's  output.  If the “--help-button” option is given, the cor‐
848              responding help text will be printed if  the  user  selects  the
849              help button.
850
851       --mixedform text height width formheight [ label y x item y x flen ilen itype ] ...
852              The  mixedform  dialog  displays a form consisting of labels and
853              fields, much like the --form dialog.  It  differs  by  adding  a
854              field-type  parameter  to each field's description.  Each bit in
855              the type denotes an attribute of the field:
856
857              1    hidden, e.g., a password field.
858
859              2    readonly, e.g., a label.
860
861       --mixedgauge text height width percent [ tag1 item1 ] ...
862              A mixedgauge box displays a meter along the bottom of  the  box.
863              The meter indicates the percentage.
864
865              It  also  displays a list of the tag- and item-values at the top
866              of the box.  See dialog(3) for the tag values.
867
868              The text is shown as a caption between the list and meter.   The
869              percent value denotes the initial percentage shown in the meter.
870
871              No provision is made for reading data from the standard input as
872              --gauge does.
873
874              On exit, no text is written to dialog's output.  The widget  ac‐
875              cepts no input, so the exit status is always OK.
876
877       --msgbox text height width
878              A message box is very similar to a yes/no box.  The only differ‐
879              ence between a message box and a yes/no box is  that  a  message
880              box has only a single OK button.  You can use this dialog box to
881              display any message you like.  After reading  the  message,  the
882              user  can  press  the ENTER key so that dialog will exit and the
883              calling shell script can continue its operation.
884
885              If the message is too large for the space, dialog may allow  you
886              to scroll it, provided that the underlying curses implementation
887              is capable enough.  In this case, a percentage is shown  in  the
888              base of the widget.
889
890              On  exit,  no  text is written to dialog's output.  Only an “OK”
891              button is provided for input, but an ESC exit status may be  re‐
892              turned.
893
894       --pause text height width seconds
895              A  pause  box displays a meter along the bottom of the box.  The
896              meter indicates how many seconds remain until  the  end  of  the
897              pause.   The  pause  exits  when  timeout is reached or the user
898              presses the OK button (status OK) or the user presses the CANCEL
899              button or Esc key.
900
901       --passwordbox text height width [init]
902              A  password box is similar to an input box, except that the text
903              the user enters is not displayed.  This is useful when prompting
904              for  passwords or other sensitive information.  Be aware that if
905              anything is passed in “init”, it will be visible in the system's
906              process table to casual snoopers.  Also, it is very confusing to
907              the user to provide them with a  default  password  they  cannot
908              see.   For  these  reasons,  using “init” is highly discouraged.
909              See “--insecure” if you do not care about your password.
910
911              On exit, the input string will be printed on dialog's output.
912
913       --passwordform text height width formheight [ label y x item y x flen ilen ] ...
914              This is identical to --form except  that  all  text  fields  are
915              treated as password widgets rather than inputbox widgets.
916
917       --prgbox text command height width
918
919       --prgbox command height width
920              A prgbox is very similar to a programbox.
921
922              This  dialog box is used to display the output of a command that
923              is specified as an argument to prgbox.
924
925              After the command completes, the user can press the ENTER key so
926              that  dialog will exit and the calling shell script can continue
927              its operation.
928
929              If three parameters are given, it displays the  text  under  the
930              title,  delineated  from the scrolling file's contents.  If only
931              two parameters are given, this text is omitted.
932
933       --programbox text height width
934
935       --programbox height width
936              A programbox is very similar to a progressbox.  The only differ‐
937              ence  between a program box and a progress box is that a program
938              box displays an OK button  (but  only  after  the  command  com‐
939              pletes).
940
941              This  dialog  box  is used to display the piped output of a com‐
942              mand.  After the command completes, the user can press the ENTER
943              key  so  that  dialog will exit and the calling shell script can
944              continue its operation.
945
946              If three parameters are given, it displays the  text  under  the
947              title,  delineated  from the scrolling file's contents.  If only
948              two parameters are given, this text is omitted.
949
950       --progressbox text height width
951
952       --progressbox height width
953              A progressbox is similar to an tailbox, except that
954
955              a) rather than displaying the contents of a file,
956                 it displays the piped output of a command and
957
958              b) it will exit when it reaches the end of the file
959                 (there is no “OK” button).
960
961              If three parameters are given, it displays the  text  under  the
962              title,  delineated  from the scrolling file's contents.  If only
963              two parameters are given, this text is omitted.
964
965       --radiolist text height width list-height  [ tag item status ] ...
966              A radiolist box is similar to a menu box.  The  only  difference
967              is  that  you can indicate which entry is currently selected, by
968              setting its status to on.
969
970              On exit, the tag of the selected item  is  written  to  dialog's
971              output.
972
973       --tailbox file height width
974              Display text from a file in a dialog box, as in a “tail -f” com‐
975              mand.  Scroll left/right using vi-style 'h' and 'l',  or  arrow-
976              keys.  A '0' resets the scrolling.
977
978              On  exit,  no  text is written to dialog's output.  Only an “OK”
979              button is provided for input, but an ESC exit status may be  re‐
980              turned.
981
982       --rangebox text height width min-value max-value default-value
983              Allow  the  user to select from a range of values, e.g., using a
984              slider.  The dialog shows the current value as a bar  (like  the
985              gauge  dialog).   Tabs or arrow keys move the cursor between the
986              buttons and the value.  When the cursor is on the value, you can
987              edit it by:
988
989              left/right cursor movement to select a digit to modify
990
991              +/-  characters to increment/decrement the digit by one
992
993              0 through 9
994                   to set the digit to the given value
995
996              Some keys are also recognized in all cursor positions:
997
998              home/end
999                   set the value to its maximum or minimum
1000
1001              pageup/pagedown
1002                   increment the value so that the slider moves by one column
1003
1004       --tailboxbg file height width
1005              Display  text  from a file in a dialog box as a background task,
1006              as in a “tail -f &” command.  Scroll left/right  using  vi-style
1007              'h' and 'l', or arrow-keys.  A '0' resets the scrolling.
1008
1009              Dialog  treats  the background task specially if there are other
1010              widgets (--and-widget) on the screen concurrently.  Until  those
1011              widgets  are  closed (e.g., an “OK”), dialog will perform all of
1012              the tailboxbg widgets in the same process, polling for  updates.
1013              You may use a tab to traverse between the widgets on the screen,
1014              and close them individually, e.g., by pressing ENTER.  Once  the
1015              non-tailboxbg  widgets are closed, dialog forks a copy of itself
1016              into the background, and prints its process  id  if  the  “--no-
1017              kill” option is given.
1018
1019              On  exit, no text is written to dialog's output.  Only an “EXIT”
1020              button is provided for input, but an ESC exit status may be  re‐
1021              turned.
1022
1023              NOTE:  Older versions of dialog forked immediately and attempted
1024              to update the screen individually.  Besides being bad  for  per‐
1025              formance,  it  was  unworkable.  Some older scripts may not work
1026              properly with the polled scheme.
1027
1028       --textbox file height width
1029              A text box lets you display the contents of a text file in a di‐
1030              alog  box.   It is like a simple text file viewer.  The user can
1031              move through the file by using the  cursor,  page-up,  page-down
1032              and HOME/END keys available on most keyboards.  If the lines are
1033              too long to be displayed in the box, the LEFT/RIGHT keys can  be
1034              used  to  scroll the text region horizontally.  You may also use
1035              vi-style keys h, j, k, and l in place of the cursor keys, and  B
1036              or N in place of the page-up and page-down keys.  Scroll up/down
1037              using vi-style 'k' and 'j', or  arrow-keys.   Scroll  left/right
1038              using  vi-style  'h'  and  'l', or arrow-keys.  A '0' resets the
1039              left/right scrolling.  For more  convenience,  vi-style  forward
1040              and backward searching functions are also provided.
1041
1042              On  exit, no text is written to dialog's output.  Only an “EXIT”
1043              button is provided for input, but an ESC exit status may be  re‐
1044              turned.
1045
1046       --timebox text height [width hour minute second]
1047              A  dialog  is  displayed which allows you to select hour, minute
1048              and second.  If the values for hour, minute or second are  miss‐
1049              ing  or  negative,  the  current date's corresponding values are
1050              used.  You can increment or decrement any  of  those  using  the
1051              left-,  up-, right- and down-arrows.  Use tab or backtab to move
1052              between windows.
1053
1054              On exit, the result is printed in the  form  hour:minute:second.
1055              The format can be overridden using the --time-format option.
1056
1057       --treeview text height width list-height [ tag item status depth ] ...
1058              Display data organized as a tree.  Each group of data contains a
1059              tag, the text to display for  the  item,  its  status  (“on”  or
1060              “off”) and the depth of the item in the tree.
1061
1062              Only  one item can be selected (like the radiolist).  The tag is
1063              not displayed.
1064
1065              On exit, the tag of the selected item  is  written  to  dialog's
1066              output.
1067
1068       --yesno text height width
1069              A yes/no dialog box of size height rows by width columns will be
1070              displayed.  The string specified by text is displayed inside the
1071              dialog  box.   If this string is too long to fit in one line, it
1072              will be automatically divided into multiple lines at appropriate
1073              places.  The text string can also contain the sub-string "\n" or
1074              newline characters `\n' to  control  line  breaking  explicitly.
1075              This  dialog box is useful for asking questions that require the
1076              user to answer either yes or no.  The dialog box has a Yes  but‐
1077              ton  and  a  No  button, in which the user can switch between by
1078              pressing the TAB key.
1079
1080              On exit, no text is written to dialog's output.  In addition  to
1081              the “Yes” and “No” exit codes (see DIAGNOSTICS) an ESC exit sta‐
1082              tus may be returned.
1083
1084              The codes used for “Yes” and “No” match those used for “OK”  and
1085              “Cancel”, internally no distinction is made.
1086
1087   Obsolete Options
1088       --beep This was used to tell the original cdialog that it should make a
1089              beep when the separate processes of the tailboxbg  widget  would
1090              repaint the screen.
1091
1092       --beep-after
1093              Beep  after a user has completed a widget by pressing one of the
1094              buttons.
1095
1096   Whitespace Options
1097       These options can be used to transform whitespace (space, tab, newline)
1098       as dialog reads the script:
1099              --cr-wrap, --no-collapse, --no-nl-expand, and --trim
1100
1101       The options are not independent:
1102
1103       ·   Dialog  checks if the script contains at least one “\n” and (unless
1104           --no-nl-expand is set) will ignore the --no-collapse and --trim op‐
1105           tions.
1106
1107       ·   After  checking for “\n” and the --no-nl-expand option, dialog han‐
1108           dles the --trim option.
1109
1110           If the --trim option takes effect, then  dialog  ignores  --no-col‐
1111           lapse.   It  changes sequences of tabs, spaces (and newlines unless
1112           -cr-wrap is set) to a single space.
1113
1114       ·   If neither the “\n” or --trim cases apply, dialog checks  --no-col‐
1115           lapse to decide whether to reduce sequences of tabs and spaces to a
1116           single space.
1117
1118           In this case, dialog ignores -cr-wrap and does not modify newlines.
1119
1120       Taking those dependencies into account, here is a table summarizing the
1121       behavior  for  the  various combinations of options.  The table assumes
1122       that the script contains at least one “\n” when the --no-nl-expand  op‐
1123       tion is not set.
1124
1125            cr-     no-        no-         trim    Result
1126            wrap    collapse   nl-expand
1127            ──────────────────────────────────────────────────────────────────────
1128            no      no         no          no      Convert tab to space.  Convert
1129                                                   newline to space.  Convert
1130                                                   “\n” to newline.
1131            no      no         no          yes     Convert tab to space.  Convert
1132                                                   newline to space.  Convert
1133                                                   “\n” to newline.
1134            no      no         yes         no      Convert tab to space.  Do not
1135                                                   convert newline to space.
1136                                                   Convert multiple-space to sin‐
1137                                                   gle.  Show “\n” literally.
1138            no      no         yes         yes     Convert tab to space.  Convert
1139                                                   multiple-space to single.
1140                                                   Convert newline to space.
1141                                                   Show “\n” literally.
1142            no      yes        no          no      Convert newline to space.
1143                                                   Convert “\n” to newline.
1144            no      yes        no          yes     Convert newline to space.
1145                                                   Convert “\n” to newline.
1146            no      yes        yes         no      Do not convert newline to
1147                                                   space.  Do not reduce multiple
1148                                                   blanks.  Show “\n” literally.
1149            no      yes        yes         yes     Convert multiple-space to sin‐
1150                                                   gle.  Convert newline to
1151                                                   space.  Show “\n” literally.
1152            yes     no         no          no      Convert tab to space.  Wrap on
1153                                                   newline.  Convert “\n” to new‐
1154                                                   line.
1155            yes     no         no          yes     Convert tab to space.  Wrap on
1156                                                   newline.  Convert “\n” to new‐
1157                                                   line.
1158
1159            yes     no         yes         no      Convert tab to space.  Do not
1160                                                   convert newline to space.
1161                                                   Convert multiple-space to sin‐
1162                                                   gle.  Show “\n” literally.
1163            yes     no         yes         yes     Convert tab to space.  Convert
1164                                                   multiple-space to single.
1165                                                   Wrap on newline.  Show “\n”
1166                                                   literally.
1167            yes     yes        no          no      Wrap on newline.  Convert “\n”
1168                                                   to newline.
1169            yes     yes        no          yes     Wrap on newline.  Convert “\n”
1170                                                   to newline.
1171            yes     yes        yes         no      Do not convert newline to
1172                                                   space.  Do not reduce multiple
1173                                                   blanks.  Show “\n” literally.
1174            yes     yes        yes         yes     Convert multiple-space to sin‐
1175                                                   gle.  Wrap on newline.  Show
1176                                                   “\n” literally.
1177

RUN-TIME CONFIGURATION

1179       1.  Create a sample configuration file by typing:
1180
1181              dialog --create-rc file
1182
1183       2.  At start, dialog determines the settings to use as follows:
1184
1185           a)  if  environment  variable DIALOGRC is set, its value determines
1186               the name of the configuration file.
1187
1188           b)  if the file in (a) is not found, use the  file  $HOME/.dialogrc
1189               as the configuration file.
1190
1191           c)  if  the  file  in (b) is not found, try using the GLOBALRC file
1192               determined at compile-time, i.e., /etc/dialogrc.
1193
1194           d)  if the file in (c) is not found, use compiled in defaults.
1195
1196       3.  Edit the sample configuration file and copy it to some  place  that
1197           dialog can find, as stated in step 2 above.
1198

KEY BINDINGS

1200       You can override or add to key bindings in dialog by adding to the con‐
1201       figuration file.  Dialog's bindkey command maps single keys to its  in‐
1202       ternal coding.
1203
1204              bindkey widget curses_key dialog_key
1205
1206       The  widget  name can be “*” (all widgets), or specific widgets such as
1207       textbox.  Specific widget bindings override the “*” bindings.  User-de‐
1208       fined bindings override the built-in bindings.
1209
1210       The curses_key can be expressed in different forms:
1211
1212       ·   It may be any of the names derived from curses.h, e.g., “HELP” from
1213           “KEY_HELP”.
1214
1215       ·   Dialog also recognizes ANSI control characters such as “^A”,  “^?”,
1216           as well as C1-controls such as “~A” and “~?”.
1217
1218       ·   Finally, dialog allows backslash escapes as in C.  Those can be oc‐
1219           tal character values such as “\033” (the ASCII  escape  character),
1220           or the characters listed in this table:
1221
1222                 Escaped   Actual
1223                 ───────────────────────────────
1224                 \b        backspace
1225                 \f        form feed
1226                 \n        new line (line feed)
1227                 \r        carriage return
1228                 \s        space
1229                 \t        tab
1230                 \^        “^” (caret)
1231                 \?        “?” (question mark)
1232                 \\        “\” (backslash)
1233                 ───────────────────────────────
1234
1235       Dialog's internal keycode names correspond to the DLG_KEYS_ENUM type in
1236       dlg_keys.h, e.g., “HELP” from “DLGK_HELP”.
1237
1238   Widget Names
1239       Some widgets (such as the formbox) have an area  where  fields  can  be
1240       edited.   Those  are managed in a subwindow of the widget, and may have
1241       separate keybindings from the main widget because  the  subwindows  are
1242       registered using a different name.
1243
1244            Widget        Window name   Subwindow Name
1245            ───────────────────────────────────────────
1246            calendar      calendar
1247            checklist     checklist
1248            editbox       editbox       editbox2
1249            form          formbox       formfield
1250            fselect       fselect       fselect2
1251            inputbox      inputbox      inputbox2
1252            menu          menubox       menu
1253            msgbox        msgbox
1254            pause         pause
1255            progressbox   progressbox
1256            radiolist     radiolist
1257            tailbox       tailbox
1258            textbox       textbox       searchbox
1259            timebox       timebox
1260            yesno         yesno
1261            ───────────────────────────────────────────
1262
1263       Some  widgets  are  actually  other widgets, using internal settings to
1264       modify the behavior.  Those use the same widget name as the actual wid‐
1265       get:
1266
1267            Widget         Actual Widget
1268            ─────────────────────────────
1269            dselect        fselect
1270            infobox        msgbox
1271            inputmenu      menu
1272            mixedform      form
1273            passwordbox    inputbox
1274            passwordform   form
1275            prgbox         progressbox
1276            programbox     progressbox
1277            tailboxbg      tailbox
1278            ─────────────────────────────
1279
1280   Built-in Bindings
1281       This  manual  page  does not list the key bindings for each widget, be‐
1282       cause that detailed information can be obtained by running dialog.   If
1283       you have set the --trace option, dialog writes the key-binding informa‐
1284       tion for each widget as it is registered.
1285
1286   Example
1287       Normally dialog uses different keys for navigating between the  buttons
1288       and editing part of a dialog versus navigating within the editing part.
1289       That is, tab (and back-tab) traverse buttons (or  between  buttons  and
1290       the  editing part), while arrow keys traverse fields within the editing
1291       part.  Tabs are also recognized as a special case  for  traversing  be‐
1292       tween widgets, e.g., when using multiple tailboxbg widgets.
1293
1294       Some users may wish to use the same key for traversing within the edit‐
1295       ing part as for traversing between buttons.  The form widget is written
1296       to  support  this sort of redefinition of the keys, by adding a special
1297       group in dlgk_keys.h for “form” (left/right/next/prev).  Here is an ex‐
1298       ample binding demonstrating how to do this:
1299
1300              bindkey formfield TAB  form_NEXT
1301              bindkey formbox   TAB  form_NEXT
1302              bindkey formfield BTAB form_prev
1303              bindkey formbox   BTAB form_prev
1304
1305       That  type  of redefinition would not be useful in other widgets, e.g.,
1306       calendar, due to the potentially large number of fields to traverse.
1307

ENVIRONMENT

1309       DIALOGOPTS     Define this variable to apply any of the common  options
1310                      to  each  widget.   Most of the common options are reset
1311                      before processing each widget.  If you set  the  options
1312                      in  this  environment variable, they are applied to dia‐
1313                      log's state after the reset.  As in the “--file” option,
1314                      double-quotes and backslashes are interpreted.
1315
1316                      The  “--file”  option  is not considered a common option
1317                      (so you cannot embed it within  this  environment  vari‐
1318                      able).
1319
1320       DIALOGRC       Define  this variable if you want to specify the name of
1321                      the configuration file to use.
1322
1323       DIALOG_CANCEL
1324
1325       DIALOG_ERROR
1326
1327       DIALOG_ESC
1328
1329       DIALOG_EXTRA
1330
1331       DIALOG_HELP
1332
1333       DIALOG_ITEM_HELP
1334
1335       DIALOG_OK      Define any of these variables to change the exit code on
1336                      Cancel  (1), error (-1), ESC (255), Extra (3), Help (2),
1337                      Help with --item-help (2), or OK  (0).   Normally  shell
1338                      scripts cannot distinguish between -1 and 255.
1339
1340       DIALOG_TTY     Set  this  variable to “1” to provide compatibility with
1341                      older versions of  dialog  which  assumed  that  if  the
1342                      script  redirects  the standard output, that the “--std‐
1343                      out” option was given.
1344

FILES

1346       $HOME/.dialogrc     default configuration file
1347

EXAMPLES

1349       The dialog sources contain several samples of how to use the  different
1350       box  options  and  how  they look.  Just take a look into the directory
1351       samples/ of the source.
1352

DIAGNOSTICS

1354       Exit status is subject to being overridden  by  environment  variables.
1355       The  default  values  and  corresponding environment variables that can
1356       override them are:
1357
1358       0    if the YES or OK button is pressed (DIALOG_OK).
1359
1360       1    if the No or Cancel button is pressed (DIALOG_CANCEL).
1361
1362       2    if the Help button is pressed (DIALOG_HELP),
1363            except as noted below about DIALOG_ITEM_HELP.
1364
1365       3    if the Extra button is pressed (DIALOG_EXTRA).
1366
1367       4    if the Help button is pressed,
1368            and the --item-help option is set
1369            and the DIALOG_ITEM_HELP environment variable is set to 4.
1370
1371            While any of the exit-codes can be  overridden  using  environment
1372            variables,  this  special  case was introduced in 2004 to simplify
1373            compatibility.  Dialog uses  DIALOG_ITEM_HELP(4)  internally,  but
1374            unless  the  environment  variable is also set, it changes that to
1375            DIALOG_HELP(2) on exit.
1376
1377       -1   if errors occur inside dialog (DIALOG_ERROR) or dialog  exits  be‐
1378            cause the ESC key (DIALOG_ESC) was pressed.
1379

PORTABILITY

1381       Dialog  works  with  X/Open curses.  However, some implementations have
1382       deficiencies:
1383
1384          ·   HPUX curses (and perhaps others) do not open the terminal  prop‐
1385              erly  for  the  newterm function.  This interferes with dialog's
1386              --input-fd option, by preventing cursor-keys and similar  escape
1387              sequences from being recognized.
1388
1389          ·   NetBSD  5.1  curses  has incomplete support for wide-characters.
1390              dialog will build, but not all examples display properly.
1391

COMPATIBILITY

1393       You may want to write scripts which run with other dialog “clones”.
1394
1395   Original Dialog
1396       First, there is the “original” dialog program to consider (versions 0.3
1397       to 0.9).  It had some misspelled (or inconsistent) options.  The dialog
1398       program maps those deprecated options to the preferred ones.  They  in‐
1399       clude:
1400
1401              Option         Treatment
1402              ─────────────────────────────────
1403              --beep-after   ignored
1404              --guage        mapped to --gauge
1405              ─────────────────────────────────
1406
1407   Xdialog
1408       This  is  an  X application, rather than a terminal program.  With some
1409       care, it is possible to write useful scripts that work with both  Xdia‐
1410       log and dialog.
1411
1412       The  dialog program ignores these options which are recognized by Xdia‐
1413       log:
1414
1415              Option             Treatment
1416              ───────────────────────────────────────────────
1417              --allow-close      ignored
1418              --auto-placement   ignored
1419              --fixed-font       ignored
1420              --icon             ignored
1421              --keep-colors      ignored
1422              --no-close         ignored
1423              --no-cr-wrap       ignored
1424              --screen-center    ignored
1425              --separator        mapped to --separate-output
1426              --smooth           ignored
1427              --under-mouse      ignored
1428              --wmclass          ignored
1429              ───────────────────────────────────────────────
1430
1431       Xdialog's manpage has a section discussing its compatibility with  dia‐
1432       log.   There  are some differences not shown in the manpage.  For exam‐
1433       ple, the html documentation states
1434
1435              Note: former Xdialog releases used the “\n” (line feed) as a re‐
1436              sults  separator for the checklist widget; this has been changed
1437              to “/” in Xdialog v1.5.0 to make it compatible  with  (c)dialog.
1438              In  your  old scripts using the Xdialog checklist, you will then
1439              have to add the --separate-output option before the  --checklist
1440              one.
1441
1442       Dialog  has  not  used a different separator; the difference was likely
1443       due to confusion regarding some script.
1444
1445   Whiptail
1446       Then there is whiptail.  For practical purposes, it  is  maintained  by
1447       Debian (very little work is done by its upstream developers).  Its doc‐
1448       umentation (README.whiptail) claims
1449
1450              whiptail(1) is a lightweight replacement for dialog(1),
1451              to provide dialog boxes for shell scripts.
1452              It is built on the
1453              newt windowing library rather than the ncurses library, allowing
1454              it to be smaller in embedded environments such as installers,
1455              rescue disks, etc.
1456
1457              whiptail is designed to be drop-in compatible with dialog, but
1458              has less features: some dialog boxes are not implemented, such
1459              as tailbox, timebox, calendarbox, etc.
1460
1461       Comparing actual sizes (Debian testing, 2007/1/10): The total of  sizes
1462       for whiptail, the newt, popt and slang libraries is 757 KB.  The compa‐
1463       rable number for dialog (counting ncurses) is  520 KB.   Disregard  the
1464       first paragraph.
1465
1466       The  second  paragraph is misleading, since whiptail also does not work
1467       for common options of dialog, such as the gauge box.  whiptail is  less
1468       compatible with dialog than the original mid-1990s dialog 0.4 program.
1469
1470       whiptail's  manpage borrows features from dialog, e.g., but oddly cites
1471       only dialog versions up to 0.4 (1994) as a source.  That is,  its  man‐
1472       page  refers  to features which were borrowed from more recent versions
1473       of dialog, e.g.,
1474
1475       ·   --gauge (from 0.5)
1476
1477       ·   --passwordbox (from Debian changes in 1999),
1478
1479       ·   --default-item (from dialog 2000/02/22),
1480
1481       ·   --output-fd (from dialog 2002/08/14).
1482
1483       Somewhat humorously, one may note that the popt  feature  (undocumented
1484       in its manpage) of using a “--” as an escape was documented in dialog's
1485       manpage about a year before it was  mentioned  in  whiptail's  manpage.
1486       whiptail's  manpage incorrectly attributes that to getopt (and is inac‐
1487       curate anyway).
1488
1489       Debian uses whiptail for the official dialog variation.
1490
1491       The dialog program ignores or maps these options which  are  recognized
1492       by whiptail:
1493
1494              Option            Treatment
1495              ───────────────────────────────────────────
1496              --cancel-button   mapped to --cancel-label
1497              --fb              ignored
1498              --fullbutton      ignored
1499              --no-button       mapped to --no-label
1500              --nocancel        mapped to --no-cancel
1501              --noitem          mapped to --no-items
1502              --notags          mapped to --no-tags
1503              --ok-button       mapped to --ok-label
1504              --scrolltext      mapped to --scrollbar
1505              --topleft         mapped to --begin 0 0
1506              --yes-button      mapped to --yes-label
1507              ───────────────────────────────────────────
1508
1509       There  are  visual  differences which are not addressed by command-line
1510       options:
1511
1512       ·   dialog centers lists within the window.   whiptail  typically  puts
1513           lists against the left margin.
1514
1515       ·   whiptail  uses  angle  brackets  (“<” and “>”) for marking buttons.
1516           dialog uses square brackets.
1517
1518       ·   whiptail marks the limits of subtitles with vertical bars.   dialog
1519           does not mark the limits.
1520
1521       ·   whiptail  attempts to mark the top/bottom cells of a scrollbar with
1522           up/down arrows.  When it cannot do this, it fills those cells  with
1523           the background color of the scrollbar and confusing the user.  dia‐
1524           log uses the entire scrollbar space, thereby getting better resolu‐
1525           tion.
1526

BUGS

1528       Perhaps.
1529

AUTHOR

1531       Thomas E. Dickey (updates for 0.9b and beyond)
1532

CONTRIBUTORS

1534       Kiran Cherupally – the mixed form and mixed gauge widgets.
1535
1536       Tobias C. Rittweiler
1537
1538       Valery Reznic – the form and progressbox widgets.
1539
1540       Yura Kalinichenko adapted the gauge widget as “pause”.
1541
1542       This  is  a  rewrite (except as needed to provide compatibility) of the
1543       earlier version of dialog 0.9a, which lists as authors:
1544
1545       ·   Savio Lam – version 0.3, “dialog”
1546
1547       ·   Stuart Herbert – patch for version 0.4
1548
1549       ·   Marc Ewing – the gauge widget.
1550
1551       ·   Pasquale De Marco “Pako” – version 0.9a, “cdialog”
1552
1553
1554
1555$Date: 2020/03/27 21:14:23 $                                         DIALOG(1)
Impressum