dialog - display dialog boxes from shell scripts


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.

              The  screen will be cleared to the screen attribute
              on exit.  This may be  used  alone,  without  other
              options.

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

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

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

       --item-help
              Interpret  the  tags  data for checklist, radiolist
              and menuboxes adding a column which is displayed in
              the  bottom  line  of the screen, for the currently
              selected item.

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

       --no-cancel

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

              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
              time, with no quoting.  This facilitates parsing by
              another program.

       --separate-widget string
              Specify  a  string that will separate the output on
              standard error from each widget.  This is  used  to
              simplify  parsing  the result of a dialog with sev­
              eral widgets.

       --shadow
              Draw a shadow to the right and bottom of each  dia­
              log box.

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


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

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

              Other parameters depend on the box type.

       --calendar text height width day month year
              A calendar box displays month, day and year in sep­
              arately  adjustable  windows.  You can increment or
              decrement any of those using the left-, up-, right-
              and  down-arrows.   Use  tab  or  backtab  to  move
              between windows.  If the year is given as zero, the
              current date is used as an initial value.  On exit,
              the date is printed in the form day/month/year.

       --checklist text height width list-height [ tag item
              status ] ...
              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.

              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.

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

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

              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.

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

       --tailbox file height width
              Display text from a file in a dialog box, as  in  a
              "tail -f" command.

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

              Display text from a file in a dialog box in a back­
              ground process, as in a "tail -f &" command.

       --timebox text height [width hour minute second]
              A dialog is displayed which allows  you  to  select
              hour,  minute  and  second.   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 be fitted  in  one  line,  it
              will  be  automatically divided into multiple lines
              at appropriate 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.


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, its value
               determines the name of the configuration file.

           b)  if  the  file  in  (a)  is not found, use the file
               $HOME/.dialogrc as the configuration file.

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


FILES

       $HOME/.dialogrc     default configuration file

       Exit status is

       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

       Pako (demarco_p@abramo.it) - version 0.9a, "cdialog",

       Thomas Dickey (updates for 0.9b)


Man(1) output converted with man2html