Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
DIALOG(1)               FreeBSD General Commands Manual              DIALOG(1)

NAME
       dialog - display dialog boxes from shell scripts

SYNOPSIS
       dialog --clear
       dialog --create-rc file
       dialog [ --title title ] [ --clear ] [ --hline line ] [ --hfile file ]
       box-options

DESCRIPTION
       Dialog is a program which allows you to present a variety of questions
       or display messages in dialog box form from a shell script.  The
       following types of dialog objects are currently supported:

       yes/no box, menu box, input box, message box, text box, info box,
       checklist box, program box, ftree and tree boxes.

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.

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

       --hline line
              Specifies a line string to be displayed at the bottom of the
              dialog box.

       --hfile file
              Specifies a file to be displayed by pressing ? or F1.

       Box Options

       --yesno text height width [ yes | no ]
              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 the
              appropriate points. 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.  A Yes button is selected by
              default unless no is specified.

       --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 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
              An input box is useful when you want to ask questions that
              require the user to input a string as the answer. 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 distinguish 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.

       --prgbox command height width
              A program box lets you display output of command in dialog box.

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

       --ftree file FS text height width menu-height
              ftree box is a dialog box showing the tree described by the data
              from the file file.  The data in the file should look like
              find(1)  output. For the find output, the field separator FS
              will be '/'. If height and width are positive numbers, they set
              the absolute size of the whole ftree box. If height and width
              are negative numbers, the size of the ftree box will be selected
              automatically.  menu-height sets the height of the tree
              subwindow inside the ftree box and must be set.  text is shown
              inside the ftree box above the tree subwindow and can contain
              newline characters '\n' to split lines. One can navigate in the
              tree by pressing UP/DOWN or '+'/'-', PG_UP/PG_DOWN or 'b'/SPACE
              and HOME/END or 'g'/'G'.  A leaf of the tree is selected by
              pressing TAB or LEFT/RIGHT the OK button and pressing ENTER.
              The selected leaf (to be more exact, the full path to it from
              the root of the tree) is printed to stderr.  If Cancel and then
              ENTER is pressed, nothing is printed to stderr.  file may
              contain data like find(1) output, as well as like the output of
              find(1) with -d option. Some of the transient paths to the
              leaves of the tree may be absent. Such data is corrected when
              fed from file.

       --tree FS text height width menu-height [ item ] ...
              tree box is like ftree box with some exceptions. First, the data
              is not entered from a file, but from the command line as item
              item ...  Second, the data thus entered is not corrected in any
              way.  Thus, the data like the output of find(1) with -d option
              will look incorrectly.

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

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

SEE ALSO
       dialog(3)

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.

       The ftree and tree boxes do not allow the tree to be moved to the left
       or to the right. Thus, if there are many levels of data, some of the
       leaves can be rendered invisible. A standard display with 80 characters
       allows for 17 levels to be visible. Deeper levels are invisible.
       However, the navigation in the tree and selection of leaves do work.

AUTHOR
       Savio Lam (lam836@cs.cuhk.hk)

       Changes by Anatoly A. Orehovsky (tolik@mpeks.tomsk.su) (ftree and tree
       boxes)

                                2 October 1998                       DIALOG(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | RUN-TIME CONFIGURATION | ENVIRONMENT | FILES | DIAGNOSTICS | SEE ALSO | BUGS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dialog&sektion=1&manpath=FreeBSD+7.0-RELEASE>

home | help