Xdialog documentation - General syntax and usage

Usage:

Xdialog [<GTK+ options>] [<common options>] [<transient options>] <box option> ...

and:

Xdialog <special option>

The [<common options>] [<transient options>] <box option> sequence may be repeated several times in the same Xdialog command line (this is called dialog chaining). The common/transient options may be omited but there must always be a <box option> as the last Xdialog option.

• The <common options> are options applying to all following <box options> until the same or opposite <common options> are encountered into the Xdialog command line. These options are mostly dealing with menu look, style, placement and behaviour.

• The <transient options> only apply to the next <box option> into the Xdialog command line. These options are used to tune the widgets (number and type of buttons, menu icon) or to trigger some of the widgets specific features.

• The <box option> tells to Xdialog which widget must be used and is followed by three or more parameters:
  • the first parameter is a text string or a filename (this depends on the box option);
  • the second and the third parameters are menu <height> and <width> in characters;
  • some box options require additional parameters such as tags, menu items, labels or default values.

  On completion of each box option (i.e. every time a widget is closed) Xdialog sends any result (text, numbers) as one or more strings to stderr (this can be changed so that the results are sent to stdout thanks to a common option).

  When Xdialog terminates (i.e. when all the <box options> are processed or when an error occurs), the exit code may take the following values:

  • 0 : OK, Yes or Next button pressed.
  • 1 : Cancel or No button pressed.
  • 2 : Help button pressed (see the --help transient option for details).
  • 3 : Previous button pressed (see the --wizard transient option for details).
  • 255 : an error occured or the box was closed through the window manager (same exit code as when the ESC key is pressed in (c)dialog).

  Note that when chaining dialogs, the chain is broken and Xdialog terminates as soon as a widget returns a non zero exit code.

  When using Xdialog from a shell, it is therefore usually invoked as follow:

  RESULTS=`Xdialog --stdout ...` # It is also possible to redirect Xdialog output to a temporary file.
  EXIT_CODE=$?
  case $EXIT_CODE in
      0) # All OK. The $RESULTS variable holds everything entered/choosed by the user.
         .../...
         ;;
      1) # Cancel/No pressed.
         .../...
         ;;
    255) # An error occured or the box was closed.
         .../...
         ;;
  esac
  

  For examples of how to use each widget, please read the box options section of this documentation and browse the samples directory.

• The <special options> take no parameter and are to be used alone into the command line. They just make Xdialog to print a string on stderr and to exit immediately (with a 0 exit code).

See also the (c)dialog compatibility notes.