http://invisible-island.net/
Copyright © 1999-2013,2014 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:

Early Dialog History
Date Version Developer Features
1993/12/17 0.1 Savio Lam The options in the initial release of dialog were --inputbox, --msgbox, and --yesno.
1994/01/03 0.2 Savio Lam Several options were added: --checklist, --clear, --infobox, --menu, --textbox, and --title.
1994/01/13 0.3 Savio Lam This added simple color support, along with the --create-rc option to configure it at runtime.
1994/06/11 0.4 Stuart Herbert This improved the color support, providing the 3-dimensional appearance by using shadows. It also added the --backtitle and --radiolist options.
1994/10/08 0.4 fork FreeBSD developers Andrey A Chernov imported dialog 0.4 into the FreeBSD source tree, splitting it into program- and library-sections.
  • Andrey A Chernov added a prgbox function to allow running a program via a pipe to a dialog box.
  • Anatoly A Orehovsky added a widget for displaying file-trees, e.g., as produced by the find program as well as more general uses.
  • Marc van Kempen added a file-selector, as well as a different gauge widget.

The main use of this version of dialog was reportedly sysinstall. That was replaced by this version of dialog for FreeBSD 9.0 by Nathan Whitehorn and others. I made improvements to dialog to help with this starting early in 2011, adding these options:

--hfile, --hline, --prgbox, and --programbox.

1994/11/07 0.5 Marc Ewing This added the --gauge and --separate-output options. It modified the --inputbox option to provide for an (optional) initial value. The dialog.pl file was added as an example.
1995/01/28 0.6 Marc Ewing Only bug-fixes were made.
1995/09/12 0.6c Florian La Roche Added mouse support by Rubini, dated 1994. This also adapted changes from 0.5 or 0.6, adding the gauge widget (but misspelled). The misspelling propagated into cdialog.
1995/08/17 0.6z John Gatewood Ham This added no new features. It modified the usage message to show only those features that were compiled-in.
1996/01/15 0.9a Pasquale De Marco "Pako" This is cdialog, based on 0.6c. It added many new options:
--and-widget, --aspect, --beep, --beep-after, --begin, --cr-wrap, --no-kill, --print-maxsize, --print-size, --print-version, --size-err, --sleep, --tab-correct, --tab-len, --tailbox, and --tailboxbg.
1996/01/16 0.69 Allesandro Rubini This is a fork of 0.6z, not used by later development.
1997/01/09 0.6z John Gatewood Ham In my copy, the samples and docs were updated about a year later.
2001/02/06 0.61a Thomas Regner This added a file-selector dialog option --file.
The README states that it was distributed as a patch to 0.6z, however my copy was fully-patched (probably a copy of the tar-ball from which the patch was made).

Vincent Stemen incorporated this work in the patches which he sent to me. That became the --fselect widget.

Later, in 2004 I later added a different option named --file.

2001/03/16 0.7 Vincent Stemen This is based on 0.61a, intentionally between 0.6z and 0.9a-20010115.
Vincent sent patches to me in 2001 to add his changes to my ongoing snapshots, so that this fork's changes were not lost.

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

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

Dialog widget-options
Name Version
--buildlist 1.2 2012/12/30
--calendar 0.9b 2001/04/15
--checklist 0.2
--dselect 1.1 2007/02/27
--editbox 1.1 2007/02/27
--form 1.0 2003/08/18
--fselect 1.1 2007/02/27
--gauge 0.5
--infobox 0.2
--inputbox 0.1
--inputmenu 1.0 2003/01/30
--menu 0.2
--mixedform 1.1 2007/02/27
--mixedgauge 1.1 2007/02/27
--msgbox 0.1
--passwordbox 0.9a 1999/12/25
--passwordform 1.0 2005/12/07
--pause 1.0 2004/12/19
--prgbox 1.1 2011/03/02
--programbox 1.1 2011/03/02
--progressbox 1.1 2006/01/19
--radiolist 0.4
--rangebox 1.2 2012/12/30
--tailbox 0.9a
--tailboxbg 0.9a
--textbox 0.2
--timebox 0.9b 2001/04/15
--treeview 1.2 2012/12/30
--yesno 0.1

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

Dialog common options
Name Version
--ascii-lines 1.1 2007/02/27
--and-widget 0.9a
--aspect 0.9a
--backtitle 0.4
--beep-after 0.9a
--beep 0.9a
--begin 0.9a
--cancel-label 0.9a 2001/12/02
--clear 0.2
--colors 0.9b 2002/08/14
--column-separator 1.1 2008/07/27
--cr-wrap 0.9a
--create-rc 0.4
--date-format 1.1 2010/01/19
--default-button 1.1 2012/07/03
--default-item 0.9a 2000/02/22
--defaultno 0.9a 1999/12/25
--exit-label 0.9b 2002/05/19
--extra-button 0.9b 2002/06/22
--extra-label 0.9b 2002/06/22
--help-button 0.9b 2002/03/09
--help-label 0.9b 2002/03/09
--help-status 0.9b 2003/11/26
--hfile 1.1 2011/06/30
--hline 1.1 2011/06/30
--ignore 0.9b 2001/10/14
--input-fd 0.9b 2003/11/26
--insecure 0.9b 2003/11/26
--item-help 0.9b 2000/10/08
--keep-tite 1.1 2007/02/27
--keep-window 0.9b 2003/11/26
--max-input 0.9a 2002/03/09
--no-cancel 0.9b 2000/12/12
--no-collapse 0.9b 2002/05/19
--no-items 1.2 20121230
--no-kill 0.9a
--no-label 0.9a 2001/12/02
--no-lines 1.1 2007/02/27
--no-mouse 1.1 2011/01/18
--no-nl-expand 1.1 2011/06/30
--no-ok 1.1 2007/09/30
--no-shadow 0.9a
--no-tags 1.2 20121230
--no-items 1.2 20121230
--nook 1.1 2007/09/30
--notags 1.2 20121230
--ok-label 0.9a 2001/12/02
--output-fd 0.9b 2002/08/14
--output-separator 1.1 2008/07/27
--print-maxsize 0.9a
--print-size 0.9a
--print-version 0.9a
--quoted 1.1 2008/07/27
--scrollbar 1.1 2010/01/19
--separate-output 0.5
--separate-widget 0.9a
--shadow 0.9a
--single-quoted 0.9b 2004/06/06
--size-err 0.9a
--sleep 0.9a
--stderr 0.9a 2000/07/02
--stdout 0.9a 2000/07/02
--tab-correct 0.9a
--tab-len 0.9a
--time-format 1.1 2010/01/19
--timeout 0.9a 2002/03/09
--title 0.2
--trace 1.1 2007/02/27
--trim 0.9a 2001/10/14
--version 0.9a 2000/07/30
--visit-items 0.9b 2004/06/06
--yes-label 0.9b 2003/11/26

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

Options mapped by dialog into its own names
Name Version Mapped to Version
--cancel-button 1.2 20121230 --cancel-label 0.9b 2001/12/02
--guage 0.6c --gauge 0.9a 2000/01/16
--no-button 1.2 20121230 --no-label 0.9b 2003/11/26
--nocancel 0.9a 2000/02/22 --nocancel 0.9a 2000/12/12
--noitem 1.2 20121230 --no-items 1.2 2012/12/30
--notags 1.2 20121230 --no-tags 1.2 2012/12/30
--ok-button 1.2 20121230 --ok-label 0.9b 2001/12/02
--scrolltext 1.2 20121230 --scrollbar 1.1 2010/01/19
--separator 0.9b 2003/08/18 --output-separator 1.1 2008/07/27
--yes-button 1.2 20121230 --yes-label 0.9b 2003/11/26

Some of the hidden options are simply ignored:

Name Version
--allow-close 0.9a 2001/05/27
--auto-placement 0.9a 2001/05/27
--fb 0.9a 2000/02/22
--fixed-font 0.9a 2001/05/27
--fullbutton 0.9a 2000/02/22
--icon 0.9a 2001/05/27
--keep-colors 0.9a 2001/05/27
--no-close 0.9a 2001/05/27
--no-cr-wrap 0.9a 2001/05/27
--screen-center 0.9a 2001/05/27
--smooth 0.9a 2001/05/27
--topleft 1.2 2012/12/30
--under-mouse 0.9a 2001/05/27
--wmclass 0.9a 2001/05/27

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

Dialog 1.2 program size by configuration
Configure options Size Size with libraries
--disable-extras 90801 2298513
--disable-extras
--enable-whiptail
91217 2298929
--disable-extras
--enable-whiptail
--enable-nls
--enable-widec
--with-ncursesw
96257 2465100
default (all widgets) 171075 2378787
--enable-nls
--enable-widec
--with-ncursesw
175883 2544726

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

Sizes of related programs
Program Size Size with libraries
dialog 1.1-20080316-1 140552 1917378
dialog 1.1-20100428-1 164408 2407723
whiptail 0.52.2-11.3-lenny1 20816 2287319
whiptail 0.52.11-1 25032 3048481
xdialog 2.31-2 86976 4465172
zenity 2.22.1-2 59536 13164249
zenity 2.30.0-1 74400 14216563
kdialog (kdebase-bin) 4:3.5.9.dfsg.1-6+lenny1 77220 22675849
kdialog (kdebase-bin) 4:4.4.5-2 89944 37593148

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

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:

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.

Early Newt/Whiptail History
Date Version Developer SLOC
1998-05-05 0.25 Erik Troan 6431
1998-08-19 0.30 Bill Nottingham 6410
2000-02-25 0.50.8 Bill Nottingham et al 8265
2000-08-22 0.50.17 Erik Troan 8567
2003-02-05 0.51.4 Matt Wilson 9418
2003-08-19 0.51.6 Michael K Johnson 9419
2003-01-04 0.52.0 Adrian Havill 9397
2003-10-13 0.52.4 Miroslav Lichvar 10377
2007-01-31 0.52.5 Miroslav Lichvar 10431
2007-03-02 0.52.6 Miroslav Lichvar 10490
2007-06-15 0.52.7 Miroslav Lichvar 10584
2008-01-23 0.52.8 Miroslav Lichvar 10603
2009-09-24 0.52.11 Miroslav Lichvar 10706
2011-12-02 0.52.14 Miroslav Lichvar 10972

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

Overview of Whiptail options
  Name Whiptail
date
Dialog
date
Same as Original
date
Whiptail
changes
Dialog
changes
--backtitle 1997/03/18 1994/06/11        
--cancel-button 2007/01/31 2012/12/30 --cancel-label 2001/12/02 Redhat #126768 / Debian #242851 1.2 review
--checklist 1997/03/18 1994/01/03        
--clear 1997/03/18 1994/01/03        
* --default-item 2006/08/25 2000/02/22     Redhat #117473 / Debian #49352 Debian #49796
--defaultno 1997/04/14 1999/10/07        
--fb 1997/03/18 2000/02/22 ignored     maintainer hint
--gauge 1997/03/18 1995/01/28        
--infobox 1998/01/03 1994/01/03        
--inputbox 1997/03/18 1993/12/17        
--menu 1997/03/18 1994/01/03        
--msgbox 1997/03/18 1993/12/17        
--no-button 2007/01/31 2012/12/30 --no-label 2003/11/26 Redhat #126768 / Debian #242851 1.2 review
--nocancel 1997/03/18 2000/02/22       maintainer hint
--noitem 1997/03/18 2012/12/30       1.2 review
--notags 2004/04/07 2012/12/30     Redhat #117468 / Debian #47597 1.2 review
--ok-button 2007/01/31 2012/12/30 --ok-label 2001/12/02 Redhat #126768 / Debian #242851 1.2 review
* --output-fd 2004/04/07 2002/08/14     Redhat #117469 Debian #153984
* --passwordbox 2006/08/25 1999/12/25     Debian #45961 Debian #45964
--radiolist 1997/03/18 1994/06/11        
--scrolltext 1997/03/18 2012/12/30 --scrollbar 2010/01/19   1.2 review
--separate-output 1997/03/18 1995/01/28        
--textbox 2004/04/14 1994/01/03     Redhat #117472 / Debian patch  
--title 1997/03/18 1994/01/03        
--topleft 2006/10/12 2012/12/30 --begin 0 0   patch from Debian? 1.2 review
--yes-button 2007/01/31 2012/12/30 --yes-label 2003/11/26 Redhat #126768 / Debian #242851 1.2 review
--yesno 1997/03/18 1994/01/03        

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:

Debian package usage
  Depends Recommends Suggests
whiptail 9 4 3
dialog 16 7 5

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

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:

Size of Debian diffs by release
Release Date Version Diffstat
Files Added Deleted
Debian 2.0 1998-06-18 0.21-8 28 859 74
Debian 2.1 1998-12-11 0.25-3 25 883 47
Debian 2.2 2000-04-23 0.50-7 20 1106 39
Debian 3.0 2002-04-03 0.50-17 38 2117 165
Debian 3.1 2005-04-30 0.51.6 54 9037 0
Debian 4.0 2007-01-22 0.52-10 51 13605 0
Debian 5.0 2009-09-24 0.52.11.3 54 13721 0
Debian 6.0 2010-06-21 0.52.11-1 34 4185 0

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.

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

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

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.

Documentation


Download

Screenshot

An example using UTF-8:

An example using UTF-8

This page has more examples.

Packages

Programs

Other

Bugs

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