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

RUN-TIME CONFIGURATION

1236       1.  Create a sample configuration file by typing:
1237
1238              dialog --create-rc file
1239
1240       2.  At start, dialog determines the settings to use as follows:
1241
1242           a)  if  environment  variable DIALOGRC is set, its value determines
1243               the name of the configuration file.
1244
1245           b)  if the file in (a) is not found, use the  file  $HOME/.dialogrc
1246               as the configuration file.
1247
1248           c)  if  the  file  in (b) is not found, try using the GLOBALRC file
1249               determined at compile-time, i.e., /etc/dialogrc.
1250
1251           d)  if the file in (c) is not found, use compiled in defaults.
1252
1253       3.  Edit the sample configuration file and copy it to some  place  that
1254           dialog can find, as stated in step 2 above.
1255

KEY BINDINGS

1257       You  can  override  or  add  to key bindings in dialog by adding to the
1258       configuration file.  Dialog's bindkey command maps single keys  to  its
1259       internal coding.
1260
1261              bindkey widget curses_key dialog_key
1262
1263       The  widget  name can be “*” (all widgets), or specific widgets such as
1264       textbox.  Specific widget bindings override the  “*”  bindings.   User-
1265       defined bindings override the built-in bindings.
1266
1267       The curses_key can be expressed in different forms:
1268
1269       •   It may be any of the names derived from curses.h, e.g., “HELP” from
1270           “KEY_HELP”.
1271
1272Dialog also recognizes ANSI control characters such as “^A”,  “^?”,
1273           as well as C1-controls such as “~A” and “~?”.
1274
1275       •   Finally,  dialog  allows  backslash  escapes as in C.  Those can be
1276           octal character values such as “\033” (the ASCII escape character),
1277           or the characters listed in this table:
1278
1279                 Escaped   Actual
1280                 ───────────────────────────────
1281                 \b        backspace
1282                 \f        form feed
1283                 \n        new line (line feed)
1284                 \r        carriage return
1285                 \s        space
1286                 \t        tab
1287                 \^        “^” (caret)
1288                 \?        “?” (question mark)
1289                 \\        “\” (backslash)
1290                 ───────────────────────────────
1291
1292       Dialog's internal keycode names correspond to the DLG_KEYS_ENUM type in
1293       dlg_keys.h, e.g., “HELP” from “DLGK_HELP”.
1294
1295   Widget Names
1296       Some widgets (such as the formbox) have an area  where  fields  can  be
1297       edited.   Those  are managed in a subwindow of the widget, and may have
1298       separate keybindings from the main widget because  the  subwindows  are
1299       registered using a different name.
1300
1301            Widget        Window name   Subwindow Name
1302            ───────────────────────────────────────────
1303            calendar      calendar
1304            checklist     checklist
1305            editbox       editbox       editbox2
1306            form          formbox       formfield
1307            fselect       fselect       fselect2
1308            inputbox      inputbox      inputbox2
1309            menu          menubox       menu
1310            msgbox        msgbox
1311            pause         pause
1312            progressbox   progressbox
1313            radiolist     radiolist
1314            tailbox       tailbox
1315            textbox       textbox       searchbox
1316            timebox       timebox
1317            yesno         yesno
1318            ───────────────────────────────────────────
1319
1320       Some  widgets  are  actually  other widgets, using internal settings to
1321       modify the behavior.  Those use the same  widget  name  as  the  actual
1322       widget:
1323
1324            Widget         Actual Widget
1325            ─────────────────────────────
1326            dselect        fselect
1327            infobox        msgbox
1328            inputmenu      menu
1329            mixedform      form
1330            passwordbox    inputbox
1331            passwordform   form
1332            prgbox         progressbox
1333            programbox     progressbox
1334            tailboxbg      tailbox
1335            ─────────────────────────────
1336
1337   Built-in Bindings
1338       This  manual  page  does  not  list  the  key bindings for each widget,
1339       because that detailed information can be obtained  by  running  dialog.
1340       If  you  have  set  the  --trace  option, dialog writes the key-binding
1341       information for each widget as it is registered.
1342
1343   Example
1344       Normally dialog uses different keys for navigating between the  buttons
1345       and editing part of a dialog versus navigating within the editing part.
1346       That is, tab (and back-tab) traverse buttons (or  between  buttons  and
1347       the  editing part), while arrow keys traverse fields within the editing
1348       part.  Tabs are also  recognized  as  a  special  case  for  traversing
1349       between widgets, e.g., when using multiple tailboxbg widgets.
1350
1351       Some  users  may  wish  to  use  the same key for traversing within the
1352       editing part as for traversing between buttons.   The  form  widget  is
1353       written  to  support this sort of redefinition of the keys, by adding a
1354       special group in dlgk_keys.h for “form”  (left/right/next/prev).   Here
1355       is an example binding demonstrating how to do this:
1356
1357              bindkey formfield TAB  form_NEXT
1358              bindkey formbox   TAB  form_NEXT
1359              bindkey formfield BTAB form_prev
1360              bindkey formbox   BTAB form_prev
1361
1362       That  type  of redefinition would not be useful in other widgets, e.g.,
1363       calendar, due to the potentially large number of fields to traverse.
1364

ENVIRONMENT

1366       DIALOGOPTS     Define this variable to apply any of the common  options
1367                      to  each  widget.   Most of the common options are reset
1368                      before processing each widget.  If you set  the  options
1369                      in  this  environment  variable,  they  are  applied  to
1370                      dialog's state after the  reset.   As  in  the  “--file
1371                      option, double-quotes and backslashes are interpreted.
1372
1373                      The  “--file”  option  is not considered a common option
1374                      (so  you  cannot  embed  it  within   this   environment
1375                      variable).
1376
1377       DIALOGRC       Define  this variable if you want to specify the name of
1378                      the configuration file to use.
1379
1380       DIALOG_CANCEL
1381
1382       DIALOG_ERROR
1383
1384       DIALOG_ESC
1385
1386       DIALOG_EXTRA
1387
1388       DIALOG_HELP
1389
1390       DIALOG_ITEM_HELP
1391
1392       DIALOG_TIMEOUT
1393
1394       DIALOG_OK      Define any of these variables to change the exit code on
1395
1396                      •   Cancel (1),
1397
1398                      •   error (-1),
1399
1400                      •   ESC (255),
1401
1402                      •   Extra (3),
1403
1404                      •   Help (2),
1405
1406                      •   Help with --item-help (2),
1407
1408                      •   Timeout (5), or
1409
1410                      •   OK (0).
1411
1412                      Normally shell scripts cannot distinguish between -1 and
1413                      255.
1414
1415       DIALOG_TTY     Set  this  variable to “1” to provide compatibility with
1416                      older versions of  dialog  which  assumed  that  if  the
1417                      script   redirects   the   standard   output,  that  the
1418--stdout” option was given.
1419

FILES

1421       $HOME/.dialogrc     default configuration file
1422

EXAMPLES

1424       The dialog sources contain several samples of how to use the  different
1425       box  options  and  how  they look.  Just take a look into the directory
1426       samples/ of the source.
1427

DIAGNOSTICS

1429       Exit status is subject to being overridden  by  environment  variables.
1430       The  default  values  and  corresponding environment variables that can
1431       override them are:
1432
1433       0    if the YES or OK button is pressed (DIALOG_OK).
1434
1435       1    if the No or Cancel button is pressed (DIALOG_CANCEL).
1436
1437       2    if the Help button is pressed (DIALOG_HELP),
1438            except as noted below about DIALOG_ITEM_HELP.
1439
1440       3    if the Extra button is pressed (DIALOG_EXTRA).
1441
1442       4    if the Help button is pressed,
1443            and the --item-help option is set
1444            and the DIALOG_ITEM_HELP environment variable is set to 4.
1445
1446            While any of the exit-codes can be  overridden  using  environment
1447            variables,  this  special  case was introduced in 2004 to simplify
1448            compatibility.  Dialog uses  DIALOG_ITEM_HELP(4)  internally,  but
1449            unless  the  environment  variable is also set, it changes that to
1450            DIALOG_HELP(2) on exit.
1451
1452       5    if a timeout expires and the DIALOG_TIMEOUT variable is set to 5.
1453
1454       -1   if errors occur  inside  dialog  (DIALOG_ERROR)  or  dialog  exits
1455            because the ESC key (DIALOG_ESC) was pressed.
1456

PORTABILITY

1458       Dialog  works  with  X/Open curses.  However, some implementations have
1459       deficiencies:
1460
1461          •   HPUX curses (and  perhaps  others)  do  not  open  the  terminal
1462              properly   for  the  newterm  function.   This  interferes  with
1463              dialog's  --input-fd  option,  by  preventing  cursor-keys   and
1464              similar escape sequences from being recognized.
1465
1466          •   NetBSD  5.1  curses  has incomplete support for wide-characters.
1467              dialog will build, but not all examples display properly.
1468

COMPATIBILITY

1470       You may want to write scripts which run with other dialog “clones”.
1471
1472   Original Dialog
1473       First, there is the “original” dialog program to consider (versions 0.3
1474       to 0.9).  It had some misspelled (or inconsistent) options.  The dialog
1475       program maps those deprecated options  to  the  preferred  ones.   They
1476       include:
1477
1478              Option         Treatment
1479              ─────────────────────────────────
1480              --beep-after   ignored
1481              --guage        mapped to --gauge
1482              ─────────────────────────────────
1483
1484   Xdialog
1485       This  is  an  X application, rather than a terminal program.  With some
1486       care, it is possible to  write  useful  scripts  that  work  with  both
1487       Xdialog and dialog.
1488
1489       The  dialog  program  ignores  these  options  which  are recognized by
1490       Xdialog:
1491
1492              Option             Treatment
1493              ───────────────────────────────────────────────
1494              --allow-close      ignored
1495              --auto-placement   ignored
1496              --fixed-font       ignored
1497              --icon             ignored
1498              --keep-colors      ignored
1499              --no-close         ignored
1500              --no-cr-wrap       ignored
1501              --screen-center    ignored
1502              --separator        mapped to --separate-output
1503              --smooth           ignored
1504              --under-mouse      ignored
1505              --wmclass          ignored
1506              ───────────────────────────────────────────────
1507
1508       Xdialog's manpage has  a  section  discussing  its  compatibility  with
1509       dialog.   There  are  some  differences  not shown in the manpage.  For
1510       example, the html documentation states
1511
1512              Note: former Xdialog releases used the “\n”  (line  feed)  as  a
1513              results  separator  for  the  checklist  widget;  this  has been
1514              changed to “/” in Xdialog v1.5.0  to  make  it  compatible  with
1515              (c)dialog.  In your old scripts using the Xdialog checklist, you
1516              will then have to add the --separate-output  option  before  the
1517              --checklist one.
1518
1519       Dialog  has  not  used a different separator; the difference was likely
1520       due to confusion regarding some script.
1521
1522   Whiptail
1523       Then there is whiptail.  For practical purposes, it  is  maintained  by
1524       Debian  (very  little  work  is  done by its upstream developers).  Its
1525       documentation (README.whiptail) claims
1526
1527              whiptail(1) is a lightweight replacement for dialog(1),
1528              to provide dialog boxes for shell scripts.
1529              It is built on the
1530              newt windowing library rather than the ncurses library, allowing
1531              it to be smaller in embedded environments such as installers,
1532              rescue disks, etc.
1533
1534              whiptail is designed to be drop-in compatible with dialog, but
1535              has less features: some dialog boxes are not implemented, such
1536              as tailbox, timebox, calendarbox, etc.
1537
1538       Comparing actual sizes (Debian testing, 2007/1/10): The total of  sizes
1539       for  whiptail,  the  newt,  popt  and  slang  libraries is 757 KB.  The
1540       comparable number for dialog (counting ncurses) is  520 KB.   Disregard
1541       the first paragraph.
1542
1543       The  second  paragraph is misleading, since whiptail also does not work
1544       for common options of dialog, such as the gauge box.  whiptail is  less
1545       compatible with dialog than the original mid-1990s dialog 0.4 program.
1546
1547       whiptail's  manpage borrows features from dialog, e.g., but oddly cites
1548       only dialog versions up to 0.4  (1994)  as  a  source.   That  is,  its
1549       manpage  refers  to  features  which  were  borrowed  from  more recent
1550       versions of dialog, e.g.,
1551
1552--gauge (from 0.5)
1553
1554--passwordbox (from Debian changes in 1999),
1555
1556--default-item (from dialog 2000/02/22),
1557
1558--output-fd (from dialog 2002/08/14).
1559
1560       Somewhat humorously, one may note that the popt  feature  (undocumented
1561       in its manpage) of using a “--” as an escape was documented in dialog's
1562       manpage about a year before it was  mentioned  in  whiptail's  manpage.
1563       whiptail's  manpage  incorrectly  attributes  that  to  getopt  (and is
1564       inaccurate anyway).
1565
1566       Debian uses whiptail for the official dialog variation.
1567
1568       The dialog program ignores or maps these options which  are  recognized
1569       by whiptail:
1570
1571              Option            Treatment
1572              ───────────────────────────────────────────
1573              --cancel-button   mapped to --cancel-label
1574              --fb              ignored
1575              --fullbutton      ignored
1576              --no-button       mapped to --no-label
1577              --nocancel        mapped to --no-cancel
1578              --noitem          mapped to --no-items
1579              --notags          mapped to --no-tags
1580              --ok-button       mapped to --ok-label
1581              --scrolltext      mapped to --scrollbar
1582              --topleft         mapped to --begin 0 0
1583              --yes-button      mapped to --yes-label
1584              ───────────────────────────────────────────
1585
1586       There  are  visual  differences which are not addressed by command-line
1587       options:
1588
1589dialog centers lists within the window.   whiptail  typically  puts
1590           lists against the left margin.
1591
1592whiptail  uses  angle  brackets  (“<” and “>”) for marking buttons.
1593           dialog uses square brackets.
1594
1595whiptail marks the limits of subtitles with vertical bars.   dialog
1596           does not mark the limits.
1597
1598whiptail  attempts to mark the top/bottom cells of a scrollbar with
1599           up/down arrows.  When it cannot do this, it fills those cells  with
1600           the  background  color  of  the  scrollbar  and confusing the user.
1601           dialog uses the entire  scrollbar  space,  thereby  getting  better
1602           resolution.
1603

BUGS

1605       Perhaps.
1606

AUTHOR

1608       Thomas E. Dickey (updates for 0.9b and beyond)
1609

CONTRIBUTORS

1611       Kiran Cherupally – the mixed form and mixed gauge widgets.
1612
1613       Tobias C. Rittweiler
1614
1615       Valery Reznic – the form and progressbox widgets.
1616
1617       Yura Kalinichenko adapted the gauge widget as “pause”.
1618
1619       This  is  a  rewrite (except as needed to provide compatibility) of the
1620       earlier version of dialog 0.9a, which lists as authors:
1621
1622       •   Savio Lam – version 0.3, “dialog”
1623
1624       •   Stuart Herbert – patch for version 0.4
1625
1626       •   Marc Ewing – the gauge widget.
1627
1628       •   Pasquale De Marco “Pako” – version 0.9a, “cdialog”
1629
1630
1631
1632$Date: 2021/12/13 22:35:33 $                                         DIALOG(1)
Impressum