http://invisible-island.net/
Copyright © 1999-2021,2022 by Thomas E. Dickey

DIALOG – Script-driven curses widgets

Synopsis

Though similar in style to CDK, it is different, being a script-interpreter which provides a set of curses widgets. Widgets are objects whose appearance and behavior can be customized. There is a much-reduced variation of dialog, called lxdialog, which is used in Linux kernel configuration.

History

Early History

Dialog was written by Savio Lam <lam836@cs.cuhk.hk> and modified by several people:

My Involvement

I became involved with dialog for the same reason as Cdk: they were the most well-known applications using ncurses, and I realized that they were not being maintained well enough to reflect ncurses' capabilities.

Initially, I made fixes and reviewed the code to ensure that problems reported were not related to ncurses. After that, I resumed development, adding new widget types. See the changelog for details.

At the end of 2005, I relicensed dialog as LGPL. It was GPL before, which made it (the dialog library in particular) unusable by developers of non-GPL programs. After several requests, I discussed this with Santiago Vila (the Debian package maintainer), indicating my intention to audit the code, and remove as needed any fragments predating my work.

I reviewed the code (studying the changes using diffstat and tkdiff) and found that over the course of development and improvements, I had replaced all of the original program. After accounting for the license notice itself, blank lines and curly braces, there was no trace of the 0.9a+Debian version.

Because I had replaced the original program with my own work, that made me an "original author" of dialog, and allowed me to relicense it.

Dialog's ChangeLog

• the changelog in html form
• CHANGES (flat-text changelog)

dialog has (at the end of 2012) 99 options shown in its usage message. Of those, 29 set a box (widget) type.

The other visible options set common variables used by the widgets:

dialog maps some options into its own set. Some are dialog options which have been imitated in other programs; some are the reverse.

Some of the hidden options are simply ignored:

dialog can be built in a variety of configurations, reducing its size.

As I note in the manpage, the total program size should count the required libraries. This is particularly true in restricted environments such as an install disk.

Here are installed sizes from Debian 5.0 (32-bit) and 6.0 (64-bit). I included both releases to provide a comparison with Xdialog. It is apparent that the installed size counting required libraries is always lowest for dialog, even when it has more than twice the functionality of the next smallest (whiptail).

Compatibility

Debian (and derived distributions such as Ubuntu) are a special case for compatibility concerns because their installer uses terminal-based scripts extensively and there is some attempt to use either dialog or whiptail.

Interestingly, the popularity contest (in which I do not participate) seems to show dialog due to installation bias of Debian has half the popularity of whiptail. The two are not installed on an equal basis because dialog is "optional" while whiptail is "important". Here is an extract of the relevant information as I am documenting dialog 1.2:

#Format
#
#<name> is the package name;
#<inst> is the number of people who installed this package;
#<vote> is the number of people who use this package regularly;
#<old> is the number of people who installed, but don't use this package
#      regularly;
#<recent> is the number of people who upgraded this package recently;
#<no-files> is the number of people whose entry didn't contain enough
#           information (atime and ctime were 0).
#rank name                            inst  vote   old recent no-files (maintainer)
1791  kdebase-bin                    11587  1878  6407   268  3034 (Debian Qt/kde Maintainers)     
12634 whiptail                       129722 52877 68792  8017    36 (Alastair Mckinstry)
16056 zenity                         58831 15952 36121  6737    21 (Debian Gnome Maintainers)
24528 dialog                         20677  3198 16421  1052     6 (Santiago Vila)
129051 xdialog                          305    40   265     0     0 (Not in sid)
          

There is no separate package for kdialog (it is part of the kdebase-bin package). There are usable figures for the other programs.

The count for zenity can be explained in part because that program is not really compatible with either dialog or whiptail. Thus, it is likely that there are scripts which cannot be used by other programs (reviewing the package dependencies makes this apparent: only one depends on either dialog or zenity).

Older versions of dialog

The issue of compatibility comes up occasionally. I do not intend to break old scripts. You may note in the change-log fixes for regressions. When merging Victor Stemens' changes, I spent time ironing out issues in text justification.

A bigger issue is cross-compatibility with similar programs.

Xdialog

Xdialog's author paid attention to compatibility, making a good attempt at working with scripts that dialog would work with. He added many widgets, some of which are viable in a terminal enviroment. I have adapted the most useful of those.

These threads give some insight on why Xdialog is no longer in Debian (because it was a victim of the successive incompatibilities of the GNOME libraries):

• Why no more Xdialog on squeeze? (Debian User Forums)
• [SOLVED] Where is Xdialog? (Ubuntu Forums)

As noted in the forums, the alternative is zenity, but that is largely incompatible.

whiptail

One of the challenging aspects about making scripts compatible with whiptail is its documentation. Whiptail is a part of the newt package, which has the same problem. I have a collection of releases, which helps.

Newt was initially released (0.25) in May 1998. It had a short tutorial on using the package, no detailed documentation. The source code is the documentation. Successive releases for the next couple of years added undated items to its change-log, with version numbers increasing more rapidly than the package version. For instance, newt 0.50.8's changelog mentions 0.55 as the most recent version. There was no fixed maintainer for the package by Red Hat. However, comments in the newt.spec give some clues as to who was modifying it. It was imported into git in 2006, from which detailed history can be gleaned. For instance:

• development on newt started in early 1996.
• whiptail's first commit was 1997-03-18
• newt's first public release was the following year, 1998-05-05.
• before release, whiptail was named ndialog

The situation in the Debian package is not much better. There has been a fixed set of maintainers, but their source history is ad hoc, unsystematic.

Here are some dates and data for the Red Hat releases. The ".spec" file serves in place of a change-log. However, it lacks most of the information which I would expect to find in a package of this type. In particular, there is no summary of features added or changed for each release.

The point in reviewing whiptail's history is to see when features were added which affect compatibility with dialog.
Here is a table showing whiptail's command-line options, together with the corresponding dialog option, dates and related bug reports which motivate their respective changes. The dates for whiptail are from its git repository for commits; they are not release dates (and you may notice that Debian's updates were not rapidly applied upstream).

Early on, there was some discussion of making dialog compatible with the options recognized by whiptail. Santiago Vila (the Debian package maintainer for dialog) mentioned this, and I made improvements, e.g., in 2000/02/22. Joey Hess made a point of providing similar changes (such as the --passwordbox option) to improve both programs.

At the time, I overlooked --noitem (perhaps because there was no documentation), and omitted --scrolltext because it was cosmetic only (there was no mouse support in newt). If there had been a bug report regarding those or other features of whiptail, I would have addressed it. However, there was none.

Although whiptail is given a higher priority (important) in Debian than dialog (optional), some packagers either expressed a preference for dialog's additional functionality, or used the features which work with both. In Debian 6 for instance, I see these counts from /var/lib/dpkg/available:

There appear to be two distinct uses of whiptail and newt:

• Red Hat uses the newt shared library from python scripts.
• Debian uses the whiptail command-line program in installers.

Reflecting that difference, Debian has long maintained a large set of patches for whiptail. Compare the patch sizes listed below with the size of the newt package listed above. The Debian package's change-log states that it started a year before newt's first release, with newt 0.10; however it was first released with Debian 2.0 (after newt's 0.25 release). Here are some numbers (obtained by inspecting packages from archive.debian.org). By the way, the packages for Debian 4.0 and 5.0 were updated after the official release:

The drop in size for Debian 6.0 is due to a resync with the Red Hat upstream in 2006. It takes a while for a change to propagate through Debian. The Debian 6.0 package has "only" 8 patches, the largest of which is 2160 lines added for bidi support.

While whiptail had a --textbox option "early on", it was removed before version 0.25, in 1997-08-18. Debian's patches added that back. It was not until the 0.52.0 sync in 2006-09-19 that upstream whiptail had this option.

That feature, by the way, never appeared in a bug report. Another feature which came into Red Hat's git without a bug report was the --topleft option (2006-10-12).

In other cases, the Debian package maintainer sent changes to Red Hat as part of a bug report.

• Bug 117466 – Patch to provide documentation
  This provides a manpage. Upstream had none; Debian added this in early 1998, addressing Debian #16857.
  Debian continued adding features adapted from ongoing work in dialog or from Joey Hess's patches for both programs.
• For instance, the patch submitted in this report includes these options:
  

  --default-item (see 0.9a 2000/02/22)
  --output-fd (see 0.9b 2002/08/14)
  --passwordbox (see 0.9a 1999/12/25)
  --separate-output (a feature from dialog 0.5 which was adapted by Debian in newt 0.21-4, 12 Feb 1998).

  Two of those (--output-fd and --passwordbox) are clearly the work of Joey Hess. One was adapted from my work.
  In each case, the manpage description is (except for changing "dialog" to "whiptail") identical. The two options implemented by Joey Hess provided manpage updates. The other two were copied from dialog.

  The early Debian package for newt noted above adapted a manpage from dialog. It describes the --gauge option. That text was copied from the manpage for dialog 0.6, but (noting that Marc Ewing's name was not in the manpage, rather it was in the README file) the Debian maintainers did not provide attribution for him either. The disclaimer at the end "based on" is too generous (to the Debian maintainer), since the work involved consisted of no more than removing the description of --create-rc and changing "dialog" to "whiptail" throughout.

  The whiptail manpage does not state this; it cites the Debian package maintainers as the developers and references dialog 0.3 as the starting point of the manpage. I reported the manpage issues as Debian bug #406278 early in 2007. Debian's maintainer has ignored it for five years.

Requests without a patch never made it, or get odd treatment:

• Bug 126766 – whiptail: please add timeout option
  (lost)

• Bug 126767 – whiptail: Please add the dialog 'form' box option
  (rejected)

• Bug 126768 – please allow way to change the text of the cancel button
  Implemented by the upstream maintainer a couple of years later, this provides the same functionality as the 2001/2003 changes in dialog—but using different option names.

Some longstanding bugs were fixed upstream without any apparent help from the Debian maintainer:

• Bug 620083 – whiptail --gauge does not work as advertised

I did not notice any of this until I started reviewing my 1.2 changes for compatibility with whiptail. After all, there were no relevant bug reports.

My 1.2 changes were prompted by having done a set of fixes toward a new update, and happening to think about a list I had made in 2006 of interesting widgets from Xdialog and FreeBSD's fork to implement in dialog. Since I had implemented most of the FreeBSD parts, I realized that if I implemented the comparable parts of the Xdialog list I would be at my goal for 1.2. So I did that, and in studying the Xdialog documentation noticed the --notags option. That led me back to compare with whiptail, and finding the extra (and in the case of Red Hat #126768) redundant options to deal with.

Incidentally, I was reminded while collecting this information of the reason why whiptail is the program used rather than dialog: It dates back to the ncurses licensing dispute in May 1997. In a connected thread on the Debian mailing list, Bruce Perens demonstrated his support for Eric Raymond by stating that

Any new work I do will use slang rather than ncurses.

In context, "new work" referred to the installer group. By the time I started maintaining dialog a year later, the matter had already been decided. That was not the last issue from that group; over the next few years (until sometime in 2000, probably after Raymond's final interaction with ncurses), they continued to demonstrate their support by misattributing my work to Eric Raymond (and others, depending on the work).

Of course there were also people (and still are) who are fans of slang and newt, and will emphasize its advantages. Notwithstanding the fact that after a few years I did get John Davis to tone down the rhetoric and stick to measurable facts, his fans are unpersuaded.

The (over-zealous) remarks from someone in the same group in 2006 prompted me to investigate just how much larger dialog was than whiptail. I was surprised to find that when counting the required libraries, whiptail was actually larger than dialog. Of course, I documented my findings in dialog's manpage.

Some people do read the manual, as noted in Ubuntu #347913. I noticed this report during my 1.2 review, prompting me to update the whiptail compatibility options.

The result of my 1.2 review is that scripts accepted by whiptail will also be accepted by dialog. Because the two programs differ in their support for word-wrapping and handling of escapes, there will be inevitably some differences in appearance.

gdialog

Zenity's documentation refers to gdialog. That was a fork of dialog 0.6c which was part of the gnome-utils package in 2002 (e.g., 2.0.2 2002/09/03), modified to use Gtk. Some parts did not work, e.g., --gauge.

Its documentation was minimal (see this). After a while, it was dropped.

zenity

Zenity was first released early in 2003 (see git). It was influenced by my work on dialog, as illustrated by its list of options. Those use the "interesting" options from Xdialog (calendar, file-selection). Comparing with the list of newer dialog options, you will see some borrowing.

-h --about --auto-close --auto-kill --calendar --cancel-label --checklist
--class --column --confirm-overwrite --date-format --day --directory
--display --editable --entry --entry-text --error --file-filter
--file-selection --filename --g-fatal-warnings --gtk-module --height --help
--help-all --help-calendar --help-entry --help-error --help-file-selection
--help-general --help-gtk --help-info --help-list --help-misc
--help-notification --help-progress --help-question --help-scale
--help-text-info --help-warning --hide-column --hide-header --hide-text
--hide-value --info --list --listen --max-value --min-value --month
--multiple --name --no-wrap --notification --ok-label --percentage
--print-column --print-partial --progress --pulsate --question --radiolist
--save --scale --screen --separator --step --sync --text --text-info
--timeout --title --value --version --warning --width --window-icon --year

However, there is no script provided with zenity to handle scripts which are newer than dialog 0.6c.

kdialog

Kdialog is less compatible with dialog than zenity. To illustrate the problem, here is the corresponding list of options:

--
--attach --author --calendar --checklist --combobox --default --dontagain
--error --getcolor --getexistingdirectory --geticon --getopenfilename
--getopenurl --getsavefilename --getsaveurl --help --help-all --help-kde
--help-qt --inputbox --license --menu --msgbox --multiple --passivepopup
--password --print-winid --progressbar --radiolist --separate-output
--slider --sorry --textbox --textinputbox --title --warningcontinuecancel
--warningyesno --warningyesnocancel --yesno --yesnocancel -v

However (see git) it is an inactive project.

bsddialog

This was written as a clone of dialog, but though the command-line repertoire is copied (and even imitated as in the --help message). On committing to FreeBSD, its author made no mention of that fact in documentation.

After some discussion, its developer proposed a slight improvement, which fell short of the usual conventions in this area (see first update, and followup). The first update is problematic (at best misleading):

It was introduced to provide a permissive open source alternative to the dialog utility for use by the FreeBSD base system.

Besides the oblique reference to dialog in a followup

implementing some feature described in the dialog manual

the developer misled the unwary reader to assume that the license used by dialog (i.e., LGPL, the most suitable compromise available given its history) is not an open source license. It is less permissive than BSD-2, but referring to LGPL as “non-permissive” is untruthful.

The developer's goals were clearly outlined in the FreeBSD Quarterly Status Report 2nd Quarter 2011:

The purpose of this project is to provide an utility and a library to build scripts and tools with UI Widgets in a terminal. The project is inspired by Dialog; however BSDDialog is released under the terms of the BSD-2-Clause License while Dialog is licensed as LGPL so a link of the project has been added to the "GPL Software in the Base System" wiki page.

The aim is to provide full compatibility with the dialog utility (the challenge is to implement over seventy options and almost thirty widgets). The API compatibility with the library is not a priority because libbsddialog should meet FreeBSD’s needs, for example it provides the new mixedlist() function, it can take as argument a set of: checklists, radiolists and separators, so it could be useful for building a dialog4ports clone: easier to implement and not depending on non-permissive dependencies.

There is a wide gap between some feature and full compatbility. In a quick inspection of the manual pages:

• dialog has 29 widgets, 78 other options,

• bsddialog 0.1 lists 19 widgets, 69 other options,

• bsddialog 0.1 reimplements 19 widgets and 48 options.

  A few are deprecated (e.g., --no-ok versus --nook), rather than being new features.

Documentation

• dialog program (pdf) (postscript) (plain text)

• dialog library (pdf) (postscript) (plain text)

Download

• source
• archives

Screenshot

An early example (2004) using UTF-8:

This page has more examples.

Related Links

Packages

• OSWatershed.org (archived 2014)
• RPM finder: dialog
• Debian
• FreeBSD ports

Programs

• Xdialog
• dialog 0.7
• FreeBSD fork of dialog 0.4
  • (program)
  • (library)
• Zenity (maintenance page)

Other

• Perl
  • UI-Dialog
  • User Interfaces in Perl San Diego Perl Mongers
• Ruby
  • Ruby Dialog Interface
• Python
  • Python Dialog Website
• Bug reports
  • Current and archived Debian bug reports for dialog
  • Current and archived Debian bug reports for whiptail
  • Current and archived Debian bug reports for zenity
• Tutorials
  • Dialog: An Introductory Tutorial by Jeff Tranter (Sep 01, 1994)
  • Designing Simple front ends with dialog/Xdialog LG #101 by Sunil Thomas Thonikuzhiyil (April 2004)
  • Shell Scripting with KDE Dialogs

Bugs

You should report bugs either to me. or to the ncurses mailing list bug-ncurses@gnu.org.