Overview
--------

pythondialog is a Python wrapper for the UNIX "dialog" utility written
by Savio Lam and modified by several people, whose home page you should
find at http://dickey.his.com/dialog/dialog.html. Its purpose is to
provide an easy to use, pythonic and as complete as possible interface
to dialog from Python code.

pythondialog is free software, licensed under the GNU LGPL.

If you want to get a quick idea of what this module allows you to do,
you should run demo.py:

  python demo.py


What is pythondialog good for? What are its limitations?
--------------------------------------------------------

As you might infer from the name, dialog is a high-level program that
generates dialog boxes. So is pythondialog. They allow you to build nice
interfaces quickly and easily, but you don't have full control over the
widgets, nor can you create new widgets without modifying dialog itself.
If you need to do low-level stuff, you should have a look at ncurses or
slang instead.


Documentation
-------------

pythondialog is fully documented through Python docstrings. Handy ways
to access to this documentation are to use the pydoc standalone program
or Python module.

You can type "pydoc dialog" at the command prompt in pythondialog base
directory. Alternatively, you can type:
  - "import dialog; help(dialog)" at at a Python 2.2 command prompt (and
    probably any later version)

To browse it in HTML format, you can launch an HTTP server listening on
port 1234 with "pydoc -p 1234 &" (yes, it is damn easy!) and simply
browse on http://localhost:1234/ afterwards.

Alternatively, you can dump the current dialog.py documentation (as
found by Python if you did "import dialog") as an html file with
"pydoc -w dialog". This will generate dialog.html in the current
directory.

See the pydoc module's documentation for more information.


Using Xdialog instead of dialog
-------------------------------

Starting with 2.06, there is an "Xdialog" compatibility mode that you
can use if you want pythondialog to run the graphical Xdialog program
(which *should* be found under http://xdialog.free.fr/) instead of
dialog (text-mode, based on the ncurses library).

The primary supported platform is still dialog, but as long as only
small modifications are enough to make pythondialog work with Xdialog, I
am willing to support Xdialog if people are interested in it (which
turned out to be the case for Xdialog).

The demo.py from pythondialog 2.06 has been tested with Xdialog 2.0.6
and found to work well (barring Xdialog's annoying behaviour with the
file selection dialog box).


Troubleshooting
---------------

* pythondialog seems not to work very well with whiptail. Well, whiptail
  is not very compatible with dialog any more. Although you can tell
  pythondialog the program you want it to invoke, only programs that are
  mostly dialog-compatible are supported.

* It is said that there is a bug in (at least) the Mandrake 7.0 Russian
  Edition running on AMD K6-2 3D that causes core dump when `dialog' is run
  with the --gauge option; in this case you'll have to recompile the `dialog'
  program.


History
-------

pythondialog was originally written by Robb Shecter. Sultanbek Tezadov
added some features to it (mainly the first gauge implementation, I
guess). Florent Rougon rewrote most parts of the program to make it
more robust and flexible so that it can give access to most features
of the dialog program. Finally, I (Peter Astrand) took over
maintainership for both the original version and Florents updated
version.