Xdialog documentation - Compatibility

dialog-compatible utilities:

There are a few dialog "compatible" utilities around, some of them just mimic dialog without adding new features (e.g. gdialog), others add features and may differ in their syntax (cdialog, wdialog). I currently know about:

• dialog: the original one (up to v0.3) which has been upgraded and declined in further versions by contributors (v0.4, v0.6a-0.6z, v0.7). AFAIK it is no more actively developed.

• cdialog: a much improved version of dialog which is still developed. Its binary file may actually be named cdialog or dialog, but you may check the usage message printed for the "ComeOn Dialog!" string IOT find out if your "dialog" binary is in fact "cdialog". You may as well try:

  dialog --print-version

  which should report v0.9 or higher for cdialog.

• gdialog: a Gnome utility that mimics closely dialog but that misses the new features of cdialog.

• wdialog and Wxdialog: a set of utilities which aim is to provide an installation wizard for both UNIX console (using wdialog) and X11 (using Wxdialog). The Wxdialog code is based on the (rather unstable and now quite outdated) Xdialog v1.2.0 code. IMHO Wxdialog is rather pointless, given the features Xdialog provides (including the wizard mode, the multiple inputs boxes, the progress report box, the check button, etc)...

• whiptail: a dialog clone which I heard about but that I never tested (IIRC it uses newt instead of ncurses).

Xdialog high compatibility mode:

As a drop in replacement for dialog, cdialog and gdialog, Xdialog tries to maintain the highest degree of compatibility wherever possible. Because of the differences between a ncurses based console utility and a GTK+ based X11 utility, this compatibility is not perfect though. Also, the Xdialog development history introduces its own oddities and some of the default Xdialog behaviours are different from those of (c)dialog...

I came to the conclusion that the only way to keep the highest possible compatility without sacrifying any of the new features offered by Xdialog, was to make it behave in two possible ways, depending on its actual usage in each script (either as a drop in replacement or as a full featured independent utility).

The approach I adopted is to allow Xdialog behaviour customisation using specific environment variables. The advantage of this solution is that while modified with some environment variable assigments, the script is still usable with (c)dialog.

As of v2.0.0, Xdialog checks for the existence of the XDIALOG_HIGH_DIALOG_COMPAT environment variable; if this variable is set to "1" or "true" (case insensitive), then Xdialog behaves in the closest way to (c)dialog (dropping some of its features and adopting (c/g)dialog defaults and syntax), the net effect being that:

• a fixed (monospacing) font is used in all Xdialog GTK+ widgets (including labels, tags, menu/list items and buttons);
• the --left common option is used as the default justification option instead of the --center one;
• the <text> wrapping is always in force (--wrap) and the --fill option is ignored.
• the --no-cr-wrap common option is used as the default instead of the --cr-wrap one (but it does not apply to the <backtitle> in this case).
• regardless of the specified box size, the auto-sizing feature of Xdialog is forced when XDIALOG_FORCE_AUTOSIZE environment variable is set to "1" or "true". This makes for the sizing problems of some menus (e.g. when the specified box size is actually too small for the number of specified menu/list entries to fit, or when a backtitle is specified; with (c)dialog the backtitle is not held into the boxes themselves, unlike Xdialog which needs therefore for more room in its widgets).
• the Cancel button is not displayed into the tailbox and textbox widgets;
• the infobox widget is turned into a msgbox unless the XDIALOG_INFOBOX_TIMEOUT environment variable is set (in 1/1000s) and greater than 0, in which case an actual infobox without button is used;
• the --version special option returns the same string as --print-version.

In order to take benefit of this improved compatibility in an existing (c)dialog script, you just have to add the following line to the script before the first invocation of Xdialog:

set XDIALOG_HIGH_DIALOG_COMPAT=true

export XDIALOG_HIGH_DIALOG_COMPAT=true

Then, before each Xdialog invocation in the script, you may customize the behaviour of Xdialog by setting the XDIALOG_FORCE_AUTOSIZE and XDIALOG_INFOBOX_TIMEOUT environment variables.

Simple, isn't it ?

Other compatibility features:

By default and whether XDIALOG_HIGH_DIALOG_COMPAT is set or not, Xdialog does its best to accept (c)dialog syntax and options:

• the cdialog --passwordbox box option is accepted by Xdialog and interpreted as --password --inputbox.
• the (c)dialog --menu box option is accepted by Xdialog and interpreted as --menubox.
• the cdialog --defaultno option is accepted by Xdialog and interpreted as --default-no.
• Because the gauge widget is wrongly spelled as "guage" in some releases of (c/g)dialog (this is what happens when the programmer is dyslexic ;-) Xdialog also accepts the --guage option for the gauge widget... Of course as you are not dyslexic (are you ?), you should only use --gauge in your own Xdialog scripts !
• Xdialog ignores any unknown transient/common option (and any associated parameter) passed into its command line. You may therefore use Xdialog in place of (c)dialog in an existing script without removing the options that are irrelevant to Xdialog (such as --clear, --no-kill, --and-widget, etc...).
• Xdialog accepts a standalone --clear option in its command line (this does nothing but Xdialog does not complain about a missing box option).
• A small wrapper (Xdialog.wrapper) is available and may be installed by running the install-wrapper script from the samples directory, just type:

  cd /usr/share/doc/Xdialog-2.3.1/samples;./install-wrapper

  This wrapper will make any script using (c)dialog to call automatically Xdialog when a X display is available (if no X display is available, then the actual (c)dialog binary is called instead); to ensure the best possible compatibility, Xdialog is called by Xdialog.wrapper in high compatibility mode with forced autosize feature on (unless the XDIALOG_HIGH_DIALOG_COMPAT and/or the XDIALOG_FORCE_AUTOSIZE environment variables are already set, in which case their value is not changed by Xdialog.wrapper).

Pending compatibility issues:

Some Xdialog widgets can't be made 100% (c)dialog compatible:

• The infobox which behaviour in (c)dialog is to print a box on the console and return immediately to the calling script without clearing the console (the "box" therefore staying displayed); when the next menu is setup, (c)dialog overwrites the infobox. This behaviour can't be reproduced with GTK+ menus although this could be coarsely simulated by forking Xdialog when such a menu is needed (but so far I could not figure out how to fork successfully with GTK+...).
  With Xdialog, you will have to set XDIALOG_HIGH_DIALOG_COMPAT to "true" and then to choose which type of infobox to use by setting (or not) XDIALOG_INFOBOX_TIMEOUT accordingly: whatever type you choose, the script will be suspended until the infobox is closed (either after the timeout period or when the user presses the OK button)...

• Although allowed by Xdialog, the --tailboxbg option will not make Xdialog to fork nor to run in the background: an explicit "&" has to be appended to the Xdialog command line IOT run it as a background process.