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


       --guage text height width percent
	      A guage 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 guage 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.4	   10 June 1994				4


