previous next contents | bottom

# Xdialog documentation - Compatibility

## dialog:

Dialog is an application used in shell scripts which displays text user interface widgets. It uses the curses or ncurses library. The latter provides users with the ability to use a mouse, e.g., in an xterm. Dialog was created by Savio Lam (first reported version 0.3 was in 1994).

- More information and downloads: https://invisible-island.net/dialog/

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

or, if you use bash:

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

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

previous next contents | top