## SYNOPSIS

           dialog --clear
           dialog --create-rc file
           dialog --print-maxsize
           dialog common-options box-options

## DESCRIPTION

           Dialog is a program that will let you to present a variety
           of questions or display messages using dialog boxes from a
           shell script.  These types of dialog boxes are implemented
           (though not all are necessarily compiled into dialog):

                  calendar,  checklist,  fselect,   gauge,   infobox,
                  inputbox,  menu,  msgbox (message), password, radi
                  olist, tailbox, tailboxbg,  textbox,  timebox,  and
                  yesno (yes/no).

           You can put more than one dialog box into a script:

           -    Use the --and-widget token to force Dialog to proceed
                to the next dialog unless you  have  pressed  ESC  to
                cancel, or

           -    Simply add the tokens for the next dialog box, making
                a chain.  Dialog stops chaining when the return  code
                from a dialog is nonzero, e.g., Cancel or No.

## OPTIONS

           Common Options

           --aspect ratio
                  This gives you some control over the box dimensions
                  when using auto sizing (specifying 0 for height and
                  width).  It represents width / height.  The default
                  is 9, which means 9 characters wide to every 1 line
                  high.

           --backtitle backtitle
                  Specifies a backtitle string to be displayed on the
                  backdrop, at the top of the screen.

           --beep Sound the audible alarm each  time  the  screen  is
                  refreshed.

           --beep-after
                  Beep if input is interrupted, e.g., by a control/C.

           --begin y x
                  Specify the position of the upper left corner of  a
                  dialog box on the screen.

           --cancel-label string
                  'r',  reset by 'R'.  Underline is set by 'u', reset
                  by  'U'.   The  settings  are   cumulative,   e.g.,
                  "\Zb\Z1"  makes  the  following  text  bright  red.
                  Restore normal settings with "\Zn".

           --cr-wrap
                  Interpret embedded newlines in the dialog text as a
                  newline on the screen.  Otherwise, dialog will only
                  wrap lines where needed to fit inside the text box.
                  Even  though you can control line breaks with this,
                  dialog will still wrap any lines that are too  long
                  for  the  width  of  the box.  Without cr-wrap, the
                  layout of your text may be formatted to  look  nice
                  in the source code of your script without affecting
                  the way it will look in the dialog.

           --create-rc file
                  When dialog supports run-time  configuration,  this
                  can  be used to dump a sample configuration file to
                  the file specified by file.

           --defaultno
                  Make the default value of the yes/no box a No.

           --default-item string
                  Set the default item in a menu box.   Normally  the
                  first item in the box is the default.

           --exit-label string
                  Override the label used for "EXIT" buttons.

           --extra-button
                  Show  an  extra  button, between ok/cancel and help
                  buttons.

           --extra-label string
                  Override the label used for "Extra" buttons.

           --help Prints the help message  to  standard  error.   The
                  help message is printed if no options are given.

           --help-button
                  Show  a  help-button after ok/cancel buttons, i.e.,
                  in checklist, radiolist and menu boxes.  If --item-
                  help  is also given, on exit the return status will
                  be the same as for the "Ok" button, and  the  item-
                  help  text  will be written to standard error after
                  the token "HELP".   Otherwise,  the  return  status
                  will indicate that the Help button was pressed, and
                  no message printed.

           --max-input size
                  Limit input strings to  the  given  size.   If  not
                  specified, the limit is 2000.

           --no-cancel

           --nocancel
                  Suppress the "Cancel" button in checklist, inputbox
                  and menu box modes.  A script can still test if the
                  user pressed the ESC key to cancel to quit.

           --no-collapse
                  Normally dialog converts tabs to spaces and reduces
                  multiple spaces to a single space for text which is
                  displayed in a message boxes, etc.  Use this option
                  to disable that feature.   Note  that  dialog  will
                  still wrap text, subject to the --cr-wrap option.

           --no-kill
                  Tells  dialog to put the tailboxbg box in the back
                  ground, printing its process id to standard  error.
                  SIGHUP is disabled for the background process.

           --no-shadow
                  Suppress  shadows  that would be drawn to the right
                  and bottom of each dialog box.

           --ok-label string
                  Override the label used for "OK" buttons.

           --output-fd fd
                  Direct output to the given file  descriptor.   Most
                  dialog  scripts  write  to  the standard error, but
                  error messages may also be written there, depending
                  on your script.

           --print-maxsize
                  Print  the  maximum size of dialog boxes, i.e., the
                  screen size, to the standard error.   This  may  be
                  used alone, without other options.

           --print-size
                  Prints  the  size  of  each  dialog box to standard
                  error.

           --print-version
                  Prints dialog's version to  standard  error.   This
                  may be used alone, without other options.

           --separate-output
                  For  checklist widgets, output result one line at a

           --size-err
                  Check the resulting size of  a  dialog  box  before
                  trying to use it, printing the resulting size if it
                  is larger than the screen.  (This option  is  obso
                  lete, since all new-window calls are checked).

           --sleep secs
                  Sleep (delay) for the given number of seconds after
                  processing a dialog box.

           --stderr
                  Direct output to the standard error.  This  is  the
                  default,   since   curses  normally  writes  screen
                  updates to the standard output.

           --stdout
                  Direct output to the standard output.

           --tab-correct
                  Convert each tab character to one or  more  spaces.
                  Otherwise,  tabs  are  rendered  according  to  the
                  curses library's interpretation.

           --tab-len n
                  Specify the number of spaces that a  tab  character
                  occupies  if  the  "--tab-correct" option is given.
                  The default is 8.

           --timeout secs
                  Timeout (exit with error code) if no user  response
                  within the given number of seconds.

           --title title
                  Specifies a title string to be displayed at the top
                  of the dialog box.

           --trim eliminate leading blanks, trim literal newlines and
                  repeated blanks from message text.

           --version
                  Same as "--print-version".

           Box Options
                  All dialog boxes have at least three parameters:

                  text the caption or contents of the box.

                  height
                       the height of the dialog box.

                  width
                       the width of the dialog box.

                  date is printed in the form day/month/year.

           --checklist  text height width list-height [ tag item sta
           tus ] ...
                  A checklist box is similar to a menu box; there are
                  multiple entries presented in the form of  a  menu.
                  Instead  of  choosing  one entry among the entries,
                  each entry can be turned on or  off  by  the  user.
                  The initial on/off state of each entry is specified
                  by status.  On exit, a list of the tag  strings  of
                  those entries that are turned on will be printed on
                  stderr.

           --fselect  filepath height width
                  The file-selection  dialog  displays  a  text-entry
                  window  in which you can type a filename (or direc
                  tory), and above that two  windows  with  directory
                  names and filenames.

                  Here  filepath  can be a filepath in which case the
                  file and directory windows will  display  the  con
                  tents  of  the  path and the text-entry window will
                  contain the preselected filename.

                  Use tab or arrow keys to move between the  windows.
                  Within  the  directory or filename windows, use the
                  up/down arrow keys to scroll the current selection.
                  Use  the  space-bar  to  copy the current selection
                  into the text-entry window.

                  Typing any printable characters switches  focus  to
                  the  text-entry  window, entering that character as
                  well as scrolling the directory and  filename  win
                  dows to the closest match.

                  Use  a carriage return or the "OK" button to accept
                  the current value in the text-entry window, or  the
                  "Cancel" button to cancel.

           --gauge text height width [percent]
                  A  gauge  box  displays a meter along the bottom of
                  the box.  The meter indicates the percentage.   New
                  percentages are read from standard input, one inte
                  ger per line.  The meter is updated to reflect each
                  new  percentage.   If stdin is XXX, then subsequent
                  lines up to another XXX are used for a new  prompt.
                  The gauge exits when EOF is reached on stdin.

                  The  percent  value  denotes the initial percentage
                  shown in the meter.  If not specified, it is  zero.

                  tialize   the  input  string.   When  entering  the
                  string, the BACKSPACE key can be  used  to  correct
                  typing  errors.  If the input string is longer than
                  can fit in the dialog box, the input field will  be
                  scrolled.   On  exit,  the  input  string  will  be
                  printed on stderr.

           --menu text height width menu-height [ tag item ] ...
                  As its name suggests, a menu box is  a  dialog  box
                  that  can  be  used to present a list of choices in
                  the form of a menu for the user to choose.  Choices
                  are  displayed in the order given.  Each menu entry
                  consists of a tag string and an item  string.   The
                  tag  gives  the entry a name to distinguish it from
                  the other entries in the menu.  The item is a short
                  description  of  the  option  that the entry repre
                  sents.  The user can move between the menu  entries
                  by  pressing  the UP/DOWN keys, the first letter of
                  the tag as a hot-key, or the number keys 1-9. There
                  are  menu-height  entries  displayed in the menu at
                  one time, but the menu will be  scrolled  if  there
                  are more entries than that.  When dialog exits, the
                  tag of the chosen menu entry  will  be  printed  on
                  stderr.   If the --help-button option is given, the
                  corresponding help text will be printed if the user
                  selects the help button.

           --msgbox text height width
                  A message box is very similar to a yes/no box.  The
                  only difference between a message box and a  yes/no
                  box is that a message box has only a single OK but
                  ton.  You can use this dialog box  to  display  any
                  message  you  like.  After reading the message, the
                  user can press the ENTER key so  that  dialog  will
                  exit  and the calling shell script can continue its
                  operation.

           --passwordbox text height width [init]
                  A password box is similar to an input  box,  except
                  that  the  text  the  user enters is not displayed.
                  This is useful  when  prompting  for  passwords  or
                  other sensitive information.  Be aware that if any
                  thing is passed in "init", it will  be  visible  in
                  the  system's  process  table  to  casual snoopers.
                  Also, it is very confusing to the user  to  provide
                  them  with a default password they cannot see.  For
                  these reasons, using "init" is highly  discouraged.

           --radiolist text height width list-height  [ tag item sta
           tus ] ...
                  A radiolist box is similar to a menu box.  The only
                  difference is that you can indicate which entry  is
                  the  tailboxbg widgets in the same process, polling
                  for updates.  You may use a tab to traverse between
                  the widgets on the screen, and close them individu
                  ally, e.g., by pressing ENTER.  Once the  non-tail
                  boxbg  widgets  are  closed, dialog forks a copy of
                  itself into the background, and prints its  process
                  id if the --no-kill option is given.

                  NOTE:  Older  versions of dialog forked immediately
                  and attempted to update  the  screen  individually.
                  Besides  being  bad for performance, it was unwork
                  able.  Some older scripts  may  not  work  properly
                  with the polled scheme.

           --textbox file height width
                  A  text box lets you display the contents of a text
                  file in a dialog box.  It is  like  a  simple  text
                  file viewer.  The user can move through the file by
                  using the  UP/DOWN,  PGUP/PGDN  and  HOME/END  keys
                  available  on most keyboards.  If the lines are too
                  long to be displayed in  the  box,  the  LEFT/RIGHT
                  keys can be used to scroll the text region horizon
                  tally.  You may also use vi-style keys h, j,  k,  l
                  in place of the cursor keys, and B or N in place of
                  the pageup/pagedown keys.   For  more  convenience,
                  vi-style  forward  and backward searching functions
                  are also provided.

           --timebox text height [width hour minute second]
                  A dialog is displayed which allows  you  to  select
                  hour,  minute  and second.  If the values for hour,
                  minute or second are missing or negative, the  cur
                  rent date's corresponding values are used.  You can
                  increment or  decrement  any  of  those  using  the
                  left-,  up-,  right-  and  down-arrows.  Use tab or
                  backtab to move  between  windows.   On  exit,  the
                  result is printed in the form hour:minute:second.

           --yesno text height width
                  A  yes/no  dialog  box of size height rows by width
                  columns will be displayed.  The string specified by
                  text  is  displayed inside the dialog box.  If this
                  string is too long to fit in one line, it  will  be
                  automatically divided into multiple lines at appro
                  priate places.  The text string  can  also  contain
                  the  sub-string  "\n" or newline characters `\n´ to
                  control line breaking explicitly.  This dialog  box
                  is  useful  for  asking  questions that require the
                  user to answer either yes or no.   The  dialog  box
                  has a Yes button and a No button, in which the user
                  can switch between by pressing the TAB key.

               c)  if  the  file  in  (b) is not found, try using the
                   GLOBALRC file determined  at  compile-time,  i.e.,
                   /etc/dialogrc.

               d)  if  the  file in (c) is not found, use compiled in
                   defaults.

           3.  Edit the sample configuration file and copy it to some
               place that dialog can find, as stated in step 2 above.

## ENVIRONMENT

           DIALOGRC       Define this variable if you want to specify
                          the  name of the configuration file to use.

           DIALOG_CANCEL

           DIALOG_ERROR

           DIALOG_ESC

           DIALOG_EXTRA

           DIALOG_HELP

           DIALOG_OK      Define any of these variables to change the
                          exit  code  on  Cancel (1), error (-1), ESC
                          (255), Extra (3),  Help  (2),  or  Ok  (0).
                          Normally  shell  scripts cannot distinguish
                          between -1 and 255.

## FILES

           $HOME/.dialogrc     default configuration file

## DIAGNOSTICS

           Exit status is subject to being overridden by  environment
           variables.  Normally they are:

           0    if dialog is exited by pressing the Yes or OK button.

           1    if the No or Cancel button is pressed.

           -1   if errors occur inside dialog or dialog is exited  by
                pressing the ESC key.

## BUGS

           Perhaps.

## AUTHOR

           Savio Lam (lam836@cs.cuhk.hk) - version 0.3, "dialog"

           Stuart  Herbert  (S.Herbert@sheffield.ac.uk)  -  patch for
           version 0.4