<html>
<head>
<title>Xdialog documentation - General syntax and usage</title>
</head>
<body bgcolor="#102050" text="#F0E0A0" link="#00E000" vlink="#FF00B0" alink="#FF0000">
<table border=0 width="100%"><tr>
<td align="left"><a href="intro.html">previous</a><a name="TOP"> </a> <a href="common.html">next</a> <a href="index.html">contents</a></td>
<td align="right"><a href="#BOTTOM">bottom</a></td>
</tr></table>
<hr>
<center>
<h1>Xdialog documentation - General syntax and usage</h1>
<hr width=30%>
</center>
<p>
<h2>Usage:</h2>
<pre>Xdialog [<<a href="gtk.html">GTK+ options</a>>] [<common options>] [<transient options>] <box option> ...</pre>
<p>and:
<pre>Xdialog <special option></pre>
<p align="justify">The [<common options>] [<transient options>] <box option> sequence may be repeated several times in the same Xdialog command line (this is called <b>dialog chaining</b>). The common/transient options may be omited but there must always be a <box option> as the last Xdialog option.
<ul>
<p><li>The <<a href="common.html">common options</a>> 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.
<p><li>The <<a href="transient.html">transient options</a>> 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.
<p><li>The <<a href="box.html">box option</a>> tells to Xdialog which widget must be used and is followed by three or more parameters:
<ul>
<li>the first parameter is a text string or a filename (this depends on the box option);
<li>the second and the third parameters are menu <height> and <width> in characters;
<li>some box options require additional parameters such as tags, menu items, labels or default values.
</ul>
<p align="justify">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).
<p align="justify">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:
<ul><p>
<li><b>0</b> : <i>OK</i>, <i>Yes</i> or <i>Next</i> button pressed.
<li><b>1</b> : <i>Cancel</i> or <i>No</i> button pressed.
<li><b>2</b> : <i>Help</i> button pressed (see the --help transient option for details).
<li><b>3</b> : <i>Previous</i> button pressed (see the --wizard transient option for details).
<li><b>255</b> : 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).
</ul>
<p align="justify">Note that when chaining dialogs, the chain is broken and Xdialog terminates as soon as a widget returns a non zero exit code.
<p align="justify">When using Xdialog from a shell, it is therefore usually invoked as follow:
<pre>
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
</pre>
<p align="justify">For examples of how to use each widget, please read the <a href="box.html">box options</a> section of this documentation and browse the <a href="samples/">samples directory</a>.
<p><li>The <<a href="special.html">special options</a>> 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).
</ul>
<p align="justify">See also the <a href="compatibility.html#FEATURES">(c)dialog compatibility notes</a>.
<hr>
<table border=0 width="100%"><tr>
<td align="left"><a href="intro.html">previous</a><a name="BOTTOM"> </a> <a href="common.html">next</a> <a href="index.html">contents</a></td>
<td align="right"><a href="#TOP">top</a></td>
</tr></table>
<br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br><br>
</body>
</html>
