gdialog



gdialog(1)                                                          gdialog(1)




NAME

       gdialog - display dialog boxes from shell scripts


SYNOPSIS

       gdialog --clear
       gdialog --create-rc file
       gdialog  [  --title  title  ]  [  --backtitle backtitle ] [ --clear ] [
       --separate-output ] box-options


DESCRIPTION

       Gdialog is a program that will let you to present a  variety  of  ques-
       tions  or display messages using dialog boxes from a shell script. Cur-
       rently, 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.

       This program is much like the dialog program, but along with displaying
       textual dialog boxes if the environment variable DISPLAY is  unset,  if
       the  environment variable is set it will instead display graphical dia-
       log boxes using gtk/gnome.



OPTIONS

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

       --create-rc file
              Since gdialog 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 dia-
              log 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  appro-
              priate  places.  The text string may also contain the sub-string
              "\n" or newline characters `\n' to control line breaking explic-
              itly.   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 differ-
              ence  between  a  message box and a yes/no box is that a message
              box has only a single OK button. 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 questions that
              require the user to input a string as the  answer.  If  init  is
              supplied it is used to initialize the input string.  When input-
              ing 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  distinguish  it
              from the other entries in the menu. The item is a short descrip-
              tion 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  mul-
              tiple entries presented in the form of a menu. Instead of choos-
              ing 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 spec-
              ified 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 integer 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


SEE ALSO

       dialog(1), whiptail (1)



gnome-utils 1.4.0                 Apr 21 2001                       gdialog(1)

Man(1) output converted with man2html