dialog (version 3.1.0)
index
/home/flo/src/python/pythondialog/dialog.py

Python interface to dialog-like programs.
 
This module provides a Python interface to dialog-like programs such
as 'dialog' and 'Xdialog'.
 
It provides a Dialog class that retains some parameters such as the
program name and path as well as the values to pass as DIALOG*
environment variables to the chosen program.
 
For a quick start, you should look at the simple_example.py file that
comes with pythondialog, in the 'examples' directory. It is a very
simple and straightforward example using a few basic widgets. Then,
you could study the demo.py file that illustrates most features of
pythondialog (also from the 'examples' directory), or more directly
dialog.py.
 
See the Dialog class documentation for general usage information,
list of available widgets and ways to pass options to dialog.
 
 
Notable exceptions
------------------
 
Here is the hierarchy of notable exceptions raised by this module:
 
  error
     ExecutableNotFound
     BadPythonDialogUsage
     PythonDialogSystemError
        PythonDialogOSError
           PythonDialogIOError  (should not be raised starting from
                                Python 3.3, as IOError becomes an
                                alias of OSError)
        PythonDialogErrorBeforeExecInChildProcess
        PythonDialogReModuleError
     UnexpectedDialogOutput
     DialogTerminatedBySignal
     DialogError
     UnableToRetrieveBackendVersion
     UnableToParseBackendVersion
        UnableToParseDialogBackendVersion
     InadequateBackendVersion
     PythonDialogBug
     ProbablyPythonBug
 
As you can see, every exception 'exc' among them verifies:
 
  issubclass(exc, error)
 
so if you don't need fine-grained error handling, simply catch
'error' (which will probably be accessible as dialog.error from your
program) and you should be safe.
 
Changed in version 2.12: PythonDialogIOError is now a subclass of
PythonDialogOSError in order to help with the transition from IOError
to OSError in the Python language. With this change, you can safely
replace "except PythonDialogIOError" clauses with
"except PythonDialogOSError" even if running under Python < 3.3.

 
Modules
       
abc
collections
os
random
re
sys
tempfile
traceback
warnings

 
Classes
       
builtins.Exception(builtins.BaseException)
error
BadPythonDialogUsage
DialogError
DialogTerminatedBySignal
ExecutableNotFound
InadequateBackendVersion
ProbablyPythonBug
PythonDialogBug
PythonDialogSystemError
PythonDialogErrorBeforeExecInChildProcess
PythonDialogOSError
PythonDialogIOError
PythonDialogReModuleError
UnableToParseBackendVersion
UnableToParseDialogBackendVersion
UnableToRetrieveBackendVersion
UnexpectedDialogOutput
builtins.object
BackendVersion
DialogBackendVersion
Dialog
VersionInfo(builtins.tuple)
VersionInfo

 
class BackendVersion(builtins.object)
    # Abstract base class
 
  Methods defined here:
__eq__(self, other)
__ge__(self, other)
__gt__(self, other)
__le__(self, other)
__lt__(self, other)
__ne__(self, other)
__str__(self)

Class methods defined here:
fromstring(s) from abc.ABCMeta

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
__abstractmethods__ = frozenset(['__eq__', '__ge__', '__gt__', '__le__', '__lt__', '__ne__', ...])
__hash__ = None

 
class BadPythonDialogUsage(error)
    Exception raised when pythondialog is used in an incorrect way.
 
 
Method resolution order:
BadPythonDialogUsage
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Invalid use of pythondialog'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class Dialog(builtins.object)
    Class providing bindings for dialog-compatible programs.
 
This class allows you to invoke dialog or a compatible program in
a pythonic way to build quicky and easily simple but nice text
interfaces.
 
An application typically creates one instance of the Dialog class
and uses it for all its widgets, but it is possible to
concurrently use several instances of this class with different
parameters (such as the background title) if you have a need
for this.
 
 
Public methods of the Dialog class (mainly widgets)
===================================================
 
The Dialog class has the following methods that produce or update
widgets:
 
  buildlist
  calendar
  checklist
  dselect
  editbox
  form
  fselect
 
  gauge_start
  gauge_update
  gauge_stop
 
  infobox
  inputbox
  inputmenu
  menu
  mixedform
  mixedgauge
  msgbox
  passwordbox
  passwordform
  pause
  programbox
  progressbox
  radiolist
  rangebox
  scrollbox
  tailbox
  textbox
  timebox
  treeview
  yesno
 
All these widgets are described in the docstrings of the
corresponding Dialog methods. Many of these descriptions are
adapted from the dialog(1) manual page, with the kind permission
of Thomas Dickey.
 
The Dialog class also has a few other methods, that are not
related to a particular widget:
 
  add_persistent_args
  backend_version       (see "Checking the backend version" below)
  maxsize
  set_background_title
 
  clear                 (has been OBSOLETE for many years!)
  setBackgroundTitle    (has been OBSOLETE for many years!)
 
 
Passing dialog "Common Options"
===============================
 
Every widget method has a **kwargs argument allowing you to pass
dialog so-called Common Options (see the dialog(1) manual page)
to dialog for this widget call. For instance, if 'd' is a Dialog
instance, you can write:
 
  d.checklist(args, ..., title="A Great Title", no_shadow=True)
 
The no_shadow option is worth looking at:
 
  1. It is an option that takes no argument as far as dialog is
     concerned (unlike the "--title" option, for instance). When
     you list it as a keyword argument, the option is really
     passed to dialog only if the value you gave it evaluates to
     True in a boolean context. For instance, "no_shadow=True"
     will cause "--no-shadow" to be passed to dialog whereas
     "no_shadow=False" will cause this option not to be passed to
     dialog at all.
 
  2. It is an option that has a hyphen (-) in its name, which you
     must change into an underscore (_) to pass it as a Python
     keyword argument. Therefore, "--no-shadow" is passed by
     giving a "no_shadow=True" keyword argument to a Dialog method
     (the leading two dashes are also consistently removed).
 
 
Automatic size for widgets
==========================
 
In many cases, it is possible to have the 'dialog' backend
automatically determine a suitable size for the widgets it
displays. This can be done by passing 'width=0' and 'height=0' to
the widget-producing methods (some widgets also have parameters
such as 'list_height' or 'menu_height'). Instead of writing this
in every widget call or so, you may want to initialize the Dialog
instance with 'autowidgetsize=True' (experimental setting), which
sets the effective default value of such size parameters to 0.
Please refer to the Dialog constructor docstring for details.
 
 
Return value of widget-producing methods
========================================
 
Most Dialog methods that create a widget (actually: all methods
that supervise the exit of a widget) return a value which fits
into one of these categories:
 
  1. The return value is a Dialog exit code (see below).
 
  2. The return value is a sequence whose first element is a
     Dialog exit code (the rest of the sequence being related to
     what the user entered in the widget).
 
"Dialog exit code" (high-level)
-------------------------------
Dialog exit code is a string such as "ok", "cancel", "esc",
"help" and "extra", respectively available as Dialog.OK,
Dialog.CANCEL, Dialog.ESC, Dialog.HELP and Dialog.EXTRA, i.e.
attributes of the Dialog class. These are the standard Dialog
exit codes, also known as "high-level exit codes", that user code
should deal with. They indicate how/why the widget ended. Some
widgets may return additional, non-standard exit codes; for
instance, the inputmenu widget may return "accepted" or "renamed"
in addition to the standard Dialog exit codes.
 
When getting a Dialog exit code from a widget-producing method,
user code should compare it with Dialog.OK and friends (or
equivalently, with "ok" and friends) using the == operator. This
allows to easily replace Dialog.OK and friends with objects that
compare the same with "ok" and u"ok" in Python 2, for instance.
 
"dialog exit status" (low-level)
--------------------------------
The standard Dialog exit codes are derived from the dialog exit
status, also known as "low-level exit code". This low-level exit
code is an integer returned by the dialog backend whose different
possible values are referred to as DIALOG_OK, DIALOG_CANCEL,
DIALOG_ESC, DIALOG_ERROR, DIALOG_EXTRA, DIALOG_HELP and
DIALOG_ITEM_HELP in the dialog(1) manual page. Note that:
  - DIALOG_HELP and DIALOG_ITEM_HELP both map to Dialog.HELP in
    pythondialog, because they both correspond to the same user
    action and the difference brings no information that the
    caller does not already have;
  - DIALOG_ERROR has no counterpart as a Dialog attribute,
    because it is automatically translated into a DialogError
    exception when received.
 
In pythondialog 2.x, the low-level exit codes were available
as the DIALOG_OK, DIALOG_CANCEL, etc. attributes of Dialog
instances. For compatibility, the Dialog class has attributes of
the same names mapped to Dialog.OK, Dialog.CANCEL, etc., but
their use is deprecated as of pythondialog 3.0.
 
 
Adding a Extra button
=====================
 
With most widgets, it is possible to add a supplementary button
called "Extra button". To do that, you simply have to use
'extra_button=True' (keyword argument) in the widget call.
By default, the button text is "Extra", but you can specify
another string with the 'extra_label' keyword argument.
 
When the widget exits, you know if the Extra button was pressed
if the Dialog exit code is Dialog.EXTRA ("extra"). Normally, the
rest of the return value is the same as if the widget had been
closed with OK. Therefore, if the widget normally returns a list
of three integers, for instance, you can expect to get the same
information if Extra is pressed instead of OK.
 
 
Providing on-line help facilities
=================================
 
With most dialog widgets, it is possible to provide online help
to the final user. At the time of this writing (October 2013),
there are three main options governing these help facilities in
the dialog backend: --help-button, --item-help and --help-status.
Since dialog 1.2-20130902, there is also --help-tags that
modifies the way --item-help works. As explained previously, to
use these options in pythondialog, you can pass the
'help_button', 'item_help', 'help_status' and 'help_tags' keyword
arguments to Dialog widget-producing methods.
 
Adding a Help button
--------------------
In order to provide a Help button in addition to the normal
buttons of a widget, you can pass help_button=True (keyword
argument) to the corresponding Dialog method. For instance, if
'd' is a Dialog instance, you can write:
 
  code = d.yesno("<text>", height=10, width=40, help_button=True)
 
or
 
  code, answer = d.inputbox("<text>", init="<init>",
                            help_button=True)
 
When the method returns, the exit code is Dialog.HELP (i.e., the
string "help") if the user pressed the Help button. Apart from
that, it works exactly as if 'help_button=True' had not been
used. In the last example, if the user presses the Help button,
'answer' will contain the user input, just as if OK had been
pressed. Similarly, if you write:
 
  code, t = d.checklist(
                "<text>", height=0, width=0, list_height=0,
                choices=[ ("Tag 1", "Item 1", False),
                          ("Tag 2", "Item 2", True),
                          ("Tag 3", "Item 3", True) ],
                help_button=True)
 
and find that code == Dialog.HELP, then 't' contains the tag
string for the highlighted item when the Help button was pressed.
 
Finally, note that it is possible to choose the text written on
the Help button by supplying a string as the 'help_label' keyword
argument.
 
Providing inline per-item help
------------------------------
In addition to, or instead of the Help button, you can provide
item-specific help that is normally displayed at the bottom of
the widget. This can be done by passing the 'item_help=True'
keyword argument to the widget-producing method and by including
the item-specific help strings in the appropriate argument.
 
For widgets where item-specific help makes sense (i.e., there are
several elements that can be highlighted), there is usually a
parameter, often called 'elements', 'choices', 'nodes'..., that
must be provided as a sequence describing the various
lines/items/nodes/... that can be highlighted in the widget. When
'item_help=True' is passed, every element of this sequence must
be completed with a string which is the item-help string of the
element (dialog(1) terminology). For instance, the following call
with no inline per-item help support:
 
  code, t = d.checklist(
                "<text>", height=0, width=0, list_height=0,
                choices=[ ("Tag 1", "Item 1", False),
                          ("Tag 2", "Item 2", True),
                          ("Tag 3", "Item 3", True) ],
                help_button=True)
 
can be altered this way to provide inline item-specific help:
 
  code, t = d.checklist(
                "<text>", height=0, width=0, list_height=0,
                choices=[ ("Tag 1", "Item 1", False, "Help 1"),
                          ("Tag 2", "Item 2", True,  "Help 2"),
                          ("Tag 3", "Item 3", True,  "Help 3") ],
                help_button=True, item_help=True, help_tags=True)
 
With this modification, the item-help string for the highlighted
item is displayed in the bottom line of the screen and updated as
the user highlights other items.
 
If you don't want a Help button, just use 'item_help=True'
without 'help_button=True' ('help_tags' doesn't matter). Then,
you have the inline help at the bottom of the screen, and the
following discussion about the return value can be ignored.
 
If the user chooses the Help button, 'code' will be equal to
Dialog.HELP ("help") and 't' will contain the tag string
corresponding to the highlighted item when the Help button was
pressed ("Tag 1/2/3" in the example). This is because of the
'help_tags' option; without it (or with 'help_tags=False'), 't'
would have contained the item-help string of the highlighted
choice ("Help 1/2/3" in the example).
 
If you remember what was said earlier, if 'item_help=True' had
not been used in the previous example, 't' would still contain
the tag of the highlighted choice if the user closed the widget
with the Help button. This is the same as when using
'item_help=True' in combination with 'help_tags=True'; however,
you would get the item-help string instead if 'help_tags' were
False (which is the default, as in the dialog backend, and in
order to preserve compatibility with the 'menu' implementation
that is several years old).
 
Therefore, I recommend for consistency to use 'help_tags=True'
whenever possible when specifying 'item_help=True'. This makes
"--help-tags" a good candidate for use with
Dialog.add_persistent_args() to avoid repeating it over and over.
However, there are two cases where 'help_tags=True' cannot be
used:
  - when the version of the dialog backend is lower than
    1.2-20130902 (the --help-tags option was added in this
    version);
  - when using empty or otherwise identical tags for presentation
    purposes (unless you don't need to tell which element was
    highlighted when the Help button was pressed, in which case
    it doesn't matter to be unable to discriminate between the
    tags).
 
Getting the widget status before the Help button was pressed
------------------------------------------------------------
Typically, when the user chooses Help in a widget, the
application will display a dialog box such as 'textbox', 'msgbox'
or 'scrollbox' and redisplay the original widget afterwards. For
simple widgets such as 'inputbox', when the Dialog exit code is
equal to Dialog.HELP, the return value contains enough
information to redisplay the widget in the same state it had when
Help was chosen. However, for more complex widgets such as
'radiolist', 'checklist', 'form' and its derivatives, knowing the
highlighted item is not enough to restore the widget state after
processing the help request: one needs to know the checked item /
list of checked items / form contents.
 
This is where the 'help_status' keyword argument becomes useful.
Example:
 
  code, t = d.checklist(
                "<text>", height=0, width=0, list_height=0,
                choices=[ ("Tag 1", "Item 1", False),
                          ("Tag 2", "Item 2", True),
                          ("Tag 3", "Item 3", True) ],
                help_button=True, help_status=True)
 
When Help is chosen, code == Dialog.HELP and 't' is a tuple of the
form (tag, selected_tags, choices) where:
  - 'tag' gives the tag string of the highlighted item (which
    would be the value of 't' if 'help_status' were set to
    False);
  - 'selected_tags' is the... list of selected tags (note that
    highlighting and selecting an item are different things!);
  - 'choices' is a list built from the original 'choices'
    argument of the 'checklist' call and from the list of
    selected tags, that can be used as is to create a widget with
    the same items and selection state as the original widget had
    when Help was chosen.
 
Normally, pythondialog should always provide something similar to
the last item in the previous example in order to make it as easy
as possible to redisplay the widget in the appropriate state. To
know precisely what is returned with 'help_status=True', the best
ways are usually to experiment or read the code (by the way,
there are many examples of widgets with various combinations of
'help_button', 'item_help' and 'help_status' in the demo).
 
As can be inferred from the last sentence, the various options
related to help support are not mutually exclusive and may be
used together to provide good help support.
 
It is also worth noting that the docstrings of the various
widgets are written, in most cases, under the assumption that the
widget was closed "normally" (typically, with the OK or Extra
button). For instance, a docstring may state that the method
returns a tuple of the form (code, tag) where 'tag' is ..., but
actually, if using 'item_help=True' with 'help_tags=False', the
'tag' may very well be an item-help string, and if using
'help_status=True', it is likely to be a structured object such
as a tuple or list. Of course, handling all these possible
variations for all widgets would be a tedious task and would
probably significantly degrade the readability of said
docstrings.
 
Checking the backend version
============================
 
The Dialog constructor retrieves the version string of the dialog
backend and stores it as an instance of a BackendVersion subclass
into the 'cached_backend_version' attribute. This allows doing
things such as ('d' being a Dialog instance):
 
  if d.compat == "dialog" and \
    d.cached_backend_version >= DialogBackendVersion("1.2-20130902"):
      ...
 
in a reliable way, allowing to fix the parsing and comparison
algorithms right in the appropriate BackendVersion subclass,
should the dialog-like backend versioning scheme change in
unforeseen ways.
 
As Xdialog seems to be dead and not to support --print-version,
the 'cached_backend_version' attribute is set to None in
Xdialog-compatibility mode (2013-09-12). Should this ever change,
one should define an XDialogBackendVersion class to handle the
particularities of the Xdialog versioning scheme.
 
 
Exceptions
==========
 
Please refer to the specific methods' docstrings or simply to the
module's docstring for a list of all exceptions that might be
raised by this class' methods.
 
  Methods defined here:
__init__(self, dialog='dialog', DIALOGRC=None, compat='dialog', use_stdout=None, *, autowidgetsize=False)
Constructor for Dialog instances.
 
dialog     -- name of (or path to) the dialog-like program to
              use; if it contains a '/', it is assumed to be
              a path and is used as is; otherwise, it is
              looked for according to the contents of the
              PATH environment variable, which defaults to
              ":/bin:/usr/bin" if unset.
DIALOGRC --   string to pass to the dialog-like program as
              the DIALOGRC environment variable, or None if
              no modification to the environment regarding
              this variable should be done in the call to the
              dialog-like program
compat     -- compatibility mode (see below)
use_stdout -- read dialog's standard output stream instead of
              its standard error stream in order to get
              most 'results' (user-supplied strings, etc.;
              basically everything apart from the exit
              status). This is for compatibility with Xdialog
              and should only be used if you have a good
              reason to do so.
autowidgetsize -- boolean indicating whether to enable
              'autowidgetsize' mode. When enabled, all
              pythondialog widget-producing methods will
              behave as if width=0, height=0, etc. had been
              passed, except where these parameters are
              explicitely specified with different values.
              This has the effect that, by default, the
              'dialog' backend will automatically compute a
              suitable size for the widgets. More details
              about this option are given below.
 
The officially supported dialog-like program in pythondialog
is the well-known dialog program written in C, based on the
ncurses library. It is also known as cdialog and its home
page is currently (2013-08-12) located at:
 
    http://invisible-island.net/dialog/dialog.html
 
If you want to use a different program such as Xdialog, you
should indicate the executable file name with the 'dialog'
argument *and* the compatibility type that you think it
conforms to with the 'compat' argument. Currently, 'compat'
can be either "dialog" (for dialog; this is the default) or
"Xdialog" (for, well, Xdialog).
 
The 'compat' argument allows me to cope with minor
differences in behaviour between the various programs
implementing the dialog interface (not the text or graphical
interface, I mean the "API"). However, having to support
various APIs simultaneously is ugly and I would really prefer
you to report bugs to the relevant maintainers when you find
incompatibilities with dialog. This is for the benefit of
pretty much everyone that relies on the dialog interface.
 
Notes about the 'autowidgetsize' option
---------------------------------------
 
The 'autowidgetsize' option should be convenient in
situations where figuring out suitable widget size parameters
is a burden, for instance when developing little scripts that
don't need too much visual polishing, or when a widget is
used to display data, the size of which is not easily
predictable.
 
This option is implemented in the following way: for a given
size parameter (for instance, width) of a given widget, the
default value in the widget-producing method is now None if
it previously had a non-zero default. At runtime, if the
value seen by the widget-producing method is not None, it is
used as is; on the contrary, if that value is None, it is
automatically replaced with:
  - 0 if the Dialog instance has been initialized with
   'autowidgetsize' set to True;
  - the old default otherwise.
 
Notes:
  - the 'autowidgetsize' option is currently marked as
    experimental, please give some feedback;
  - you may encounter questionable results if you only set
    one of the 'width' and 'height' parameters to 0 for a
    given widget (seen in dialog 1.2-20140219).
 
Notable exceptions:
 
    ExecutableNotFound
    PythonDialogOSError
    UnableToRetrieveBackendVersion
    UnableToParseBackendVersion
add_persistent_args(self, args)
Add arguments to use for every subsequent dialog call.
 
This method cannot guess which elements of 'args' are dialog
options (such as '--title') and which are not (for instance,
you might want to use '--title' or even '--' as an argument
to a dialog option). Therefore, this method does not perform
any kind of dash escaping; you have to do it yourself.
dash_escape() and dash_escape_nf() may be useful for this
purpose.
backend_version(self)
Get the version of the dialog-like program (backend).
 
If the version of the dialog-like program can be retrieved,
return it as a string; otherwise, raise
UnableToRetrieveBackendVersion.
 
This version is not to be confused with the pythondialog
version.
 
In most cases, you should rather use the
'cached_backend_version' attribute of Dialog instances,
because:
  - it avoids calling the backend every time one needs the
    version;
  - it is a BackendVersion instance (or instance of a
    subclass) that allows easy and reliable comparisons
    between versions;
  - the version string corresponding to a BackendVersion
    instance (or instance of a subclass) can be obtained with
    str().
 
Notable exceptions:
 
    UnableToRetrieveBackendVersion
    PythonDialogReModuleError
    any exception raised by _perform()
buildlist(self, text, height=0, width=0, list_height=0, items=[], **kwargs)
Display a buildlist box.
 
text        -- text to display in the box
height      -- height of the box
width       -- width of the box
list_height -- height of the selected and unselected list
               boxes
items       -- a list of (tag, item, status) tuples where
               'status' specifies the initial
               selected/unselected state of each entry; can
               be True or False, 1 or 0, "on" or "off" (True,
               1 and "on" meaning selected), or any case
               variation of these two strings.
 
A buildlist dialog is similar in logic to the checklist but
differs in presentation. In this widget, two lists are
displayed, side by side. The list on the left shows
unselected items. The list on the right shows selected items.
As items are selected or unselected, they move between the
two lists. The 'status' component of 'items' specifies which
items are initially selected.
 
Return a tuple of the form (code, tags) where:
  - 'code' is the Dialog exit code;
  - 'tags' is a list of the tags corresponding to the
    selected items, in the order they have in the list on the
    right.
 
Keys: SPACE   select or deselect the highlighted item, i.e.,
              move it between the left and right lists
      ^       move the focus to the left list
      $       move the focus to the right list
      TAB     move focus (see 'visit_items' below)
      ENTER   press the focused button
 
If called with 'visit_items=True', the TAB key can move the
focus to the left and right lists, which is probably more
intuitive for users than the default behavior that requires
using ^ and $ for this purpose.
 
This widget requires dialog >= 1.2 (2012-12-30).
 
Notable exceptions:
 
    any exception raised by _perform() or _to_onoff()
calendar(self, text, height=None, width=0, day=0, month=0, year=0, **kwargs)
Display a calendar dialog box.
 
text   -- text to display in the box
height -- height of the box (minus the calendar height)
width  -- width of the box
day    -- inititial day highlighted
month  -- inititial month displayed
year   -- inititial year selected (0 causes the current date
          to be used as the initial date)
 
A calendar box displays month, day and year in separately
adjustable windows. If the values for day, month or year are
missing or negative, the current date's corresponding values
are used. You can increment or decrement any of those using
the left, up, right and down arrows. Use tab or backtab to
move between windows. If the year is given as zero, the
current date is used as an initial value.
 
Return a tuple of the form (code, date) where:
  - 'code' is the Dialog exit code;
  - 'date' is a list of the form [day, month, year], where
    'day', 'month' and 'year' are integers corresponding to
    the date chosen by the user.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=6.
 
Notable exceptions:
    - any exception raised by _perform()
    - UnexpectedDialogOutput
    - PythonDialogReModuleError
checklist(self, text, height=None, width=None, list_height=None, choices=[], **kwargs)
Display a checklist box.
 
text        -- text to display in the box
height      -- height of the box
width       -- width of the box
list_height -- number of entries displayed in the box (which
               can be scrolled) at a given time
choices     -- a list of tuples (tag, item, status) where
               'status' specifies the initial on/off state of
               each entry; can be True or False, 1 or 0, "on"
               or "off" (True, 1 and "on" meaning checked),
               or any case variation of these two strings.
 
Return a tuple of the form (code, [tag, ...]) with the tags
for the entries that were selected by the user. 'code' is the
Dialog exit code.
 
If the user exits with ESC or CANCEL, the returned tag list
is empty.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=15, width=54,
list_height=7.
 
Notable exceptions:
 
    any exception raised by _perform() or _to_onoff()
clear(self)
Clear the screen. Equivalent to the dialog --clear option.
 
This method is obsolete. Please remove calls to it from your
programs. You may use the clear(1) program to clear the screen.
cf. clear_screen() in examples/demo.py for an example.
dselect(self, filepath, height=0, width=0, **kwargs)
Display a directory selection dialog box.
 
filepath -- initial path
height   -- height of the box
width    -- width of the box
 
The directory-selection dialog displays a text-entry window
in which you can type a directory, and above that a window
with directory names.
 
Here, filepath can be a filepath in which case the directory
window will display the contents of the path and the
text-entry window will contain the preselected directory.
 
Use tab or arrow keys to move between the windows. Within the
directory window, use the up/down arrow keys to scroll the
current selection. Use the space-bar to copy the current
selection into the text-entry window.
 
Typing any printable characters switches focus to the
text-entry window, entering that character as well as
scrolling the directory window to the closest match.
 
Use a carriage return or the "OK" button to accept the
current value in the text-entry window and exit.
 
Return a tuple of the form (code, path) where 'code' is the
Dialog exit code and 'path' is the directory chosen by the
user.
 
Notable exceptions:
 
    any exception raised by _perform()
editbox(self, filepath, height=0, width=0, **kwargs)
Display a basic text editor dialog box.
 
filepath -- file which determines the initial contents of
            the dialog box
height   -- height of the box
width    -- width of the box
 
The editbox dialog displays a copy of the file contents. You
may edit it using the Backspace, Delete and cursor keys to
correct typing errors. It also recognizes Page Up and Page
Down. Unlike the inputbox, you must tab to the "OK" or
"Cancel" buttons to close the dialog. Pressing the "Enter"
key within the box will split the corresponding line.
 
Return a tuple of the form (code, text) where 'code' is the
Dialog exit code and 'text' is the contents of the text entry
window on exit.
 
Notable exceptions:
 
    any exception raised by _perform()
form(self, text, elements, height=0, width=0, form_height=0, **kwargs)
Display a form consisting of labels and fields.
 
text        -- text to display in the box
elements    -- sequence describing the labels and fields (see
               below)
height      -- height of the box
width       -- width of the box
form_height -- number of form lines displayed at the same time
 
A form box consists in a series of fields and associated
labels. This type of dialog is suitable for adjusting
configuration parameters and similar tasks.
 
Each element of 'elements' must itself be a sequence
(LABEL, YL, XL, ITEM, YI, XI, FIELD_LENGTH, INPUT_LENGTH)
containing the various parameters concerning a given field
and the associated label.
 
LABEL is a string that will be displayed at row YL, column
XL. ITEM is a string giving the initial value for the field,
which will be displayed at row YI, column XI (row and column
numbers starting from 1).
 
FIELD_LENGTH and INPUT_LENGTH are integers that respectively
specify the number of characters used for displaying the
field and the maximum number of characters that can be
entered for this field. These two integers also determine
whether the contents of the field can be modified, as
follows:
 
  - if FIELD_LENGTH is zero, the field cannot be altered and
    its contents determines the displayed length;
 
  - if FIELD_LENGTH is negative, the field cannot be altered
    and the opposite of FIELD_LENGTH gives the displayed
    length;
 
  - if INPUT_LENGTH is zero, it is set to FIELD_LENGTH.
 
Return a tuple of the form (code, list) where 'code' is the
Dialog exit code and 'list' gives the contents of every
editable field on exit, with the same order as in 'elements'.
 
Notable exceptions:
 
    BadPythonDialogUsage
    any exception raised by _perform()
fselect(self, filepath, height=0, width=0, **kwargs)
Display a file selection dialog box.
 
filepath -- initial file path
height   -- height of the box
width    -- width of the box
 
The file-selection dialog displays a text-entry window in
which you can type a filename (or directory), and above that
two windows with directory names and filenames.
 
Here, filepath can be a file path in which case the file and
directory windows will display the contents of the path and
the text-entry window will contain the preselected filename.
 
Use tab or arrow keys to move between the windows. Within the
directory or filename windows, use the up/down arrow keys to
scroll the current selection. Use the space-bar to copy the
current selection into the text-entry window.
 
Typing any printable character switches focus to the
text-entry window, entering that character as well as
scrolling the directory and filename windows to the closest
match.
 
Use a carriage return or the "OK" button to accept the
current value in the text-entry window, or the "Cancel"
button to cancel.
 
Return a tuple of the form (code, path) where 'code' is the
Dialog exit code and 'path' is the path chosen by the user
(the last element of which may be a directory or a file).
 
Notable exceptions:
 
    any exception raised by _perform()
gauge_iterate(*args, **kwargs)
# For "compatibility" with the old dialog.py...
gauge_start(self, text='', height=None, width=None, percent=0, **kwargs)
Display gauge box.
 
text    -- text to display in the box
height  -- height of the box
width   -- width of the box
percent -- initial percentage shown in the meter
 
A gauge box displays a meter along the bottom of the box. The
meter indicates a percentage.
 
This function starts the dialog-like program telling it to
display a gauge box with a text in it and an initial
percentage in the meter.
 
Return value: undefined.
 
 
Gauge typical usage
-------------------
 
Gauge typical usage (assuming that 'd' is an instance of the
Dialog class) looks like this:
    d.gauge_start()
    # do something
    d.gauge_update(10)       # 10% of the whole task is done
    # ...
    d.gauge_update(100, "any text here") # work is done
    exit_code = d.gauge_stop()           # cleanup actions
 
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=8, width=54.
 
Notable exceptions:
    - any exception raised by _call_program()
    - PythonDialogOSError
gauge_stop(self)
Terminate a running gauge widget.
 
This function performs the appropriate cleanup actions to
terminate a running gauge (started with 'gauge_start').
 
See the 'gauge_start' function's documentation for
information about how to use a gauge.
 
Return value: the Dialog exit code from the backend.
 
Notable exceptions:
    - any exception raised by
      _wait_for_program_termination()
    - PythonDialogIOError (PythonDialogOSError from
      Python 3.3 onwards) can be raised if closing the pipe
      used to talk to the dialog-like program fails.
gauge_update(self, percent, text='', update_text=False)
Update a running gauge box.
 
percent     -- new percentage (integer) to show in the gauge
               meter
text        -- new text to optionally display in the box
update_text -- boolean indicating whether to update the
               text in the box
 
This function updates the percentage shown by the meter of a
running gauge box (meaning 'gauge_start' must have been
called previously). If update_text is True, the text
displayed in the box is also updated.
 
See the 'gauge_start' function's documentation for
information about how to use a gauge.
 
Return value: undefined.
 
Notable exception: PythonDialogIOError (PythonDialogOSError
                   from Python 3.3 onwards) can be raised if
                   there is an I/O error while writing to the
                   pipe used to talk to the dialog-like
                   program.
infobox(self, text, height=None, width=None, **kwargs)
Display an information dialog box.
 
text   -- text to display in the box
height -- height of the box
width  -- width of the box
 
An info box is basically a message box. However, in this
case, dialog will exit immediately after displaying the
message to the user. The screen is not cleared when dialog
exits, so that the message will remain on the screen after
the method returns. This is useful when you want to inform
the user that some operations are carrying on that may
require some time to finish.
 
Return the Dialog exit code from the backend.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=10, width=30.
 
Notable exceptions:
 
    any exception raised by _perform()
inputbox(self, text, height=None, width=None, init='', **kwargs)
Display an input dialog box.
 
text   -- text to display in the box
height -- height of the box
width  -- width of the box
init   -- default input string
 
An input box is useful when you want to ask questions that
require the user to input a string as the answer. If init is
supplied it is used to initialize the input string. When
entering the string, the BACKSPACE key can be used to
correct typing errors. If the input string is longer than
can fit in the dialog box, the input field will be scrolled.
 
Return a tuple of the form (code, string) where 'code' is the
Dialog exit code and 'string' is the string entered by the
user.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=10, width=30.
 
Notable exceptions:
 
    any exception raised by _perform()
inputmenu(self, text, height=0, width=None, menu_height=None, choices=[], **kwargs)
Display an inputmenu dialog box.
 
text        -- text to display in the box
height      -- height of the box
width       -- width of the box
menu_height -- height of the menu (scrollable part)
choices     -- a sequence of (tag, item) tuples, the meaning
               of which is explained below
 
 
Overview
--------
 
An inputmenu box is a dialog box that can be used to present
a list of choices in the form of a menu for the user to
choose. Choices are displayed in the given order. The main
differences with the menu dialog box are:
 
  * entries are not automatically centered, but
    left-adjusted;
 
  * the current entry can be renamed by pressing the Rename
    button, which allows editing the 'item' part of the
    current entry.
 
Each menu entry consists of a 'tag' string and an 'item'
string. The tag gives the entry a name to distinguish it from
the other entries in the menu and to provide quick keyboard
access. The item is a short description of the option that
the entry represents.
 
The user can move between the menu entries by pressing the
UP/DOWN keys or the first letter of the tag as a hot key.
There are 'menu_height' lines (not entries!) displayed in the
scrollable part of the menu at one time.
 
BEWARE!
 
  It is strongly advised not to put any space in tags,
  otherwise the dialog output can be ambiguous if the
  corresponding entry is renamed, causing pythondialog to
  return a wrong tag string and new item text.
 
  The reason is that in this case, the dialog output is
  "RENAMED <tag> <item>" (without angle brackets) and
  pythondialog cannot guess whether spaces after the
  "RENAMED " prefix belong to the <tag> or the new <item>
  text.
 
Note: there is no point in calling this method with
      'help_status=True', because it is not possible to
      rename several items nor is it possible to choose the
      Help button (or any button other than Rename) once one
      has started to rename an item.
 
Return value
------------
 
Return a tuple of the form (exit_info, tag, new_item_text)
where:
 
'exit_info' is either:
  - the string "accepted", meaning that an entry was accepted
    without renaming;
  - the string "renamed", meaning that an entry was accepted
    after being renamed;
  - one of the standard Dialog exit codes Dialog.CANCEL,
    Dialog.ESC, Dialog.HELP.
 
'tag' indicates which entry was accepted (with or without
renaming), if any. If no entry was accepted (e.g., if the
dialog was exited with the Cancel button), then 'tag' is
None.
 
'new_item_text' gives the new 'item' part of the renamed
entry if 'exit_info' is "renamed", otherwise it is None.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: width=60, menu_height=7.
 
Notable exceptions:
 
    any exception raised by _perform()
maxsize(self, **kwargs)
Get the maximum size of dialog boxes.
 
If the exit code from the backend is self.OK, return a
(lines, cols) tuple of integers; otherwise, return None.
 
If you want to obtain the number of lines and columns of the
terminal, you should call this method with
use_persistent_args=False, because arguments such as
--backtitle modify the values returned.
 
Notable exceptions:
 
    PythonDialogReModuleError
    any exception raised by _perform()
menu(self, text, height=None, width=None, menu_height=None, choices=[], **kwargs)
Display a menu dialog box.
 
text        -- text to display in the box
height      -- height of the box
width       -- width of the box
menu_height -- number of entries displayed in the box (which
               can be scrolled) at a given time
choices     -- a sequence of (tag, item) tuples (see below)
 
 
Overview
--------
 
As its name suggests, a menu box is a dialog box that can be
used to present a list of choices in the form of a menu for
the user to choose. Choices are displayed in the given order.
 
Each menu entry consists of a 'tag' string and an 'item'
string. The tag gives the entry a name to distinguish it from
the other entries in the menu and to provide quick keyboard
access. The item is a short description of the option that
the entry represents.
 
The user can move between the menu entries by pressing the
UP/DOWN keys, the first letter of the tag as a hot key, or
the number keys 1-9. There are 'menu_height' entries
displayed in the menu at one time, but the menu will be
scrolled if there are more entries than that.
 
 
Return value
------------
 
Return a tuple of the form (code, tag) where 'code' is the
Dialog exit code and 'tag' the tag string of the item that
the user chose.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=15, width=54,
menu_height=7.
 
Notable exceptions:
 
    any exception raised by _perform()
mixedform(self, text, elements, height=0, width=0, form_height=0, **kwargs)
Display a form consisting of labels and fields.
 
text        -- text to display in the box
elements    -- sequence describing the labels and fields (see
               below)
height      -- height of the box
width       -- width of the box
form_height -- number of form lines displayed at the same time
 
A mixedform box is very similar to a form box, and differs
from the latter by allowing field attributes to be specified.
 
Each element of 'elements' must itself be a sequence (LABEL,
YL, XL, ITEM, YI, XI, FIELD_LENGTH, INPUT_LENGTH, ATTRIBUTES)
containing the various parameters concerning a given field
and the associated label.
 
ATTRIBUTES is a bit mask with the following meaning:
 
  bit 0  -- the field should be hidden (e.g., a password)
  bit 1  -- the field should be read-only (e.g., a label)
 
For all other parameters, please refer to the documentation
of the form box.
 
The return value is the same as would be with the form box,
except that field marked as read-only with bit 1 of
ATTRIBUTES are also included in the output list.
 
Notable exceptions:
 
    BadPythonDialogUsage
    any exception raised by _perform()
mixedgauge(self, text, height=0, width=0, percent=0, elements=[], **kwargs)
Display a mixed gauge dialog box.
 
text        -- text to display in the middle of the box,
               between the elements list and the progress bar
height      -- height of the box
width       -- width of the box
percent     -- integer giving the percentage for the global
               progress bar
elements    -- a sequence of (tag, item) tuples, the meaning
               of which is explained below
 
A mixedgauge box displays a list of "elements" with status
indication for each of them, followed by a text and finally a
(global) progress bar along the bottom of the box.
 
The top part ('elements') is suitable for displaying a task
list. One element is displayed per line, with its 'tag' part
on the left and its 'item' part on the right. The 'item' part
is a string that is displayed on the right of the same line.
 
The 'item' of an element can be an arbitrary string, but
special values listed in the dialog(3) manual page translate
into a status indication for the corresponding task ('tag'),
such as: "Succeeded", "Failed", "Passed", "Completed", "Done",
"Skipped", "In Progress", "Checked", "N/A" or a progress
bar.
 
A progress bar for an element is obtained by supplying a
negative number for the 'item'. For instance, "-75" will
cause a progress bar indicating 75 % to be displayed on the
corresponding line.
 
For your convenience, if an 'item' appears to be an integer
or a float, it will be converted to a string before being
passed to the dialog-like program.
 
'text' is shown as a sort of caption between the list and the
global progress bar. The latter displays 'percent' as the
percentage of completion.
 
Contrary to the gauge widget, mixedgauge is completely
static. You have to call mixedgauge() several times in order
to display different percentages in the global progress bar,
or status indicators for a given task.
 
Return the Dialog exit code from the backend.
 
Notable exceptions:
 
    any exception raised by _perform()
msgbox(self, text, height=None, width=None, **kwargs)
Display a message dialog box, with scrolling and line wrapping.
 
text   -- text to display in the box
height -- height of the box
width  -- width of the box
 
Display a text in a message box, with a scrollbar and
percentage indication if the text is too long to fit in a
single "screen".
 
A message box is very similar to a yes/no box. The only
difference between a message box and a yes/no box is that a
message box has only a single OK button. You can use this
dialog box to display any message you like. After reading
the message, the user can press the Enter key so that dialog
will exit and the calling program can continue its
operation.
 
msgbox() performs automatic line wrapping. If you want to
force a newline at some point, simply insert it in 'text'. In
other words (with the default settings), newline characters
in 'text' *are* respected; the line wrapping process
performed by dialog only inserts *additional* newlines when
needed. If you want no automatic line wrapping, consider
using scrollbox().
 
Return the Dialog exit code from the backend.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=10, width=30.
 
Notable exceptions:
 
    any exception raised by _perform()
passwordbox(self, text, height=None, width=None, init='', **kwargs)
Display a password input dialog box.
 
text   -- text to display in the box
height -- height of the box
width  -- width of the box
init   -- default input password
 
A password box is similar to an input box, except that the
text the user enters is not displayed. This is useful when
prompting for passwords or other sensitive information. Be
aware that if anything is passed in "init", it will be
visible in the system's process table to casual snoopers.
Also, it is very confusing to the user to provide them with a
default password they cannot see. For these reasons, using
"init" is highly discouraged.
 
By default (as in dialog), nothing is echoed to the terminal
as the user enters the sensitive text. This can be confusing
to users. Use the 'insecure' keyword argument if you want an
asterisk to be echoed for each character entered by the user.
 
Return a tuple of the form (code, password) where 'code' is
the Dialog exit code and 'password' is the password entered
by the user.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=10, width=60.
 
Notable exceptions:
 
    any exception raised by _perform()
passwordform(self, text, elements, height=0, width=0, form_height=0, **kwargs)
Display a form consisting of labels and invisible fields.
 
This widget is identical to the form box, except that all
text fields are treated as passwordbox widgets rather than
inputbox widgets.
 
By default (as in dialog), nothing is echoed to the terminal
as the user types in the invisible fields. This can be
confusing to users. Use the 'insecure' keyword argument if
you want an asterisk to be echoed for each character entered
by the user.
 
Notable exceptions:
 
    BadPythonDialogUsage
    any exception raised by _perform()
pause(self, text, height=None, width=None, seconds=5, **kwargs)
Display a pause dialog box.
 
text       -- text to display in the box
height     -- height of the box
width      -- width of the box
seconds    -- number of seconds to pause for (integer)
 
A pause box displays a text and a meter along the bottom of
the box, during a specified amount of time ('seconds'). The
meter indicates how many seconds remain until the end of the
pause. The widget exits when the specified number of seconds
is elapsed, or immediately if the user presses the OK button,
the Cancel button or the Esc key.
 
Return the Dialog exit code, which is Dialog.OK if the pause
ended automatically after 'seconds' seconds or if the user
pressed the OK button.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=15, width=60.
 
Notable exceptions:
 
    any exception raised by _perform()
programbox(self, file_path=None, file_flags=0, fd=None, text=None, height=None, width=None, **kwargs)
Display a possibly growing stream in a dialog box, as with "tail -f".
 
A programbox is very similar to a progressbox. The only
difference between a program box and a progress box is that a
program box displays an OK button, but only after the input
stream has been exhausted (i.e., End Of File has been
reached).
 
This dialog box can be used to display the piped output of an
external program. After the program completes, the user can
press the Enter key to close the dialog and resume execution
of the calling program.
 
The parameters and exceptions are the same as for
'progressbox'. Please refer to the corresponding
documentation.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=20, width=78.
 
This widget requires dialog >= 1.1 (2011-03-02).
progressbox(self, file_path=None, file_flags=0, fd=None, text=None, height=None, width=None, **kwargs)
Display a possibly growing stream in a dialog box, as with "tail -f".
 
  file_path  -- path to the file that is going to be displayed
  file_flags -- flags used when opening 'file_path'; those
                are passed to os.open() function (not the
                built-in open function!). By default, only
                one flag is used: os.O_RDONLY.
 
OR, ALTERNATIVELY:
 
  fd       -- file descriptor for the stream to be displayed
 
text     -- caption continuously displayed at the top, above the
            stream text, or None to disable the caption
height   -- height of the box
width    -- width of the box
 
Display the contents of the specified file, updating the
dialog box whenever the file grows, as with the "tail -f"
command.
 
The file can be specified in two ways:
  - either by giving its path (and optionally os.open()
    flags) with parameters 'file_path' and 'file_flags';
  - or by passing its file descriptor with parameter 'fd' (in
    which case it may not even be a file; for instance, it
    could be an anonymous pipe created with os.pipe()).
 
Return the Dialog exit code from the backend.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=20, width=78.
 
Notable exceptions:
 
    PythonDialogIOError    if the Python version is < 3.3
    PythonDialogOSError
    any exception raised by _perform()
radiolist(self, text, height=None, width=None, list_height=None, choices=[], **kwargs)
Display a radiolist box.
 
text        -- text to display in the box
height      -- height of the box
width       -- width of the box
list_height -- number of entries displayed in the box (which
               can be scrolled) at a given time
choices     -- a list of tuples (tag, item, status) where
               'status' specifies the initial on/off state of
               each entry; can be True or False, 1 or 0, "on"
               or "off" (True and 1 meaning "on"), or any case
               variation of these two strings. No more than
               one entry should be set to True.
 
A radiolist box is similar to a menu box. The main difference
is that you can indicate which entry is initially selected,
by setting its status to True.
 
Return a tuple of the form (code, tag) with the tag for the
entry that was chosen by the user. 'code' is the Dialog exit
code from the backend.
 
If the user exits with ESC or CANCEL, or if all entries were
initially set to False and not altered before the user chose
OK, the returned tag is the empty string.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=15, width=54,
list_height=7.
 
Notable exceptions:
 
    any exception raised by _perform() or _to_onoff()
rangebox(self, text, height=0, width=0, min=None, max=None, init=None, **kwargs)
Display an range dialog box.
 
text   -- text to display above the actual range control
height -- height of the box
width  -- width of the box
min    -- minimum value for the range control
max    -- maximum value for the range control
init   -- initial value for the range control
 
The rangebox dialog allows the user to select from a range of
values using a kind of slider. The range control shows the
current value as a bar (like the gauge dialog).
 
The return value is a tuple of the form (code, val) where
'code' is the Dialog exit code and 'val' is an integer: the
value chosen by the user.
 
The Tab and arrow keys move the cursor between the buttons
and the range control. When the cursor is on the latter, you
can change the value with the following keys:
 
  Left/Right arrows   select a digit to modify
 
  +/-                 increment/decrement the selected digit
                      by one unit
 
  0-9                 set the selected digit to the given
                      value
 
Some keys are also recognized in all cursor positions:
 
  Home/End            set the value to its minimum or maximum
 
  PageUp/PageDown     decrement/increment the value so that
                      the slider moves by one column
 
This widget requires dialog >= 1.2 (2012-12-30).
 
Notable exceptions:
 
    any exception raised by _perform()
scrollbox(self, text, height=None, width=None, **kwargs)
Display a string in a scrollable box, with no line wrapping.
 
text   -- string to display in the box
height -- height of the box
width  -- width of the box
 
This method is a layer on top of textbox. The textbox widget
in dialog allows to display file contents only. This method
allows you to display any text in a scrollable box. This is
simply done by creating a temporary file, calling textbox() and
deleting the temporary file afterwards.
 
The text is not automatically wrapped. New lines in the
scrollable box will be placed exactly as in 'text'. If you
want automatic line wrapping, you should use the msgbox
widget instead (the 'textwrap' module from the Python
standard library is also worth knowing about).
 
Return the Dialog exit code from the backend.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=20, width=78.
 
Notable exceptions:
    - PythonDialogIOError    if the Python version is < 3.3
    - PythonDialogOSError
setBackgroundTitle(self, text)
Set the background title for dialog.
 
text   -- string to use as the background title
 
This method is obsolete. Please remove calls to it from your
programs.
set_background_title(self, text)
Set the background title for dialog.
 
text   -- string to use as the background title
setup_debug(self, enable, file=None, always_flush=False)
Setup the debugging parameters.
 
When enabled, all dialog commands are written to 'file' using
Bourne shell syntax.
 
enable         -- boolean indicating whether to enable or
                  disable debugging
file           -- file object where to write debugging
                  information
always_flush   -- boolean indicating whether to call
                  file.flush() after each command written
tailbox(self, filename, height=None, width=None, **kwargs)
Display the contents of a file in a dialog box, as with "tail -f".
 
filename -- name of the file, the contents of which is to be
            displayed in the box
height   -- height of the box
width    -- width of the box
 
Display the contents of the specified file, updating the
dialog box whenever the file grows, as with the "tail -f"
command.
 
Return the Dialog exit code from the backend.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=20, width=60.
 
Notable exceptions:
 
    any exception raised by _perform()
textbox(self, filename, height=None, width=None, **kwargs)
Display the contents of a file in a dialog box.
 
filename -- name of the file whose contents is to be
            displayed in the box
height   -- height of the box
width    -- width of the box
 
A text box lets you display the contents of a text file in a
dialog box. It is like a simple text file viewer. The user
can move through the file by using the UP/DOWN, PGUP/PGDN
and HOME/END keys available on most keyboards. If the lines
are too long to be displayed in the box, the LEFT/RIGHT keys
can be used to scroll the text region horizontally. For more
convenience, forward and backward searching functions are
also provided.
 
Return the Dialog exit code from the backend.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=20, width=60.
 
Notable exceptions:
 
    any exception raised by _perform()
timebox(self, text, height=None, width=None, hour=-1, minute=-1, second=-1, **kwargs)
Display a time dialog box.
 
text   -- text to display in the box
height -- height of the box
width  -- width of the box
hour   -- inititial hour selected
minute -- inititial minute selected
second -- inititial second selected
 
A dialog is displayed which allows you to select hour, minute
and second. If the values for hour, minute or second are
negative (or not explicitely provided, as they default to
-1), the current time's corresponding values are used. You
can increment or decrement any of those using the left-, up-,
right- and down-arrows. Use tab or backtab to move between
windows.
 
Return a tuple of the form (code, time) where:
  - 'code' is the Dialog exit code;
  - 'time' is a list of the form [hour, minute, second],
    where 'hour', 'minute' and 'second' are integers
    corresponding to the time chosen by the user.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=3, width=30.
 
Notable exceptions:
    - any exception raised by _perform()
    - PythonDialogReModuleError
    - UnexpectedDialogOutput
treeview(self, text, height=0, width=0, list_height=0, nodes=[], **kwargs)
Display a treeview box.
 
text        -- text to display at the top of the box
height      -- height of the box
width       -- width of the box
list_height -- number of lines reserved for the main part of
               the box, where the tree is displayed
nodes       -- a list of (tag, item, status, depth) tuples
               describing nodes, where:
                 - 'tag' is used to indicate which node was
                   selected by the user on exit;
                 - 'item' is the text displayed for the node;
                 - 'status' specifies the initial on/off
                   state of each node; can be True or False,
                   1 or 0, "on" or "off" (True, 1 and "on"
                   meaning selected), or any case variation
                   of these two strings;
                 - 'depth' is a non-negative integer
                   indicating the depth of the node in the
                   tree (0 for the root node).
 
Display nodes organized in a tree structure. Each node has a
tag, an 'item' text, a selected status, and a depth in the
tree. Only the 'item' texts are displayed in the widget; tags
are only used for the return value. Only one node can be
selected at a given time, as for the radiolist widget.
 
Return a tuple of the form (code, tag) where:
  - 'code' is the Dialog exit code from the backend;
  - 'tag' is the tag of the selected node.
 
This widget requires dialog >= 1.2 (2012-12-30).
 
Notable exceptions:
 
    any exception raised by _perform() or _to_onoff()
yesno(self, text, height=None, width=None, **kwargs)
Display a yes/no dialog box.
 
text   -- text to display in the box
height -- height of the box
width  -- width of the box
 
A yes/no dialog box of size 'height' rows by 'width' columns
will be displayed. The string specified by 'text' is
displayed inside the dialog box. If this string is too long
to fit in one line, it will be automatically divided into
multiple lines at appropriate places. The text string can
also contain the sub-string "\n" or newline characters to
control line breaking explicitly. This dialog box is useful
for asking questions that require the user to answer either
yes or no. The dialog box has a Yes button and a No button,
in which the user can switch between by pressing the TAB
key.
 
Return the Dialog exit code from the backend.
 
Default values for the size parameters when the
'autowidgetsize' option is disabled: height=10, width=30.
 
Notable exceptions:
 
    any exception raised by _perform()

Class methods defined here:
dash_escape(args) from builtins.type
Escape all elements of 'args' that need escaping.
 
'args' may be any sequence and is not modified by this method.
Return a new list where every element that needs escaping has
been escaped.
 
An element needs escaping when it starts with two ASCII hyphens
('--'). Escaping consists in prepending an element composed of
two ASCII hyphens, i.e., the string '--'.
 
All high-level Dialog methods automatically perform dash
escaping where appropriate. In particular, this is the case
for every method that provides a widget: yesno(), msgbox(),
etc. You only need to do it yourself when calling a low-level
method such as add_persistent_args().
dash_escape_nf(args) from builtins.type
Escape all elements of 'args' that need escaping, except the first one.
 
See dash_escape() for details. Return a new list.
 
All high-level Dialog methods automatically perform dash
escaping where appropriate. In particular, this is the case
for every method that provides a widget: yesno(), msgbox(),
etc. You only need to do it yourself when calling a low-level
method such as add_persistent_args().

Data descriptors defined here:
DIALOG_CANCEL
Obsolete property superseded by Dialog.CANCEL
DIALOG_ERROR
DIALOG_ESC
Obsolete property superseded by Dialog.ESC
DIALOG_EXTRA
Obsolete property superseded by Dialog.EXTRA
DIALOG_HELP
Obsolete property superseded by Dialog.HELP
DIALOG_ITEM_HELP
Obsolete property superseded by Dialog.HELP
DIALOG_OK
Obsolete property superseded by Dialog.OK
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
CANCEL = 'cancel'
ESC = 'esc'
EXTRA = 'extra'
HELP = 'help'
OK = 'ok'

 
class DialogBackendVersion(BackendVersion)
    Class representing possible versions of the dialog backend.
 
The purpose of this class is to make it easy to reliably compare
between versions of the dialog backend. It encapsulates the
specific details of the backend versioning scheme to allow
eventual adaptations to changes in this scheme without affecting
external code.
 
The version is represented by two components in this class: the
"dotted part" and the "rest". For instance, in the '1.2' version
string, the dotted part is [1, 2] and the rest is the empty
string. However, in version '1.2-20130902', the dotted part is
still [1, 2], but the rest is the string '-20130902'.
 
Instances of this class can be created with the constructor by
specifying the dotted part and the rest. Alternatively, an
instance can be created from the corresponding version string
(e.g., '1.2-20130902') using the fromstring() class method. This
is particularly useful with the result of d.backend_version(),
where 'd' is a Dialog instance. Actually, the main constructor
detects if its first argument is a string and calls fromstring()
in this case as a convenience. Therefore, all of the following
expressions are valid to create a DialogBackendVersion instance:
 
  DialogBackendVersion([1, 2])
  DialogBackendVersion([1, 2], "-20130902")
  DialogBackendVersion("1.2-20130902")
  DialogBackendVersion.fromstring("1.2-20130902")
 
If 'bv' is a DialogBackendVersion instance, str(bv) is a string
representing the same version (for instance, "1.2-20130902").
 
Two DialogBackendVersion instances can be compared with the usual
comparison operators (<, <=, ==, !=, >=, >). The algorithm is
designed so that the following order is respected (after
instanciation with fromstring()):
 
  1.2 < 1.2-20130902 < 1.2-20130903 < 1.2.0 < 1.2.0-20130902
 
among other cases. Actually, the "dotted parts" are the primary
keys when comparing and "rest" strings act as secondary keys.
Dotted parts are compared with the standard Python list
comparison and "rest" strings using the standard Python string
comparison.
 
 
Method resolution order:
DialogBackendVersion
BackendVersion
builtins.object

Methods defined here:
__eq__(self, other)
__ge__(self, other)
__gt__(self, other)
__init__(self, dotted_part_or_str, rest='')
Create a DialogBackendVersion instance.
 
Please see the class docstring for details.
__le__(self, other)
__lt__(self, other)
__ne__(self, other)
# Python 3.2 has a decorator (functools.total_ordering) to automate this.
__repr__(self)
__str__(self)

Class methods defined here:
fromstring(s) from abc.ABCMeta

Data and other attributes defined here:
__abstractmethods__ = frozenset([])
__hash__ = None

Data descriptors inherited from BackendVersion:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class DialogError(error)
    Exception raised when the dialog-like program exits with the code indicating an error.
 
 
Method resolution order:
DialogError
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'dialog-like terminated due to an error'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class DialogTerminatedBySignal(error)
    Exception raised when the dialog-like program is terminated by a signal.
 
 
Method resolution order:
DialogTerminatedBySignal
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'dialog-like terminated by a signal'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class ExecutableNotFound(error)
    Exception raised when the dialog executable can't be found.
 
 
Method resolution order:
ExecutableNotFound
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Executable not found'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class InadequateBackendVersion(error)
    Exception raised when the backend version in use is inadequate in a given situation.
 
 
Method resolution order:
InadequateBackendVersion
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Inadequate backend version'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class ProbablyPythonBug(error)
    Exception raised when pythondialog behaves in a way that seems to indicate a Python bug.
 
 
Method resolution order:
ProbablyPythonBug
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Bug in python, probably'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class PythonDialogBug(error)
    Exception raised when pythondialog finds a bug in his own code.
 
 
Method resolution order:
PythonDialogBug
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Bug in pythondialog'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class PythonDialogErrorBeforeExecInChildProcess(PythonDialogSystemError)
    Exception raised when an exception is caught in a child process before the exec sytem call (included).
 
This can happen in uncomfortable situations such as:
  - the system being out of memory;
  - the maximum number of open file descriptors being reached;
  - the dialog-like program being removed (or made
    non-executable) between the time we found it with
    _find_in_path and the time the exec system call attempted to
    execute it;
  - the Python program trying to call the dialog-like program
    with arguments that cannot be represented in the user's
    locale (LC_CTYPE).
 
 
Method resolution order:
PythonDialogErrorBeforeExecInChildProcess
PythonDialogSystemError
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Error in a child process before the exec system call'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
PythonDialogException = class error(builtins.Exception)
    Base class for exceptions in pythondialog.
 
 
Method resolution order:
error
builtins.Exception
builtins.BaseException
builtins.object

Methods defined here:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
ExceptionShortDescription = 'pythondialog generic exception'

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class PythonDialogIOError(PythonDialogOSError)
    Exception raised when pythondialog catches an IOError exception that should be passed to the calling program.
 
This exception should not be raised starting from Python 3.3, as
the built-in exception IOError becomes an alias of OSError.
 
 
Method resolution order:
PythonDialogIOError
PythonDialogOSError
PythonDialogSystemError
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'IO error'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class PythonDialogOSError(PythonDialogSystemError)
    Exception raised when pythondialog catches an OSError exception that should be passed to the calling program.
 
 
Method resolution order:
PythonDialogOSError
PythonDialogSystemError
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'OS error'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class PythonDialogReModuleError(PythonDialogSystemError)
    Exception raised when pythondialog catches a re.error exception.
 
 
Method resolution order:
PythonDialogReModuleError
PythonDialogSystemError
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = "'re' module error"

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class PythonDialogSystemError(error)
    Exception raised when pythondialog cannot perform a "system operation" (e.g., a system call) that should work in "normal" situations.
 
This is a convenience exception: PythonDialogIOErrorPythonDialogOSError
and PythonDialogErrorBeforeExecInChildProcess all derive from this
exception. As a consequence, watching for PythonDialogSystemError instead
of the aformentioned exceptions is enough if you don't need precise
details about these kinds of errors.
 
Don't confuse this exception with Python's builtin SystemError
exception.
 
 
Method resolution order:
PythonDialogSystemError
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'System error'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class UnableToParseBackendVersion(error)
    Exception raised when we cannot parse the version string of the dialog-like backend.
 
 
Method resolution order:
UnableToParseBackendVersion
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Unable to parse as a dialog-like backend version string'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class UnableToParseDialogBackendVersion(UnableToParseBackendVersion)
    Exception raised when we cannot parse the version string of the dialog backend.
 
 
Method resolution order:
UnableToParseDialogBackendVersion
UnableToParseBackendVersion
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Unable to parse as a dialog version string'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class UnableToRetrieveBackendVersion(error)
    Exception raised when we cannot retrieve the version string of the dialog-like backend.
 
 
Method resolution order:
UnableToRetrieveBackendVersion
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Unable to retrieve the version of the dialog-like backend'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class UnexpectedDialogOutput(error)
    Exception raised when the dialog-like program returns something not expected by pythondialog.
 
 
Method resolution order:
UnexpectedDialogOutput
error
builtins.Exception
builtins.BaseException
builtins.object

Data and other attributes defined here:
ExceptionShortDescription = 'Unexpected dialog output'

Methods inherited from error:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors inherited from error:
__weakref__
list of weak references to the object (if defined)

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
class VersionInfo(VersionInfo)
    
Method resolution order:
VersionInfo
VersionInfo
builtins.tuple
builtins.object

Methods defined here:
__repr__(self)
__str__(self)

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)

Methods inherited from VersionInfo:
__getnewargs__(self)
Return self as a plain tuple.  Used by copy and pickle.
__getstate__(self)
Exclude the OrderedDict from pickling
_asdict(self)
Return a new OrderedDict which maps field names to their values.
_replace(_self, **kwds)
Return a new VersionInfo object replacing specified fields with new values

Class methods inherited from VersionInfo:
_make(iterable, new=, len=) from builtins.type
Make a new VersionInfo object from a sequence or iterable

Static methods inherited from VersionInfo:
__new__(_cls, major, minor, micro, releasesuffix)
Create new instance of VersionInfo(major, minor, micro, releasesuffix)

Data descriptors inherited from VersionInfo:
major
Alias for field number 0
micro
Alias for field number 2
minor
Alias for field number 1
releasesuffix
Alias for field number 3

Data and other attributes inherited from VersionInfo:
_fields = ('major', 'minor', 'micro', 'releasesuffix')
_source = "from builtins import property as _property, tupl..._itemgetter(3), doc='Alias for field number 3')\n\n"

Methods inherited from builtins.tuple:
__add__(self, value, /)
Return self+value.
__contains__(self, key, /)
Return key in self.
__eq__(self, value, /)
Return self==value.
__ge__(self, value, /)
Return self>=value.
__getattribute__(self, name, /)
Return getattr(self, name).
__getitem__(self, key, /)
Return self[key].
__gt__(self, value, /)
Return self>value.
__hash__(self, /)
Return hash(self).
__iter__(self, /)
Implement iter(self).
__le__(self, value, /)
Return self<=value.
__len__(self, /)
Return len(self).
__lt__(self, value, /)
Return self<value.
__mul__(self, value, /)
Return self*value.n
__ne__(self, value, /)
Return self!=value.
__rmul__(self, value, /)
Return self*value.
__sizeof__(...)
T.__sizeof__() -- size of T in memory, in bytes
count(...)
T.count(value) -> integer -- return number of occurrences of value
index(...)
T.index(value, [start, [stop]]) -> integer -- return first index of value.
Raises ValueError if the value is not present.

 
class error(builtins.Exception)
    Base class for exceptions in pythondialog.
 
 
Method resolution order:
error
builtins.Exception
builtins.BaseException
builtins.object

Methods defined here:
__init__(self, message=None)
__repr__(self)
__str__(self)
complete_message(self)

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
ExceptionShortDescription = 'pythondialog generic exception'

Methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__reduce__(...)
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__dict__
__suppress_context__
__traceback__
args

 
Functions
       
retval_is_code(func)
Decorator for Dialog widget-producing methods whose return value is the Dialog exit code.
 
This decorator is intended for widget-producing methods whose
return value consists solely of the Dialog exit code. When this
decorator is *not* used on a widget-producing method, the Dialog
exit code must be the first element of the return value.
widget(func)
Decorator to mark Dialog methods that provide widgets.
 
This allows code to perform automatic operations on these
specific methods. For instance, one can define a class that
behaves similarly to Dialog, except that after every
widget-producing call, it spawns a "confirm quit" dialog if the
widget returned Dialog.ESC, and loops in case the user doesn't
actually want to quit.
 
When it is unclear whether a method should have the decorator or
not, the return value is used to draw the line. For instance,
among 'gauge_start', 'gauge_update' and 'gauge_stop', only the
last one has the decorator because it returns a Dialog exit code,
whereas the first two don't return anything meaningful.
 
Note:
 
  Some widget-producing methods return the Dialog exit code, but
  other methods return a *sequence*, the first element of which
  is the Dialog exit code; the 'retval_is_code' attribute, which
  is set by the decorator of the same name, allows to
  programmatically discover the interface a given method conforms
  to.

 
Data
        version_info = dialog.VersionInfo(major=3, minor=1, micro=0, releasesuffix=None)