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

RUN-TIME CONFIGURATION

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

KEY BINDINGS

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

ENVIRONMENT

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

FILES

1415       $HOME/.dialogrc     default configuration file
1416

EXAMPLES

1418       The dialog sources contain several samples of how to use the  different
1419       box  options  and  how  they look.  Just take a look into the directory
1420       samples/ of the source.
1421

DIAGNOSTICS

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

PORTABILITY

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

COMPATIBILITY

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

BUGS

1599       Perhaps.
1600

AUTHOR

1602       Thomas E. Dickey (updates for 0.9b and beyond)
1603

CONTRIBUTORS

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