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

NAME

6       dialog - display dialog boxes from shell scripts
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

RUN-TIME CONFIGURATION

1167       1.  Create a sample configuration file by typing:
1168
1169              dialog --create-rc file
1170
1171       2.  At start, dialog determines the settings to use as follows:
1172
1173           a)  if environment variable DIALOGRC is set, its  value  determines
1174               the name of the configuration file.
1175
1176           b)  if  the  file in (a) is not found, use the file $HOME/.dialogrc
1177               as the configuration file.
1178
1179           c)  if the file in (b) is not found, try using  the  GLOBALRC  file
1180               determined at compile-time, i.e., /etc/dialogrc.
1181
1182           d)  if the file in (c) is not found, use compiled in defaults.
1183
1184       3.  Edit  the  sample configuration file and copy it to some place that
1185           dialog can find, as stated in step 2 above.
1186

KEY BINDINGS

1188       You can override or add to key bindings in dialog by adding to the con‐
1189       figuration  file.  Dialog's bindkey command maps single keys to its in‐
1190       ternal coding.
1191
1192              bindkey widget curses_key dialog_key
1193
1194       The widget name can be "*" (all widgets), or specific widgets  such  as
1195       textbox.  Specific widget bindings override the "*" bindings.  User-de‐
1196       fined bindings override the built-in bindings.
1197
1198       The curses_key can be any of the names  derived  from  curses.h,  e.g.,
1199       “HELP” from “KEY_HELP”.  Dialog also recognizes ANSI control characters
1200       such as "^A", "^?", as well as C1-controls such as "~A" and "~?".   Fi‐
1201       nally, it allows any single character to be escaped with a backslash.
1202
1203       Dialog's internal keycode names correspond to the DLG_KEYS_ENUM type in
1204       dlg_keys.h, e.g., “HELP” from “DLGK_HELP”.
1205
1206   Widget Names
1207       Some widgets (such as the formbox) have an area  where  fields  can  be
1208       edited.   Those  are managed in a subwindow of the widget, and may have
1209       separate keybindings from the main widget because  the  subwindows  are
1210       registered using a different name.
1211
1212                     Widget        Window name   Subwindow Name
1213                     ───────────────────────────────────────────
1214                     calendar      calendar
1215                     checklist     checklist
1216                     editbox       editbox       editbox2
1217                     form          formbox       formfield
1218                     fselect       fselect       fselect2
1219                     inputbox      inputbox      inputbox2
1220                     menu          menubox       menu
1221                     msgbox        msgbox
1222                     pause         pause
1223                     progressbox   progressbox
1224                     radiolist     radiolist
1225                     tailbox       tailbox
1226                     textbox       textbox       searchbox
1227                     timebox       timebox
1228                     yesno         yesno
1229                     ───────────────────────────────────────────
1230
1231       Some  widgets  are  actually  other widgets, using internal settings to
1232       modify the behavior.  Those use the same widget name as the actual wid‐
1233       get:
1234
1235                            Widget         Actual Widget
1236                            ─────────────────────────────
1237                            dselect        fselect
1238                            infobox        msgbox
1239                            inputmenu      menu
1240                            mixedform      form
1241                            passwordbox    inputbox
1242                            passwordform   form
1243                            prgbox         progressbox
1244                            programbox     progressbox
1245                            tailboxbg      tailbox
1246                            ─────────────────────────────
1247
1248   Built-in Bindings
1249       This  manual  page  does not list the key bindings for each widget, be‐
1250       cause that detailed information can be obtained by running dialog.   If
1251       you have set the --trace option, dialog writes the key-binding informa‐
1252       tion for each widget as it is registered.
1253
1254   Example
1255       Normally dialog uses different keys for navigating between the  buttons
1256       and editing part of a dialog versus navigating within the editing part.
1257       That is, tab (and back-tab) traverse buttons (or  between  buttons  and
1258       the  editing part), while arrow keys traverse fields within the editing
1259       part.  Tabs are also recognized as a special case  for  traversing  be‐
1260       tween widgets, e.g., when using multiple tailboxbg widgets.
1261
1262       Some users may wish to use the same key for traversing within the edit‐
1263       ing part as for traversing between buttons.  The form widget is written
1264       to  support  this sort of redefinition of the keys, by adding a special
1265       group in dlgk_keys.h for “form” (left/right/next/prev).  Here is an ex‐
1266       ample binding demonstrating how to do this:
1267
1268              bindkey formfield TAB  form_NEXT
1269              bindkey formbox   TAB  form_NEXT
1270              bindkey formfield BTAB form_prev
1271              bindkey formbox   BTAB form_prev
1272
1273       That  type  of redefinition would not be useful in other widgets, e.g.,
1274       calendar, due to the potentially large number of fields to traverse.
1275

ENVIRONMENT

1277       DIALOGOPTS     Define this variable to apply any of the common  options
1278                      to  each  widget.   Most of the common options are reset
1279                      before processing each widget.  If you set  the  options
1280                      in  this  environment variable, they are applied to dia‐
1281                      log's state after the reset.  As in the "--file" option,
1282                      double-quotes and backslashes are interpreted.
1283
1284                      The  "--file"  option  is not considered a common option
1285                      (so you cannot embed it within  this  environment  vari‐
1286                      able).
1287
1288       DIALOGRC       Define  this variable if you want to specify the name of
1289                      the configuration file to use.
1290
1291       DIALOG_CANCEL
1292
1293       DIALOG_ERROR
1294
1295       DIALOG_ESC
1296
1297       DIALOG_EXTRA
1298
1299       DIALOG_HELP
1300
1301       DIALOG_ITEM_HELP
1302
1303       DIALOG_OK      Define any of these variables to change the exit code on
1304                      Cancel  (1), error (-1), ESC (255), Extra (3), Help (2),
1305                      Help with --item-help (2), or OK  (0).   Normally  shell
1306                      scripts cannot distinguish between -1 and 255.
1307
1308       DIALOG_TTY     Set  this  variable to “1” to provide compatibility with
1309                      older versions of  dialog  which  assumed  that  if  the
1310                      script  redirects  the standard output, that the "--std‐
1311                      out" option was given.
1312

FILES

1314       $HOME/.dialogrc     default configuration file
1315

EXAMPLES

1317       The dialog sources contain several samples of how to use the  different
1318       box  options  and  how  they look.  Just take a look into the directory
1319       samples/ of the source.
1320

DIAGNOSTICS

1322       Exit status is subject to being overridden  by  environment  variables.
1323       The  default  values  and  corresponding environment variables that can
1324       override them are:
1325
1326       0    if the YES or OK button is pressed (DIALOG_OK).
1327
1328       1    if the No or Cancel button is pressed (DIALOG_CANCEL).
1329
1330       2    if the Help button is pressed (DIALOG_HELP),
1331            except as noted below about DIALOG_ITEM_HELP.
1332
1333       3    if the Extra button is pressed (DIALOG_EXTRA).
1334
1335       4    if the Help button is pressed,
1336            and the --item-help option is set
1337            and the DIALOG_ITEM_HELP environment variable is set to 4.
1338
1339            While any of the exit-codes can be  overridden  using  environment
1340            variables,  this  special  case was introduced in 2004 to simplify
1341            compatibility.  Dialog uses  DIALOG_ITEM_HELP(4)  internally,  but
1342            unless  the  environment  variable is also set, it changes that to
1343            DIALOG_HELP(2) on exit.
1344
1345       -1   if errors occur inside dialog (DIALOG_ERROR) or dialog  exits  be‐
1346            cause the ESC key (DIALOG_ESC) was pressed.
1347

PORTABILITY

1349       Dialog  works  with  X/Open curses.  However, some implementations have
1350       deficiencies:
1351
1352          ·   HPUX curses (and perhaps others) do not open the terminal  prop‐
1353              erly  for  the  newterm function.  This interferes with dialog's
1354              --input-fd option, by preventing cursor-keys and similar  escape
1355              sequences from being recognized.
1356
1357          ·   NetBSD  5.1  curses  has incomplete support for wide-characters.
1358              dialog will build, but not all examples display properly.
1359

COMPATIBILITY

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

BUGS

1496       Perhaps.
1497

AUTHOR

1499       Thomas E. Dickey (updates for 0.9b and beyond)
1500

CONTRIBUTORS

1502       Kiran Cherupally – the mixed form and mixed gauge widgets.
1503
1504       Tobias C. Rittweiler
1505
1506       Valery Reznic – the form and progressbox widgets.
1507
1508       Yura Kalinichenko adapted the gauge widget as “pause”.
1509
1510       This  is  a  rewrite (except as needed to provide compatibility) of the
1511       earlier version of dialog 0.9a, which lists as authors:
1512
1513       ·   Savio Lam – version 0.3, “dialog”
1514
1515       ·   Stuart Herbert – patch for version 0.4
1516
1517       ·   Marc Ewing – the gauge widget.
1518
1519       ·   Pasquale De Marco “Pako” – version 0.9a, “cdialog”
1520
1521
1522
1523$Date: 2018/06/19 00:26:13 $                                         DIALOG(1)
Impressum