dialog(1): dialog boxes from shell scripts

NAME

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, form, fselect, gauge, infobox, inputbox, inputmenu, menu, msgbox (message), password, pause, radiolist, 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 (see DIAGNOSTICS).

Some widgets, e.g., checklist, will write text to dialog's output. Normally that is the standard error, but there are options for changing this: "--output-fd", "--stderr" and "--stdout". No text is written if the Cancel button (or ESC) is pressed; dialog exits immediately in that case.

OPTIONS

All options begin with "--" (two ASCII hyphens, for the benefit of those using systems with deranged locale support).

A "--" by itself is used as an escape, i.e., the next token on the command-line is not treated as an option.

dialog --title -- --Not an option

The "--args" option tells dialog to list the command-line parameters to the standard error. This is useful when debugging complex scripts using the "--" and "--file", since the command-line may be rewritten as these are expanded.

The "--file" option tells dialog to read parameters from the file named as its value.

dialog --file parameterfile

Blanks not within double-quotes are discarded (use backslashes to quote single characters). The result is inserted into the command-line, replacing "--file" and its option value. Interpretation of the command-line resumes from that point.

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

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

--begin y x

Specify the position of the upper left corner of a dialog box on the screen.

--cancel-label string

Override the label used for "Cancel" buttons.

--clear

Clears the widget screen, keeping only the screen_color background. Use this when you combine widgets with "--and-widget" to erase the contents of a previous widget on the screen, so it won't be seen under the contents of a following widget. Understand this as the complement of "--keep-window". To compare the effects, use these:

All three widgets visible, staircase effect, ordered 1,2,3:

dialog                         --begin 2 2 --yesno "" 0 0 \
    --and-widget               --begin 4 4 --yesno "" 0 0 \
    --and-widget               --begin 6 6 --yesno "" 0 0

Only the last widget is left visible:

dialog           --clear       --begin 2 2 --yesno "" 0 0 \
    --and-widget --clear       --begin 4 4 --yesno "" 0 0 \
    --and-widget               --begin 6 6 --yesno "" 0 0

All three widgets visible, staircase effect, ordered 3,2,1:

dialog           --keep-window --begin 2 2 --yesno "" 0 0 \
    --and-widget --keep-window --begin 4 4 --yesno "" 0 0 \
    --and-widget               --begin 6 6 --yesno "" 0 0

First and third widget visible, staircase effect, ordered 3,1:

dialog           --keep-window --begin 2 2 --yesno "" 0 0 \
    --and-widget --clear       --begin 4 4 --yesno "" 0 0 \
    --and-widget               --begin 6 6 --yesno "" 0 0

Note, if you want to restore original console colors and send your cursor home after the dialog program has exited, use the clear (1) command.

--colors

Interpret embedded "\Z" sequences in the dialog text by the following character, which tells dialog to set colors or video attributes: 0 through 7 are the ANSI used in curses: black, red, green, yellow, blue, magenta, cyan and white respectively. Bold is set by 'b', reset by 'B'. Reverse is set by 'r', reset by 'R'. Underline is set by 'u', reset by 'U'. The settings are cumulative, e.g., "\Zb\Z1" makes the following text bold (perhaps bright) red. Restore normal settings with "\Zn".

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

--defaultno

Make the default value of the yes/no box a No. Likewise, make the default button of widgets that provide "OK" and "Cancel" a Cancel. If "--nocancel" or "--visit-items" are given those options overrides this, making the default button always "Yes" (internally the same as "OK").

--default-item string

Set the default item in a checklist, form or menu box. Normally the first item in the box is the default.

--exit-label string

Override the label used for "EXIT" buttons.

--extra-button

Show an extra button, between "OK" and "Cancel" buttons.

--extra-label string

Override the label used for "Extra" buttons. Note: for inputmenu widgets, this defaults to "Rename".

--help

Prints the help message to dialog's output. The help message is printed if no options are given.

--help-button

Show a help-button after "OK" and "Cancel" buttons, i.e., in checklist, radiolist and menu boxes. If "--item-help" is also given, on exit the return status will be the same as for the "OK" button, and the item-help text will be written to dialog's output after the token "HELP". Otherwise, the return status will indicate that the Help button was pressed, and no message printed.

--help-label string

Override the label used for "Help" buttons.

--help-status

If the help-button is selected, writes the checklist, radiolist or form information after the item-help "HELP" information. This can be used to reconstruct the state of a checklist after processing the help request.

--ignore

Ignore options that dialog does not recognize. Some well-known ones such as "--icon" are ignored anyway, but this is a better choice for compatibility with other implementations.

--input-fd fd

Read keyboard input from the given file descriptor. Most dialog scripts read from the standard input, but the gauge widget reads a pipe (which is always standard input). Some configurations do not work properly when dialog tries to reopen the terminal. Use this option (with appropriate juggling of file-descriptors) if your script must work in that type of environment.

--insecure

Makes the password widget friendlier but less secure, by echoing asterisks for each character.

--item-help

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

--keep-window

Normally when dialog performs several tailboxbg widgets connected by "--and-widget", it clears the old widget from the screen by painting over it. Use this option to suppress that repainting.

At exit, dialog repaints all of the widgets which have been marked with "--keep-window", even if they are not tailboxbg widgets. That causes them to be repainted in reverse order. See the discussion of the "--clear" option for examples.

--max-input size

Limit input strings to the given size. If not specified, the limit is 2048.

--no-cancel

--nocancel

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

--no-collapse

Normally dialog converts tabs to spaces and reduces multiple spaces to a single space for text which is displayed in a message boxes, etc. Use this option to disable that feature. Note that dialog will still wrap text, subject to the "--cr-wrap" and "--trim" options.

--no-kill

Tells dialog to put the tailboxbg box in the background, printing its process id to dialog's output. SIGHUP is disabled for the background process.

--no-label string

Override the label used for "No" buttons.

--no-shadow

Suppress shadows that would be drawn to the right and bottom of each dialog box.

--ok-label string

Override the label used for "OK" buttons.

--output-fd fd

Direct output to the given file descriptor. Most dialog scripts write to the standard error, but error messages may also be written there, depending on your script.

--print-maxsize

Print the maximum size of dialog boxes, i.e., the screen size, to dialog's output. This may be used alone, without other options.

--print-size

Prints the size of each dialog box to dialog's output.

--print-version

Prints dialog's version to dialog's output. 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.

--separator string

--separate-widget string

Specify a string that will separate the output on dialog's output from each widget. This is used to simplify parsing the result of a dialog with several widgets. If this option is not given, the default separator string is a tab character.

--shadow

Draw a shadow to the right and bottom of each dialog box.

--single-quoted

Use single-quoting as needed (and no quotes if unneeded) for the output of checklist's as well as the item-help text. If this option is not set, dialog uses double quotes around each item. That requires occasional use of backslashes to make the output useful in shell scripts.

--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 obsolete, 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. This option is provided for compatibility with Xdialog, however using it in portable scripts is not recommended, since curses normally writes its screen updates to the standard output. If you use this option, dialog attempts to reopen the terminal so it can write to the display. Depending on the platform and your environment, that may fail.

--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 default is 8.

--timeout secs

Timeout (exit with error code) if no user response within the given number of seconds. This is overridden if the background "--tailboxbg is used. A timeout of zero seconds is ignored.

--title title

Specifies a title string to be displayed at the top of

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

--trim

eliminate leading blanks, trim literal newlines and repeated blanks from message text.

--version

Same as "--print-version".

--visit-items

Modify the tab-traversal of checklist, radiobox, menubox and inputmenu to include the list of items as one of the states. This is useful as a visual aid, i.e., the cursor position helps some users.

When this option is given, the cursor is initially placed on the list. Abbreviations (the first letter of the tag) apply to the list items. If you tab to the button row, abbreviations apply to the buttons.

--yes-label string

Override the label used for "Yes" buttons.

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 separately adjustable windows. If the values for day, month or year are missing or negative, the current date's corresponding values are used. You can increment or decrement any of those using the left-, up-, right- and down-arrows. Use vi-style h, j, k and l for moving around the array of days in a month. 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 dialog's output. If the "--separate-output" option is not given, the strings will be quoted to make it simple for scripts to separate them. See the "--single-quoted" option, which modifies the quoting behavior.
--form text height width formheight [ label y x item y x flen ilen ] ...

Box Options

Obsolete Options

RUN-TIME CONFIGURATION

ENVIRONMENT

FILES

EXAMPLES

DIAGNOSTICS

BUGS

AUTHOR

CONTRIBUTORS

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

Common Options