DIALOG(1)                                               DIALOG(1)

NAME
       dialog - display dialog boxes from shell scripts

SYNOPSIS
       dialog --clear
       dialog --create-rc file
       dialog  [  --title  title  ]  [  --backtitle backtitle ] [
       --clear ] [ --separate-output ] 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. Currently, these types of dialog  boxes  are
       implemented:

       yes/no  box,  menu  box, input box, message box, text box,
       info box, checklist box, radiolist box, and gauge box.

OPTIONS
       --clear
              The screen will be cleared to the screen  attribute
              on exit.

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

       --separate-output
              For  checklist widgets, output result one line at a
              time, with no quoting.  This facilitates parsing by
              another program.

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

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

       Box Options

       --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 be fitted  in  one  line,  it
              will  be  automatically divided into multiple lines
              at appropriate places. The  text  string  may  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.

       --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.

       --infobox text height width
              An info box is basically a message  box.   However,
              in  this  case,  dialog will exit immediately after
              displaying the message to the user. The  screen  is
              not  cleared when dialog exits, so that the message
              will remain on the screen until the  calling  shell
              script  clears  it  later.  This is useful when you
              want to inform the user that  some  operations  are
              carrying on that may require some time to finish.

       --inputbox text height width [init]
              An  input  box is useful when you want to ask ques-
              tions that require the user to input  a  string  as
              the  answer. If init is supplied it is used to ini-
              tialize  the  input  string.   When  inputing   the
              string,  the  BACKSPACE  key can be used to correct
              typing errors. If the input string is  longer  than
              can  be  fitted  in the dialog box, the input field
              will be scrolled. On exit, the input string will be
              printed on stderr.

       --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 horizontally. For
              more convenience, forward  and  backward  searching
              functions are also provided.

       --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. Each
              menu entry consists of a tag  string  and  an  item
              string.  The  tag gives the entry a name to distin-
              guish it from the other entries in  the  menu.  The
              item  is a short description of the option that the
              entry represents. 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.

       --checklist text height width list-height [ tag item
              status ] ...
              A  checklist  box  is similar to a menu box in that
              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.

       --radiolist text height width list-height  [ tag  item
              status  ] ...
              A radiolist box is similar to a menu box.  The only
              difference  is that you can indicate which entry is
              currently selected, by setting its status to on.

       --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.

RUN-TIME CONFIGURATION
       1.  Create a sample configuration file by typing:

                 "dialog --create-rc <file>"

       2.  At start, dialog determines the  settings  to  use  as
           follows:

           a)  if  environment  variable  DIALOGRC  is  set, it's
               value determines the  name  of  the  configuration
               file.

           b)  if  the  file  in (a) can't be found, use the file
               $HOME/.dialogrc as the configuration file.

           c)  if the file in (b) can't be 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.

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

FILES
       $HOME/.dialogrc     default configuration file

DIAGNOSTICS
       Exit  status  is 0 if dialog is exited by pressing the Yes
       or OK button, and 1 if the No or Cancel button is pressed.
       Otherwise,  if  errors  occur  inside  dialog or dialog is
       exited by pressing the ESC key, the exit status is -1.

BUGS
       Text files containing tab characters  may  cause  problems
       with text box.  Tab characters in text files must first be
       expanded to spaces before being displayed by text box.

       Screen update is too slow.

AUTHOR
       Savio Lam (lam836@cs.cuhk.hk) - version 0.3

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

Dialog Version 0.6         10 June 1994                         1