python-dialog 3.3.0-2 / usr / lib / python2.7 / dist-packages / dialog.py

# dialog.py --- A Python interface to the ncurses-based "dialog" utility
# -*- coding: utf-8 -*-
#
# Copyright (C) 2002, 2003, 2004, 2009, 2010, 2013, 2014, 2015  Florent Rougon
# Copyright (C) 2004  Peter Åstrand
# Copyright (C) 2000  Robb Shecter, Sultanbek Tezadov
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
# MA  02110-1301 USA.

"""Python interface to :program:`dialog`-like programs.

This module provides a Python interface to :program:`dialog`-like
programs such as :program:`dialog` and :program:`Xdialog`.

It provides a :class:`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.

See the pythondialog manual for detailed documentation.

"""

from __future__ import with_statement, unicode_literals, print_function
import collections
from itertools import imap
from itertools import izip
from io import open
import locale

_VersionInfo = collections.namedtuple(
    "VersionInfo", ("major", "minor", "micro", "releasesuffix"))

class VersionInfo(_VersionInfo):
    """Class used to represent the version of pythondialog.

    This class is based on :func:`collections.namedtuple` and has the
    following field names: ``major``, ``minor``, ``micro``,
    ``releasesuffix``.

    .. versionadded:: 2.14
    """
    def __unicode__(self):
        """Return an Unicode representation of the version."""
        res = ".".join( ( unicode(elt) for elt in self[:3] ) )
        if self.releasesuffix:
            res += self.releasesuffix
        return res

    def __repr__(self):
        # Unicode strings are not supported as the result of __repr__()
        # in Python 2.x (cf. <http://bugs.python.org/issue5876>).
        return b"{0}.{1}".format(__name__, _VersionInfo.__repr__(self))

#: Version of pythondialog as a :class:`VersionInfo` instance.
#:
#: .. versionadded:: 2.14
version_info = VersionInfo(3, 3, 0, None)
#: Version of pythondialog as an Unicode string.
#:
#: .. versionadded:: 2.12
__version__ = unicode(version_info)


import sys, os, tempfile, random, re, warnings, traceback
from contextlib import contextmanager
from textwrap import dedent

# This is not for calling programs, only to prepare the shell commands that are
# written to the debug log when debugging is enabled.
try:
    from shlex import quote as _shell_quote
except ImportError:
    def _shell_quote(s):
        return "'%s'" % s.replace("'", "'\"'\"'")


# Exceptions raised by this module
#
# When adding, suppressing, renaming exceptions or changing their
# hierarchy, don't forget to update the module's docstring.
class error(Exception):
    """Base class for exceptions in pythondialog."""
    def __init__(self, message=None):
        self.message = message

    def __unicode__(self):
        return self.complete_message()

    def __repr__(self):
        # Unicode strings are not supported as the result of __repr__()
        # in Python 2.x (cf. <http://bugs.python.org/issue5876>).
        return b"{0}.{1}({2!r})".format(__name__, self.__class__.__name__,
                                        self.message)

    def complete_message(self):
        if self.message:
            return "{0}: {1}".format(self.ExceptionShortDescription,
                                     self.message)
        else:
            return self.ExceptionShortDescription

    ExceptionShortDescription = "{0} generic exception".format("pythondialog")

# For backward-compatibility
#
# Note: this exception was not documented (only the specific ones were), so
#       the backward-compatibility binding could be removed relatively easily.
PythonDialogException = error

class ExecutableNotFound(error):
    """Exception raised when the :program:`dialog` executable can't be found."""
    ExceptionShortDescription = "Executable not found"

class PythonDialogBug(error):
    """Exception raised when pythondialog finds a bug in his own code."""
    ExceptionShortDescription = "Bug in pythondialog"

# Yeah, the "Probably" makes it look a bit ugly, but:
#   - this is more accurate
#   - this avoids a potential clash with an eventual PythonBug built-in
#     exception in the Python interpreter...
class ProbablyPythonBug(error):
    """Exception raised when pythondialog behaves in a way that seems to \
indicate a Python bug."""
    ExceptionShortDescription = "Bug in python, probably"

class BadPythonDialogUsage(error):
    """Exception raised when pythondialog is used in an incorrect way."""
    ExceptionShortDescription = "Invalid use of pythondialog"

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: :exc:`PythonDialogIOError`,
    :exc:`PythonDialogOSError` and
    :exc:`PythonDialogErrorBeforeExecInChildProcess` all derive from
    this exception. As a consequence, watching for
    :exc:`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
    :exc:`SystemError` exception.

    """
    ExceptionShortDescription = "System error"

class PythonDialogOSError(PythonDialogSystemError):
    """Exception raised when pythondialog catches an :exc:`OSError` exception \
that should be passed to the calling program."""
    ExceptionShortDescription = "OS error"

class PythonDialogIOError(PythonDialogOSError):
    """Exception raised when pythondialog catches an :exc:`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 :exc:`IOError` becomes an alias of
    :exc:`OSError`.

    .. versionchanged:: 2.12
       :exc:`PythonDialogIOError` is now a subclass of
       :exc:`PythonDialogOSError` in order to help with the transition
       from :exc:`IOError` to :exc:`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.

    """
    ExceptionShortDescription = "IO error"

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 :program:`dialog`-like program being removed (or made
        non-executable) between the time we found it with
        :func:`_find_in_path` and the time the exec system call
        attempted to execute it;
      - the Python program trying to call the :program:`dialog`-like
        program with arguments that cannot be represented in the user's
        locale (:envvar:`LC_CTYPE`).

    """
    ExceptionShortDescription = "Error in a child process before the exec " \
                                "system call"

class PythonDialogReModuleError(PythonDialogSystemError):
    """Exception raised when pythondialog catches a :exc:`re.error` exception."""
    ExceptionShortDescription = "'re' module error"

class UnexpectedDialogOutput(error):
    """Exception raised when the :program:`dialog`-like program returns \
something not expected by pythondialog."""
    ExceptionShortDescription = "Unexpected dialog output"

class DialogTerminatedBySignal(error):
    """Exception raised when the :program:`dialog`-like program is \
terminated by a signal."""
    ExceptionShortDescription = "dialog-like terminated by a signal"

class DialogError(error):
    """Exception raised when the :program:`dialog`-like program exits \
with the code indicating an error."""
    ExceptionShortDescription = "dialog-like terminated due to an error"

class UnableToRetrieveBackendVersion(error):
    """Exception raised when we cannot retrieve the version string of the \
:program:`dialog`-like backend.

    .. versionadded:: 2.14
    """
    ExceptionShortDescription = "Unable to retrieve the version of the \
dialog-like backend"

class UnableToParseBackendVersion(error):
    """Exception raised when we cannot parse the version string of the \
:program:`dialog`-like backend.

    .. versionadded:: 2.14
    """
    ExceptionShortDescription = "Unable to parse as a dialog-like backend \
version string"

class UnableToParseDialogBackendVersion(UnableToParseBackendVersion):
    """Exception raised when we cannot parse the version string of the \
:program:`dialog` backend.

    .. versionadded:: 2.14
    """
    ExceptionShortDescription = "Unable to parse as a dialog version string"

class InadequateBackendVersion(error):
    """Exception raised when the backend version in use is inadequate \
in a given situation.

    .. versionadded:: 2.14
    """
    ExceptionShortDescription = "Inadequate backend version"


@contextmanager
def _OSErrorHandling():
    try:
        yield
    except OSError, e:
        raise PythonDialogOSError(unicode(e))
    except IOError, e:
        raise PythonDialogIOError(unicode(e))


try:
    # Values accepted for checklists
    _on_cre = re.compile(r"on$", re.IGNORECASE)
    _off_cre = re.compile(r"off$", re.IGNORECASE)

    _calendar_date_cre = re.compile(
        r"(?P<day>\d\d)/(?P<month>\d\d)/(?P<year>\d\d\d\d)$")
    _timebox_time_cre = re.compile(
        r"(?P<hour>\d\d):(?P<minute>\d\d):(?P<second>\d\d)$")
except re.error, e:
    raise PythonDialogReModuleError(unicode(e))


# From dialog(1):
#
#   All options begin with "--" (two ASCII hyphens, for the benefit of those
#   using systems with deranged locale support).
#
#   A "--" by itself is used as an escape, i.e., the next token on the
#   command-line is not treated as an option, as in:
#        dialog --title -- --Not an option
def _dash_escape(args):
    """Escape all elements of *args* that need escaping.

    *args* may be any sequence and is not modified by this function.
    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 ``'--'``.

    """
    res = []

    for arg in args:
        if arg.startswith("--"):
            res.extend(("--", arg))
        else:
            res.append(arg)

    return res

# We need this function in the global namespace for the lambda
# expressions in _common_args_syntax to see it when they are called.
def _dash_escape_nf(args):      # nf: non-first
    """Escape all elements of *args* that need escaping, except the first one.

    See :func:`_dash_escape` for details. Return a new list.

    """
    if not args:
        raise PythonDialogBug("not a non-empty sequence: {0!r}".format(args))
    l = _dash_escape(args[1:])
    l.insert(0, args[0])
    return l

def _simple_option(option, enable):
    """Turn on or off the simplest :term:`dialog common options`."""
    if enable:
        return (option,)
    else:
        # This will not add any argument to the command line
        return ()


# This dictionary allows us to write the dialog common options in a Pythonic
# way (e.g. dialog_instance.checklist(args, ..., title="Foo", no_shadow=True)).
#
# Options such as --separate-output should obviously not be set by the user
# since they affect the parsing of dialog's output:
_common_args_syntax = {
    "ascii_lines": lambda enable: _simple_option("--ascii-lines", enable),
    "aspect": lambda ratio: _dash_escape_nf(("--aspect", unicode(ratio))),
    "backtitle": lambda backtitle: _dash_escape_nf(("--backtitle", backtitle)),
    # Obsolete according to dialog(1)
    "beep": lambda enable: _simple_option("--beep", enable),
    # Obsolete according to dialog(1)
    "beep_after": lambda enable: _simple_option("--beep-after", enable),
    # Warning: order = y, x!
    "begin": lambda coords: _dash_escape_nf(
        ("--begin", unicode(coords[0]), unicode(coords[1]))),
    "cancel_label": lambda s: _dash_escape_nf(("--cancel-label", s)),
    # Old, unfortunate choice of key, kept for backward compatibility
    "cancel": lambda s: _dash_escape_nf(("--cancel-label", s)),
    "clear": lambda enable: _simple_option("--clear", enable),
    "colors": lambda enable: _simple_option("--colors", enable),
    "column_separator": lambda s: _dash_escape_nf(("--column-separator", s)),
    "cr_wrap": lambda enable: _simple_option("--cr-wrap", enable),
    "create_rc": lambda filename: _dash_escape_nf(("--create-rc", filename)),
    "date_format": lambda s: _dash_escape_nf(("--date-format", s)),
    "defaultno": lambda enable: _simple_option("--defaultno", enable),
    "default_button": lambda s: _dash_escape_nf(("--default-button", s)),
    "default_item": lambda s: _dash_escape_nf(("--default-item", s)),
    "exit_label": lambda s: _dash_escape_nf(("--exit-label", s)),
    "extra_button": lambda enable: _simple_option("--extra-button", enable),
    "extra_label": lambda s: _dash_escape_nf(("--extra-label", s)),
    "help": lambda enable: _simple_option("--help", enable),
    "help_button": lambda enable: _simple_option("--help-button", enable),
    "help_label": lambda s: _dash_escape_nf(("--help-label", s)),
    "help_status": lambda enable: _simple_option("--help-status", enable),
    "help_tags": lambda enable: _simple_option("--help-tags", enable),
    "hfile": lambda filename: _dash_escape_nf(("--hfile", filename)),
    "hline": lambda s: _dash_escape_nf(("--hline", s)),
    "ignore": lambda enable: _simple_option("--ignore", enable),
    "insecure": lambda enable: _simple_option("--insecure", enable),
    "item_help": lambda enable: _simple_option("--item-help", enable),
    "keep_tite": lambda enable: _simple_option("--keep-tite", enable),
    "keep_window": lambda enable: _simple_option("--keep-window", enable),
    "max_input": lambda size: _dash_escape_nf(("--max-input", unicode(size))),
    "no_cancel": lambda enable: _simple_option("--no-cancel", enable),
    "nocancel": lambda enable: _simple_option("--nocancel", enable),
    "no_collapse": lambda enable: _simple_option("--no-collapse", enable),
    "no_kill": lambda enable: _simple_option("--no-kill", enable),
    "no_label": lambda s: _dash_escape_nf(("--no-label", s)),
    "no_lines": lambda enable: _simple_option("--no-lines", enable),
    "no_mouse": lambda enable: _simple_option("--no-mouse", enable),
    "no_nl_expand": lambda enable: _simple_option("--no-nl-expand", enable),
    "no_ok": lambda enable: _simple_option("--no-ok", enable),
    "no_shadow": lambda enable: _simple_option("--no-shadow", enable),
    "no_tags": lambda enable: _simple_option("--no-tags", enable),
    "ok_label": lambda s: _dash_escape_nf(("--ok-label", s)),
    # cf. Dialog.maxsize()
    "print_maxsize": lambda enable: _simple_option("--print-maxsize",
                                                   enable),
    "print_size": lambda enable: _simple_option("--print-size", enable),
    # cf. Dialog.backend_version()
    "print_version": lambda enable: _simple_option("--print-version",
                                                   enable),
    "scrollbar": lambda enable: _simple_option("--scrollbar", enable),
    "separate_output": lambda enable: _simple_option("--separate-output",
                                                     enable),
    "separate_widget": lambda s: _dash_escape_nf(("--separate-widget", s)),
    "shadow": lambda enable: _simple_option("--shadow", enable),
    # Obsolete according to dialog(1)
    "size_err": lambda enable: _simple_option("--size-err", enable),
    "sleep": lambda secs: _dash_escape_nf(("--sleep", unicode(secs))),
    "stderr": lambda enable: _simple_option("--stderr", enable),
    "stdout": lambda enable: _simple_option("--stdout", enable),
    "tab_correct": lambda enable: _simple_option("--tab-correct", enable),
    "tab_len": lambda n: _dash_escape_nf(("--tab-len", unicode(n))),
    "time_format": lambda s: _dash_escape_nf(("--time-format", s)),
    "timeout": lambda secs: _dash_escape_nf(("--timeout", unicode(secs))),
    "title": lambda title: _dash_escape_nf(("--title", title)),
    "trace": lambda filename: _dash_escape_nf(("--trace", filename)),
    "trim": lambda enable: _simple_option("--trim", enable),
    "version": lambda enable: _simple_option("--version", enable),
    "visit_items": lambda enable: _simple_option("--visit-items", enable),
    "yes_label": lambda s: _dash_escape_nf(("--yes-label", s)) }


def _find_in_path(prog_name):
    """Search an executable in the :envvar:`PATH`.

    If :envvar:`PATH` is not defined, the default path
    ``:/bin:/usr/bin`` is used.

    Return a path to the file or ``None`` if no readable and executable
    file is found.

    Notable exception:

      :exc:`PythonDialogOSError`

    """
    with _OSErrorHandling():
        # Note that the leading empty component in the default value for PATH
        # could lead to the returned path not being absolute.
        PATH = os.getenv("PATH", ":/bin:/usr/bin") # see the execvp(3) man page
        for d in PATH.split(":"):
            file_path = os.path.join(d, prog_name)
            if os.path.isfile(file_path) \
               and os.access(file_path, os.R_OK | os.X_OK):
                return file_path
        return None


def _path_to_executable(f):
    """Find a path to an executable.

    Find a path to an executable, using the same rules as the POSIX
    exec*p functions (see execvp(3) for instance).

    If *f* contains a ``/``, it is assumed to be a path and is simply
    checked for read and write permissions; otherwise, it is looked for
    according to the contents of the :envvar:`PATH` environment
    variable, which defaults to ``:/bin:/usr/bin`` if unset.

    The returned path is not necessarily absolute.

    Notable exceptions:

      - :exc:`ExecutableNotFound`
      - :exc:`PythonDialogOSError`

    """
    with _OSErrorHandling():
        if '/' in f:
            if os.path.isfile(f) and \
                   os.access(f, os.R_OK | os.X_OK):
                res = f
            else:
                raise ExecutableNotFound("%s cannot be read and executed" % f)
        else:
            res = _find_in_path(f)
            if res is None:
                raise ExecutableNotFound(
                    "can't find the executable for the dialog-like "
                    "program")

    return res


def _to_onoff(val):
    """Convert boolean expressions to ``"on"`` or ``"off"``.

    :return:
      - ``"on"`` if *val* is ``True``, a non-zero integer, ``"on"`` or
        any case variation thereof;
      - ``"off"`` if *val* is ``False``, ``0``, ``"off"`` or any case
        variation thereof.

    Notable exceptions:

      - :exc:`PythonDialogReModuleError`
      - :exc:`BadPythonDialogUsage`

    """
    if isinstance(val, (bool, int)):
        return "on" if val else "off"
    elif isinstance(val, basestring):
        try:
            if _on_cre.match(val):
                return "on"
            elif _off_cre.match(val):
                return "off"
        except re.error, e:
            raise PythonDialogReModuleError(unicode(e))

    raise BadPythonDialogUsage("invalid boolean value: {0!r}".format(val))


def _compute_common_args(mapping):
    """Compute the list of arguments for :term:`dialog common options`.

    Compute a list of the command-line arguments to pass to
    :program:`dialog` from a keyword arguments dictionary for options
    listed as "common options" in the manual page for :program:`dialog`.
    These are the options that are not tied to a particular widget.

    This allows one to specify these options in a pythonic way, such
    as::

       d.checklist(<usual arguments for a checklist>,
                   title="...",
                   backtitle="...")

    instead of having to pass them with strings like ``"--title foo"``
    or ``"--backtitle bar"``.

    Notable exceptions: none

    """
    args = []
    for option, value in mapping.items():
        args.extend(_common_args_syntax[option](value))
    return args


# Classes for dealing with the version of dialog-like backend programs
if sys.hexversion >= 0x030200F0:
    import abc
    # Abstract base class
    class BackendVersion():
        __metaclass__ = abc.ABCMeta
        @abc.abstractmethod
        def __unicode__(self):
            raise NotImplementedError()

        if sys.hexversion >= 0x030300F0:
            @classmethod
            @abc.abstractmethod
            def fromstring(cls, s):
                raise NotImplementedError()
        else:                   # for Python 3.2
            @abc.abstractclassmethod
            def fromstring(cls, s):
                raise NotImplementedError()

        @abc.abstractmethod
        def __lt__(self, other):
            raise NotImplementedError()

        @abc.abstractmethod
        def __le__(self, other):
            raise NotImplementedError()

        @abc.abstractmethod
        def __eq__(self, other):
            raise NotImplementedError()

        @abc.abstractmethod
        def __ne__(self, other):
            raise NotImplementedError()

        @abc.abstractmethod
        def __gt__(self, other):
            raise NotImplementedError()

        @abc.abstractmethod
        def __ge__(self, other):
            raise NotImplementedError()
else:
    class BackendVersion(object):
        pass


class DialogBackendVersion(BackendVersion):
    """Class representing possible versions of the :program:`dialog` backend.

    The purpose of this class is to make it easy to reliably compare
    between versions of the :program:`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
    :dfn:`dotted part` and the :dfn:`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 :meth:`fromstring` class method. This
    is particularly useful with the result of
    :samp:`{d}.backend_version()`, where *d* is a :class:`Dialog`
    instance. Actually, the main constructor detects if its first
    argument is a string and calls :meth:`!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 :class:`DialogBackendVersion` instance,
    :samp:`unicode({bv})` is an Unicode string representing the same
    version (for instance, ``"1.2-20130902"``).

    Two :class:`DialogBackendVersion` instances can be compared with the
    usual comparison operators (``<``, ``<=``, ``==``, ``!=``, ``>=``,
    ``>``). The algorithm is designed so that the following order is
    respected (after instanciation with :meth:`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.

    """
    try:
        _backend_version_cre = re.compile(r"""(?P<dotted> (\d+) (\.\d+)* )
                                              (?P<rest>.*)$""", re.VERBOSE)
    except re.error, e:
        raise PythonDialogReModuleError(unicode(e))

    def __init__(self, dotted_part_or_str, rest=""):
        """Create a :class:`DialogBackendVersion` instance.

        Please see the class docstring for details.

        """
        if isinstance(dotted_part_or_str, basestring):
            if rest:
                raise BadPythonDialogUsage(
                    "non-empty 'rest' with 'dotted_part_or_str' as string: "
                    "{0!r}".format(rest))
            else:
                tmp = self.__class__.fromstring(dotted_part_or_str)
                dotted_part_or_str, rest = tmp.dotted_part, tmp.rest

        for elt in dotted_part_or_str:
            if not isinstance(elt, int):
                raise BadPythonDialogUsage(
                    "when 'dotted_part_or_str' is not a string, it must "
                    "be a sequence (or iterable) of integers; however, "
                    "{0!r} is not an integer.".format(elt))

        self.dotted_part = list(dotted_part_or_str)
        self.rest = rest

    def __repr__(self):
        # Unicode strings are not supported as the result of __repr__()
        # in Python 2.x (cf. <http://bugs.python.org/issue5876>).
        return b"{0}.{1}({2!r}, rest={3!r})".format(
            __name__, self.__class__.__name__, self.dotted_part, self.rest)

    def __unicode__(self):
        return '.'.join(imap(unicode, self.dotted_part)) + self.rest

    @classmethod
    def fromstring(cls, s):
        """Create a :class:`DialogBackendVersion` instance from a \
:program:`dialog` version string.

        :param str s: a :program:`dialog` version string
        :return:
          a :class:`DialogBackendVersion` instance representing the same
          string

        Notable exceptions:

          - :exc:`UnableToParseDialogBackendVersion`
          - :exc:`PythonDialogReModuleError`

          """
        try:
            mo = cls._backend_version_cre.match(s)
            if not mo:
                raise UnableToParseDialogBackendVersion(s)
            dotted_part = [ int(x) for x in mo.group("dotted").split(".") ]
            rest = mo.group("rest")
        except re.error, e:
            raise PythonDialogReModuleError(unicode(e))

        return cls(dotted_part, rest)

    def __lt__(self, other):
        return (self.dotted_part, self.rest) < (other.dotted_part, other.rest)

    def __le__(self, other):
        return (self.dotted_part, self.rest) <= (other.dotted_part, other.rest)

    def __eq__(self, other):
        return (self.dotted_part, self.rest) == (other.dotted_part, other.rest)

    # Python 3.2 has a decorator (functools.total_ordering) to automate this.
    def __ne__(self, other):
        return not (self == other)

    def __gt__(self, other):
        return not (self <= other)

    def __ge__(self, other):
        return not (self < other)


def widget(func):
    """Decorator to mark :class:`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 :class:`Dialog`, except that after every widget-producing call,
    it spawns a "confirm quit" dialog if the widget returned
    :attr:`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
    :meth:`Dialog.gauge_start`, :meth:`Dialog.gauge_update` and
    :meth:`Dialog.gauge_stop`, only the last one has the decorator
    because it returns a :term:`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.

    .. versionadded:: 2.14

    """
    func.is_widget = True
    return func


def retval_is_code(func):
    """Decorator for :class:`Dialog` widget-producing methods whose \
return value is the :term:`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.

    .. versionadded:: 3.0

    """
    func.retval_is_code = True
    return func


def _obsolete_property(name, replacement=None):
    if replacement is None:
        replacement = name

    def getter(self):
        warnings.warn("the DIALOG_{name} attribute of Dialog instances is "
                      "obsolete; use the Dialog.{repl} class attribute "
                      "instead.".format(name=name, repl=replacement),
                      DeprecationWarning)
        return getattr(self, replacement)

    return getter


# Main class of the module
class Dialog(object):
    """Class providing bindings for :program:`dialog`-compatible programs.

    This class allows you to invoke :program:`dialog` or a compatible
    program in a pythonic way to quickly and easily build simple but
    nice text interfaces.

    An application typically creates one instance of the :class:`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.

    """
    try:
        _print_maxsize_cre = re.compile(r"""^MaxSize:[ \t]+
                                            (?P<rows>\d+),[ \t]*
                                            (?P<columns>\d+)[ \t]*$""",
                                        re.VERBOSE)
        _print_version_cre = re.compile(
            r"^Version:[ \t]+(?P<version>.+?)[ \t]*$", re.MULTILINE)
    except re.error, e:
        raise PythonDialogReModuleError(unicode(e))

    # DIALOG_OK, DIALOG_CANCEL, etc. are environment variables controlling
    # the dialog backend exit status in the corresponding situation ("low-level
    # exit status/code").
    #
    # Note:
    #    - 127 must not be used for any of the DIALOG_* values. It is used
    #      when a failure occurs in the child process before it exec()s
    #      dialog (where "before" includes a potential exec() failure).
    #    - 126 is also used (although in presumably rare situations).
    _DIALOG_OK        = 0
    _DIALOG_CANCEL    = 1
    _DIALOG_ESC       = 2
    _DIALOG_ERROR     = 3
    _DIALOG_EXTRA     = 4
    _DIALOG_HELP      = 5
    _DIALOG_ITEM_HELP = 6
    # cf. also _lowlevel_exit_codes and _dialog_exit_code_ll_to_hl which are
    # created by __init__(). It is not practical to define everything here,
    # because there is no equivalent of 'self' for the class outside method
    # definitions.
    _lowlevel_exit_code_varnames = frozenset(("OK", "CANCEL", "ESC", "ERROR",
                                              "EXTRA", "HELP", "ITEM_HELP"))

    # High-level exit codes, AKA "Dialog exit codes". These are the codes that
    # pythondialog-based applications should use.
    #
    #: :term:`Dialog exit code` corresponding to the ``DIALOG_OK``
    #: :term:`dialog exit status`
    OK     = "ok"
    #: :term:`Dialog exit code` corresponding to the ``DIALOG_CANCEL``
    #: :term:`dialog exit status`
    CANCEL = "cancel"
    #: :term:`Dialog exit code` corresponding to the ``DIALOG_ESC``
    #: :term:`dialog exit status`
    ESC    = "esc"
    #: :term:`Dialog exit code` corresponding to the ``DIALOG_EXTRA``
    #: :term:`dialog exit status`
    EXTRA  = "extra"
    #: :term:`Dialog exit code` corresponding to the ``DIALOG_HELP`` and
    #: ``DIALOG_ITEM_HELP`` :term:`dialog exit statuses <dialog exit status>`
    HELP   = "help"

    # Define properties to maintain backward-compatibility while warning about
    # the obsolete attributes (which used to refer to the low-level exit codes
    # in pythondialog 2.x).
    #
    #: Obsolete property superseded by :attr:`Dialog.OK` since version 3.0
    DIALOG_OK        = property(_obsolete_property("OK"),
                         doc="Obsolete property superseded by Dialog.OK")
    #: Obsolete property superseded by :attr:`Dialog.CANCEL` since version 3.0
    DIALOG_CANCEL    = property(_obsolete_property("CANCEL"),
                         doc="Obsolete property superseded by Dialog.CANCEL")
    #: Obsolete property superseded by :attr:`Dialog.ESC` since version 3.0
    DIALOG_ESC       = property(_obsolete_property("ESC"),
                         doc="Obsolete property superseded by Dialog.ESC")
    #: Obsolete property superseded by :attr:`Dialog.EXTRA` since version 3.0
    DIALOG_EXTRA     = property(_obsolete_property("EXTRA"),
                         doc="Obsolete property superseded by Dialog.EXTRA")
    #: Obsolete property superseded by :attr:`Dialog.HELP` since version 3.0
    DIALOG_HELP      = property(_obsolete_property("HELP"),
                         doc="Obsolete property superseded by Dialog.HELP")
    # We treat DIALOG_ITEM_HELP and DIALOG_HELP the same way in pythondialog,
    # since both indicate the same user action ("Help" button pressed).
    #
    #: Obsolete property superseded by :attr:`Dialog.HELP` since version 3.0
    DIALOG_ITEM_HELP = property(_obsolete_property("ITEM_HELP",
                                                   replacement="HELP"),
                         doc="Obsolete property superseded by Dialog.HELP")

    @property
    def DIALOG_ERROR(self):
        warnings.warn("the DIALOG_ERROR attribute of Dialog instances is "
                      "obsolete. Since the corresponding exit status is "
                      "automatically translated into a DialogError exception, "
                      "users should not see nor need this attribute. If you "
                      "think you have a good reason to use it, please expose "
                      "your situation on the pythondialog mailing-list.",
                      DeprecationWarning)
        # There is no corresponding high-level code; and if the user *really*
        # wants to know the (integer) error exit status, here it is...
        return self._DIALOG_ERROR

    def __init__(self, dialog="dialog", DIALOGRC=None,
                 compat="dialog", use_stdout=None, **kwargs):
        """Constructor for :class:`Dialog` instances.

        :param str dialog:
          name of (or path to) the :program:`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 :envvar:`PATH` environment variable, which
          defaults to ``":/bin:/usr/bin"`` if unset.
        :param str DIALOGRC:
          string to pass to the :program:`dialog`-like program as the
          :envvar:`DIALOGRC` environment variable, or ``None`` if no
          modification to the environment regarding this variable should
          be done in the call to the :program:`dialog`-like program
        :param str compat:
          compatibility mode (see :ref:`below
          <Dialog-constructor-compat-arg>`)
        :param bool use_stdout:
          read :program:`dialog`'s standard output stream instead of its
          standard error stream in order to get most "results"
          (user-supplied strings, selected items, etc.; basically,
          everything except the exit status). This is for compatibility
          with :program:`Xdialog` and should only be used if you have a
          good reason to do so.
        :param bool autowidgetsize:
          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
          :program:`dialog` backend will automatically compute a
          suitable size for the widgets. More details about this option
          are given :ref:`below <autowidgetsize>`.
        :param pass_args_via_file:
          whether to use the :option:`--file` option with a temporary
          file in order to pass arguments to the :program:`dialog`
          backend, instead of including them directly into the argument
          list; using :option:`--file` has the advantage of not exposing
          the “real” arguments to other users through the process table.
          With the default value (``None``), the option is enabled if
          the :program:`dialog` version is recent enough to offer a
          reliable :option:`--file` implementation (i.e., 1.2-20150513
          or later).
        :type pass_args_via_file: bool or ``None``
        :return: a :class:`Dialog` instance

        .. _Dialog-constructor-compat-arg:

        The officially supported :program:`dialog`-like program in
        pythondialog is the well-known dialog_ program written in C,
        based on the ncurses_ library.

        .. _dialog: http://invisible-island.net/dialog/dialog.html
        .. _ncurses: http://invisible-island.net/ncurses/ncurses.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 :program:`dialog`; this is the
        default) or ``"Xdialog"`` (for, well, :program:`Xdialog`).

        .. _Xdialog: http://xdialog.free.fr/

        The *compat* argument allows me to cope with minor differences
        in behaviour between the various programs implementing the
        :program:`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 :program:`dialog`. This is for the
        benefit of pretty much everyone that relies on the
        :program:`dialog` interface.

        Notable exceptions:

          - :exc:`ExecutableNotFound`
          - :exc:`PythonDialogOSError`
          - :exc:`UnableToRetrieveBackendVersion`
          - :exc:`UnableToParseBackendVersion`

        .. versionadded:: 3.1
           Support for the *autowidgetsize* parameter.

        .. versionadded:: 3.3
           Support for the *pass_args_via_file* parameter.

        """
        if 'autowidgetsize' in kwargs: autowidgetsize = kwargs['autowidgetsize']; del kwargs['autowidgetsize']
        else: autowidgetsize = False
        if 'pass_args_via_file' in kwargs: pass_args_via_file = kwargs['pass_args_via_file']; del kwargs['pass_args_via_file']
        else: pass_args_via_file = None

        # DIALOGRC differs from the Dialog._DIALOG_* attributes in that:
        #   1. It is an instance attribute instead of a class attribute.
        #   2. It should be a string if not None.
        #   3. We may very well want it to be unset.
        if DIALOGRC is not None:
            self.DIALOGRC = DIALOGRC

        # Mapping from "OK", "CANCEL", ... to the corresponding dialog exit
        # statuses (integers).
        self._lowlevel_exit_codes = dict((
            name, getattr(self, "_DIALOG_" + name))
            for name in self._lowlevel_exit_code_varnames)

        # Mapping from dialog exit status (integer) to Dialog exit code ("ok",
        # "cancel", ... strings referred to by Dialog.OK, Dialog.CANCEL, ...);
        # in other words, from low-level to high-level exit code.
        self._dialog_exit_code_ll_to_hl = {}
        for name in self._lowlevel_exit_code_varnames:
            intcode = self._lowlevel_exit_codes[name]

            if name == "ITEM_HELP":
                self._dialog_exit_code_ll_to_hl[intcode] = self.HELP
            elif name == "ERROR":
                continue
            else:
                self._dialog_exit_code_ll_to_hl[intcode] = getattr(self, name)

        self._dialog_prg = _path_to_executable(dialog)
        self.compat = compat
        self.autowidgetsize = autowidgetsize
        self.dialog_persistent_arglist = []

        # Use stderr or stdout for reading dialog's output?
        if self.compat == "Xdialog":
            # Default to using stdout for Xdialog
            self.use_stdout = True
        else:
            self.use_stdout = False
        if use_stdout is not None:
            # Allow explicit setting
            self.use_stdout = use_stdout
        if self.use_stdout:
            self.add_persistent_args(["--stdout"])

        self.setup_debug(False)

        if compat == "dialog":
            # Temporary setting to ensure that self.backend_version()
            # will be able to run even if dialog is too old to support
            # --file correctly. Will be overwritten later.
            self.pass_args_via_file = False
            self.cached_backend_version = DialogBackendVersion.fromstring(
                self.backend_version())
        else:
            # Xdialog doesn't seem to offer --print-version (2013-09-12)
            self.cached_backend_version = None

        if pass_args_via_file is not None:
            # Always respect explicit settings
            self.pass_args_via_file = pass_args_via_file
        elif self.cached_backend_version is not None:
            self.pass_args_via_file = self.cached_backend_version >= \
                                      DialogBackendVersion("1.2-20150513")
        else:
            # Xdialog doesn't seem to offer --file (2015-05-24)
            self.pass_args_via_file = False

    @classmethod
    def dash_escape(cls, args):
        """
        Escape all elements of *args* that need escaping for :program:`dialog`.

        *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 :class:`Dialog` methods automatically perform
        :term:`dash escaping` where appropriate. In particular, this is
        the case for every method that provides a widget: :meth:`yesno`,
        :meth:`msgbox`, etc. You only need to do it yourself when
        calling a low-level method such as :meth:`add_persistent_args`.

        .. versionadded:: 2.12

        """
        return _dash_escape(args)

    @classmethod
    def dash_escape_nf(cls, args):
        """
        Escape all elements of *args* that need escaping, except the first one.

        See :meth:`dash_escape` for details. Return a new list.

        All high-level :class:`Dialog` methods automatically perform dash
        escaping where appropriate. In particular, this is the case
        for every method that provides a widget: :meth:`yesno`, :meth:`msgbox`,
        etc. You only need to do it yourself when calling a low-level
        method such as :meth:`add_persistent_args`.

        .. versionadded:: 2.12

        """
        return _dash_escape_nf(args)

    def 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 :term:`dash escaping`; you have to do it yourself.
        :meth:`dash_escape` and :meth:`dash_escape_nf` may be useful for
        this purpose.

        """
        self.dialog_persistent_arglist.extend(args)

    def set_background_title(self, text):
        """Set the background title for dialog.

        :param str text: string to use as background title

        .. versionadded:: 2.13

        """
        self.add_persistent_args(self.dash_escape_nf(("--backtitle", text)))

    # For compatibility with the old dialog
    def setBackgroundTitle(self, text):
        """Set the background title for :program:`dialog`.

        :param str text: background title to use behind widgets

        .. deprecated:: 2.03
          Use :meth:`set_background_title` instead.

        """
        warnings.warn("Dialog.setBackgroundTitle() has been obsolete for "
                      "many years; use Dialog.set_background_title() instead",
                      DeprecationWarning)
        self.set_background_title(text)

    def setup_debug(self, enable, file=None, always_flush=False, **kwargs):
        """Setup the debugging parameters.

        :param bool enable:       whether to enable or disable debugging
        :param file file:         where to write debugging information
        :param bool always_flush: whether to call :meth:`file.flush`
                                  after each command written
        :param bool expand_file_opt:
          when :meth:`Dialog.__init__` has been called with
          :samp:`{pass_args_via_file}=True`, this option causes the
          :option:`--file` options that would normally be written to
          *file* to be expanded, yielding a similar result to what would
          be obtained with :samp:`{pass_args_via_file}=False` (but
          contrary to :samp:`{pass_args_via_file}=False`, this only
          affects *file*, not the actual :program:`dialog` calls). This
          is useful, for instance, for copying some of the
          :program:`dialog` commands into a shell.

        When *enable* is true, all :program:`dialog` commands are
        written to *file* using POSIX shell syntax. In this case, you'll
        probably want to use either :samp:`{expand_file_opt}=True` in
        this method or :samp:`{pass_args_via_file}=False` in
        :meth:`Dialog.__init__`, otherwise you'll mostly see
        :program:`dialog` calls containing only one :option:`--file`
        option followed by a path to a temporary file.

        .. versionadded:: 2.12

        .. versionadded:: 3.3
           Support for the *expand_file_opt* parameter.

        """
        if 'expand_file_opt' in kwargs: expand_file_opt = kwargs['expand_file_opt']; del kwargs['expand_file_opt']
        else: expand_file_opt = False

        self._debug_enabled = enable

        if not hasattr(self, "_debug_logfile"):
            self._debug_logfile = None
        # Allows to switch debugging on and off without having to pass the file
        # object again and again.
        if file is not None:
            self._debug_logfile = file

        if enable and self._debug_logfile is None:
            raise BadPythonDialogUsage(
                "you must specify a file object when turning debugging on")

        self._debug_always_flush = always_flush
        self._expand_file_opt = expand_file_opt
        self._debug_first_output = True

    def _write_command_to_file(self, env, arglist):
        envvar_settings_list = []

        if "DIALOGRC" in env:
            envvar_settings_list.append(
                "DIALOGRC={0}".format(_shell_quote(env["DIALOGRC"])))

        for var in self._lowlevel_exit_code_varnames:
            varname = "DIALOG_" + var
            envvar_settings_list.append(
                "{0}={1}".format(varname, _shell_quote(env[varname])))

        command_str = ' '.join(envvar_settings_list +
                               list(imap(_shell_quote, arglist)))
        s = "{separator}{cmd}\n\nArgs: {args!r}\n".format(
            separator="" if self._debug_first_output else ("-" * 79) + "\n",
            cmd=command_str, args=arglist)

        self._debug_logfile.write(s)
        if self._debug_always_flush:
            self._debug_logfile.flush()

        self._debug_first_output = False

    def _quote_arg_for_file_opt(self, argument):
        """
        Transform a :program:`dialog` argument for safe inclusion via :option:`--file`.

        Since arguments in a file included via :option:`--file` are
        separated by whitespace, they must be quoted for
        :program:`dialog` in a way similar to shell quoting.

        """
        l = ['"']

        for c in argument:
            if c in ('"', '\\'):
                l.append("\\" + c)
            else:
                l.append(c)

        return ''.join(l + ['"'])

    def _call_program(self, cmdargs, **kwargs):
        """Do the actual work of invoking the :program:`dialog`-like program.

        Communication with the :program:`dialog`-like program is
        performed through one :manpage:`pipe(2)` and optionally a
        user-specified file descriptor, depending on
        *redir_child_stdin_from_fd*. The pipe allows the parent process
        to read what :program:`dialog` writes on its standard error
        stream [#]_.

        If *use_persistent_args* is ``True`` (the default), the elements
        of ``self.dialog_persistent_arglist`` are passed as the first
        arguments to ``self._dialog_prg``; otherwise,
        ``self.dialog_persistent_arglist`` is not used at all. The
        remaining arguments are those computed from *kwargs* followed by
        the elements of *cmdargs*.

        If *dash_escape* is the string ``"non-first"``, then every
        element of *cmdargs* that starts with ``'--'`` is escaped by
        prepending an element consisting of ``'--'``, except the first
        one (which is usually a :program:`dialog` option such as
        ``'--yesno'``). In order to disable this escaping mechanism,
        pass the string ``"none"`` as *dash_escape*.

        If *redir_child_stdin_from_fd* is not ``None``, it should be an
        open file descriptor (i.e., an integer). That file descriptor
        will be connected to :program:`dialog`'s standard input. This is
        used by the gauge widget to feed data to :program:`dialog`, as
        well as for :meth:`progressbox` in order to allow
        :program:`dialog` to read data from a possibly-growing file.

        If *redir_child_stdin_from_fd* is ``None``, the standard input
        in the child process (which runs :program:`dialog`) is not
        redirected in any way.

        If *close_fds* is passed, it should be a sequence of file
        descriptors that will be closed by the child process before it
        exec()s the :program:`dialog`-like program.

        Notable exception:

          :exc:`PythonDialogOSError` (if any of the pipe(2) or close(2)
          system calls fails...)

        .. [#] standard ouput stream if *use_stdout* is ``True``

        """
        if 'close_fds' in kwargs: close_fds = kwargs['close_fds']; del kwargs['close_fds']
        else: close_fds = ()
        if 'redir_child_stdin_from_fd' in kwargs: redir_child_stdin_from_fd = kwargs['redir_child_stdin_from_fd']; del kwargs['redir_child_stdin_from_fd']
        else: redir_child_stdin_from_fd = None
        if 'use_persistent_args' in kwargs: use_persistent_args = kwargs['use_persistent_args']; del kwargs['use_persistent_args']
        else: use_persistent_args = True
        if 'dash_escape' in kwargs: dash_escape = kwargs['dash_escape']; del kwargs['dash_escape']
        else: dash_escape = "non-first"

        # We want to define DIALOG_OK, DIALOG_CANCEL, etc. in the
        # environment of the child process so that we know (and
        # even control) the possible dialog exit statuses.
        new_environ = {}
        new_environ.update(os.environ)
        for var, value in self._lowlevel_exit_codes.items():
            varname = "DIALOG_" + var
            new_environ[varname] = unicode(value)
        if hasattr(self, "DIALOGRC"):
            new_environ["DIALOGRC"] = self.DIALOGRC

        if dash_escape == "non-first":
            # Escape all elements of 'cmdargs' that start with '--', except the
            # first one.
            cmdargs = self.dash_escape_nf(cmdargs)
        elif dash_escape != "none":
            raise PythonDialogBug("invalid value for 'dash_escape' parameter: "
                                  "{0!r}".format(dash_escape))

        arglist = [ self._dialog_prg ]

        if use_persistent_args:
            arglist.extend(self.dialog_persistent_arglist)

        arglist.extend(_compute_common_args(kwargs) + cmdargs)
        orig_args = arglist[:] # New object, copy of 'arglist'

        if self.pass_args_via_file:
            # There is currently no 'encoding' parameter in
            # tempfile.NamedTemporaryFile(), and the encoding for text files
            # defaults to ASCII in Python 2 → let's use binary mode.
            tmpfile = tempfile.NamedTemporaryFile(
                mode="wb", prefix="pythondialog.tmp", delete=False)
            filecontents = ' '.join( ( self._quote_arg_for_file_opt(arg)
                                       for arg in arglist[1:] ) )
            with tmpfile as f:
                f.write(filecontents.encode(
                    locale.getpreferredencoding(False)))
            args_file = tmpfile.name
            arglist[1:] = ["--file", args_file]
        else:
            args_file = None

        if self._debug_enabled:
            # Write the complete command line with environment variables
            # setting to the debug log file (POSIX shell syntax for easy
            # copy-pasting into a terminal, followed by repr(arglist)).
            self._write_command_to_file(
                new_environ, orig_args if self._expand_file_opt else arglist)

        # Create a pipe so that the parent process can read dialog's
        # output on stderr (stdout with 'use_stdout')
        with _OSErrorHandling():
            # rfd = File Descriptor for Reading
            # wfd = File Descriptor for Writing
            (child_output_rfd, child_output_wfd) = os.pipe()

        child_pid = os.fork()
        if child_pid == 0:
            # We are in the child process. We MUST NOT raise any exception.
            try:
                # 1) If the write end of a pipe isn't closed, the read end
                #    will never see EOF, which can indefinitely block the
                #    child waiting for input. To avoid this, the write end
                #    must be closed in the father *and* child processes.
                # 2) The child process doesn't need child_output_rfd.
                for fd in close_fds + (child_output_rfd,):
                    os.close(fd)
                # We want:
                #   - to keep a reference to the father's stderr for error
                #     reporting (and use line-buffering for this stream);
                #   - dialog's output on stderr[*] to go to child_output_wfd;
                #   - data written to fd 'redir_child_stdin_from_fd'
                #     (if not None) to go to dialog's stdin.
                #
                #       [*] stdout with 'use_stdout'
                #
                # We'll just print the result of traceback.format_exc() to
                # father_stderr, which is a byte string in Python 2, hence the
                # binary mode.
                father_stderr = open(os.dup(2), mode="wb")
                os.dup2(child_output_wfd, 1 if self.use_stdout else 2)
                if redir_child_stdin_from_fd is not None:
                    os.dup2(redir_child_stdin_from_fd, 0)

                os.execve(self._dialog_prg, arglist, new_environ)
            except:
                print(traceback.format_exc(), file=father_stderr)
                father_stderr.close()
                os._exit(127)

            # Should not happen unless there is a bug in Python
            os._exit(126)

        # We are in the father process.
        #
        # It is essential to close child_output_wfd, otherwise we will never
        # see EOF while reading on child_output_rfd and the parent process
        # will block forever on the read() call.
        # [ after the fork(), the "reference count" of child_output_wfd from
        #   the operating system's point of view is 2; after the child exits,
        #   it is 1 until the father closes it itself; then it is 0 and a read
        #   on child_output_rfd encounters EOF once all the remaining data in
        #   the pipe has been read. ]
        with _OSErrorHandling():
            os.close(child_output_wfd)
        return (child_pid, child_output_rfd, args_file)

    def _wait_for_program_termination(self, child_pid, child_output_rfd):
        """Wait for a :program:`dialog`-like process to terminate.

        This function waits for the specified process to terminate,
        raises the appropriate exceptions in case of abnormal
        termination and returns the :term:`Dialog exit code` and stderr
        [#stream]_ output of the process as a tuple: :samp:`({hl_exit_code},
        {output_string})`.

        *child_output_rfd* must be the file descriptor for the
        reading end of the pipe created by :meth:`_call_program`, the
        writing end of which was connected by :meth:`_call_program`
        to the child process's standard error [#stream]_.

        This function reads the process output on the standard error
        [#stream]_ from *child_output_rfd* and closes this file
        descriptor once this is done.

        Notable exceptions:

          - :exc:`DialogTerminatedBySignal`
          - :exc:`DialogError`
          - :exc:`PythonDialogErrorBeforeExecInChildProcess`
          - :exc:`PythonDialogIOError`    if the Python version is < 3.3
          - :exc:`PythonDialogOSError`
          - :exc:`PythonDialogBug`
          - :exc:`ProbablyPythonBug`

        .. [#stream] standard output if ``self.use_stdout`` is ``True``

        """
        # Read dialog's output on its stderr (stdout with 'use_stdout')
        with _OSErrorHandling():
            with open(child_output_rfd, "r") as f:
                child_output = f.read()
            # The closing of the file object causes the end of the pipe we used
            # to read dialog's output on its stderr to be closed too. This is
            # important, otherwise invoking dialog enough times would
            # eventually exhaust the maximum number of open file descriptors.

        exit_info = os.waitpid(child_pid, 0)[1]
        if os.WIFEXITED(exit_info):
            ll_exit_code = os.WEXITSTATUS(exit_info)
        # As we wait()ed for the child process to terminate, there is no
        # need to call os.WIFSTOPPED()
        elif os.WIFSIGNALED(exit_info):
            raise DialogTerminatedBySignal("the dialog-like program was "
                                           "terminated by signal %d" %
                                           os.WTERMSIG(exit_info))
        else:
            raise PythonDialogBug("please report this bug to the "
                                  "pythondialog maintainer(s)")

        if ll_exit_code == self._DIALOG_ERROR:
            raise DialogError(
                "the dialog-like program exited with status {0} (which was "
                "passed to it as the DIALOG_ERROR environment variable). "
                "Sometimes, the reason is simply that dialog was given a "
                "height or width parameter that is too big for the terminal "
                "in use. Its output, with leading and trailing whitespace "
                "stripped, was:\n\n{1}".format(ll_exit_code,
                                               child_output.strip()))
        elif ll_exit_code == 127:
            raise PythonDialogErrorBeforeExecInChildProcess(dedent("""\
            possible reasons include:
              - the dialog-like program could not be executed (this can happen
                for instance if the Python program is trying to call the
                dialog-like program with arguments that cannot be represented
                in the user's locale [LC_CTYPE]);
              - the system is out of memory;
              - the maximum number of open file descriptors has been reached;
              - a cosmic ray hit the system memory and flipped nasty bits.
            There ought to be a traceback above this message that describes
            more precisely what happened."""))
        elif ll_exit_code == 126:
            raise ProbablyPythonBug(
                "a child process returned with exit status 126; this might "
                "be the exit status of the dialog-like program, for some "
                "unknown reason (-> probably a bug in the dialog-like "
                "program); otherwise, we have probably found a python bug")

        try:
            hl_exit_code = self._dialog_exit_code_ll_to_hl[ll_exit_code]
        except KeyError:
            raise PythonDialogBug(
                "unexpected low-level exit status (new code?): {0!r}".format(
                    ll_exit_code))

        return (hl_exit_code, child_output)

    def _handle_program_exit(self, child_pid, child_output_rfd, args_file):
        """Handle exit of a :program:`dialog`-like process.

        This method:

          - waits for the :program:`dialog`-like program termination;
          - removes the temporary file used to pass its argument list,
            if any;
          - and returns the appropriate :term:`Dialog exit code` along
            with whatever output it produced.

        Notable exceptions:

          any exception raised by :meth:`_wait_for_program_termination`

        """
        try:
            exit_code, output = \
                    self._wait_for_program_termination(child_pid,
                                                       child_output_rfd)
        finally:
            with _OSErrorHandling():
                if args_file is not None and os.path.exists(args_file):
                    os.unlink(args_file)

        return (exit_code, output)

    def _perform(self, cmdargs, **kwargs):
        """Perform a complete :program:`dialog`-like program invocation.

        This method:

          - invokes the :program:`dialog`-like program;
          - waits for its termination;
          - removes the temporary file used to pass its argument list,
            if any;
          - and returns the appropriate :term:`Dialog exit code` along
            with whatever output it produced.

        See :meth:`_call_program` for a description of the parameters.

        Notable exceptions:

          any exception raised by :meth:`_call_program` or
          :meth:`_handle_program_exit`

        """
        if 'use_persistent_args' in kwargs: use_persistent_args = kwargs['use_persistent_args']; del kwargs['use_persistent_args']
        else: use_persistent_args = True
        if 'dash_escape' in kwargs: dash_escape = kwargs['dash_escape']; del kwargs['dash_escape']
        else: dash_escape = "non-first"

        child_pid, child_output_rfd, args_file = \
                    self._call_program(cmdargs, dash_escape=dash_escape,
                                       use_persistent_args=use_persistent_args,
                                       **kwargs)
        exit_code, output = self._handle_program_exit(child_pid,
                                                      child_output_rfd,
                                                      args_file)

        return (exit_code, output)

    def _strip_xdialog_newline(self, output):
        """Remove trailing newline (if any) in \
:program:`Xdialog`-compatibility mode"""
        if self.compat == "Xdialog" and output.endswith("\n"):
            output = output[:-1]
        return output

    # This is for compatibility with the old dialog.py
    def _perform_no_options(self, cmd):
        """Call :program:`dialog` without passing any more options."""

        warnings.warn("Dialog._perform_no_options() has been obsolete for "
                      "many years", DeprecationWarning)
        return os.system(self._dialog_prg + ' ' + cmd)

    # For compatibility with the old dialog.py
    def clear(self):
        """Clear the screen.

        Equivalent to the :option:`--clear` option of :program:`dialog`.

        .. deprecated:: 2.03
          You may use the :manpage:`clear(1)` program instead.
          cf. ``clear_screen()`` in :file:`examples/demo.py` for an
          example.

        """
        warnings.warn("Dialog.clear() has been obsolete for many years.\n"
                      "You may use the clear(1) program to clear the screen.\n"
                      "cf. clear_screen() in examples/demo.py for an example",
                      DeprecationWarning)
        self._perform_no_options('--clear')

    def _help_status_on(self, kwargs):
        return ("--help-status" in self.dialog_persistent_arglist
                or kwargs.get("help_status", False))

    def _parse_quoted_string(self, s, start=0):
        """Parse a quoted string from a :program:`dialog` help output."""
        if start >= len(s) or s[start] != '"':
            raise PythonDialogBug("quoted string does not start with a double "
                                  "quote: {0!r}".format(s))

        l = []
        i = start + 1

        while i < len(s) and s[i] != '"':
            if s[i] == "\\":
                i += 1
                if i >= len(s):
                    raise PythonDialogBug(
                        "quoted string ends with a backslash: {0!r}".format(s))
            l.append(s[i])
            i += 1

        if s[i] != '"':
            raise PythonDialogBug("quoted string does not and with a double "
                                  "quote: {0!r}".format(s))

        return (''.join(l), i+1)

    def _split_shellstyle_arglist(self, s):
        """Split an argument list with shell-style quoting performed \
by :program:`dialog`.

        Any argument in 's' may or may not be quoted. Quoted
        arguments are always expected to be enclosed in double quotes
        (more restrictive than what the POSIX shell allows).

        This function could maybe be replaced with shlex.split(),
        however:
          - shlex only handles Unicode strings in Python 2.7.3 and
            above;
          - the bulk of the work is done by _parse_quoted_string(),
            which is probably still needed in _parse_help(), where
            one needs to parse things such as 'HELP <id> <status>' in
            which <id> may be quoted but <status> is never quoted,
            even if it contains spaces or quotes.

        """
        s = s.rstrip()
        l = []
        i = 0

        while i < len(s):
            if s[i] == '"':
                arg, i = self._parse_quoted_string(s, start=i)
                if i < len(s) and s[i] != ' ':
                    raise PythonDialogBug(
                        "expected a space or end-of-string after quoted "
                        "string in {0!r}, but found {1!r}".format(s, s[i]))
                # Start of the next argument, or after the end of the string
                i += 1
                l.append(arg)
            else:
                try:
                    end = s.index(' ', i)
                except ValueError:
                    end = len(s)

                l.append(s[i:end])
                # Start of the next argument, or after the end of the string
                i = end + 1

        return l

    def _parse_help(self, output, kwargs, **_3to2kwargs):
        """Parse the dialog help output from a widget.

        'kwargs' should contain the keyword arguments used in the
        widget call that produced the help output.

        'multival' is for widgets that return a list of values as
        opposed to a single value.

        'raw_format' is for widgets that don't start their help
        output with the string "HELP ".

        """
        if 'raw_format' in _3to2kwargs: raw_format = _3to2kwargs['raw_format']; del _3to2kwargs['raw_format']
        else: raw_format = False
        if 'multival_on_single_line' in _3to2kwargs: multival_on_single_line = _3to2kwargs['multival_on_single_line']; del _3to2kwargs['multival_on_single_line']
        else: multival_on_single_line = False
        if 'multival' in _3to2kwargs: multival = _3to2kwargs['multival']; del _3to2kwargs['multival']
        else: multival = False

        l = output.splitlines()

        if raw_format:
            # This format of the help output is either empty or consists of
            # only one line (possibly terminated with \n). It is
            # encountered with --calendar and --inputbox, among others.
            if len(l) > 1:
                raise PythonDialogBug("raw help feedback unexpected as "
                                      "multiline: {0!r}".format(output))
            elif len(l) == 0:
                return ""
            else:
                return l[0]

        # Simple widgets such as 'yesno' will fall in this case if they use
        # this method.
        if not l:
            return None

        # The widgets that actually use --help-status always have the first
        # help line indicating the active item; there is no risk of
        # confusing this line with the first line produced by --help-status.
        if not l[0].startswith("HELP "):
            raise PythonDialogBug(
                "unexpected help output that does not start with 'HELP ': "
                "{0!r}".format(output))

        # Everything that follows "HELP "; what it contains depends on whether
        # --item-help and/or --help-tags were passed to dialog.
        s = l[0][5:]

        if not self._help_status_on(kwargs):
            return s

        if multival:
            if multival_on_single_line:
                args = self._split_shellstyle_arglist(s)
                if not args:
                    raise PythonDialogBug(
                        "expected a non-empty space-separated list of "
                        "possibly-quoted strings in this help output: {0!r}"
                        .format(output))
                return (args[0], args[1:])
            else:
                return (s, l[1:])
        else:
            if not s:
                raise PythonDialogBug(
                    "unexpected help output whose first line is 'HELP '")
            elif s[0] != '"':
                l2 = s.split(' ', 1)
                if len(l2) == 1:
                    raise PythonDialogBug(
                        "expected 'HELP <id> <status>' in the help output, "
                        "but couldn't find any space after 'HELP '")
                else:
                    return tuple(l2)
            else:
                help_id, after_index = self._parse_quoted_string(s)
                if not s[after_index:].startswith(" "):
                    raise PythonDialogBug(
                        "expected 'HELP <quoted_id> <status>' in the help "
                        "output, but couldn't find any space after "
                        "'HELP <quoted_id>'")
                return (help_id, s[after_index+1:])

    def _widget_with_string_output(self, args, kwargs,
                                   strip_xdialog_newline=False,
                                   raw_help=False):
        """Generic implementation for a widget that produces a single string.

        The help output must be present regardless of whether
        --help-status was passed or not.

        """
        code, output = self._perform(args, **kwargs)

        if strip_xdialog_newline:
            output = self._strip_xdialog_newline(output)

        if code == self.HELP:
            # No check for --help-status
            help_data = self._parse_help(output, kwargs, raw_format=raw_help)
            return (code, help_data)
        else:
            return (code, output)

    def _widget_with_no_output(self, widget_name, args, kwargs):
        """Generic implementation for a widget that produces no output."""
        code, output = self._perform(args, **kwargs)

        if output:
            raise PythonDialogBug(
                "expected an empty output from {0!r}, but got: {1!r}".format(
                    widget_name, output))

        return code

    def _dialog_version_check(self, version_string, feature):
        if self.compat == "dialog":
            minimum_version = DialogBackendVersion.fromstring(version_string)

            if self.cached_backend_version < minimum_version:
                raise InadequateBackendVersion(
                    "{0} requires dialog {1} or later, "
                    "but you seem to be using version {2}".format(
                        feature, minimum_version, self.cached_backend_version))

    def backend_version(self):
        """Get the version of the :program:`dialog`-like program (backend).

        If the version of the :program:`dialog`-like program can be
        retrieved, return it as a string; otherwise, raise
        :exc:`UnableToRetrieveBackendVersion`.

        This version is not to be confused with the pythondialog
        version.

        In most cases, you should rather use the
        :attr:`cached_backend_version` attribute of :class:`Dialog`
        instances, because:

          - it avoids calling the backend every time one needs the
            version;
          - it is a :class:`BackendVersion` instance (or instance of a
            subclass) that allows easy and reliable comparisons between
            versions;
          - the version string corresponding to a
            :class:`BackendVersion` instance (or instance of a subclass)
            can be obtained with :func:`unicode`.

        Notable exceptions:

          - :exc:`UnableToRetrieveBackendVersion`
          - :exc:`PythonDialogReModuleError`
          - any exception raised by :meth:`Dialog._perform`

        .. versionadded:: 2.12

        .. versionchanged:: 2.14
           Raise :exc:`UnableToRetrieveBackendVersion` instead of
           returning ``None`` when the version of the
           :program:`dialog`-like program can't be retrieved.

        """
        code, output = self._perform(["--print-version"],
                                     use_persistent_args=False)

        # Workaround for old dialog versions
        if code == self.OK and not (output.strip() or self.use_stdout):
            # output.strip() is empty and self.use_stdout is False.
            # This can happen with old dialog versions (1.1-20100428
            # apparently does that). Try again, reading from stdout this
            # time.
            self.use_stdout = True
            code, output = self._perform(["--stdout", "--print-version"],
                                         use_persistent_args=False,
                                         dash_escape="none")
            self.use_stdout = False

        if code == self.OK:
            try:
                mo = self._print_version_cre.match(output)
                if mo:
                    return mo.group("version")
                else:
                    raise UnableToRetrieveBackendVersion(
                        "unable to parse the output of '{0} --print-version': "
                        "{1!r}".format(self._dialog_prg, output))
            except re.error, e:
                raise PythonDialogReModuleError(unicode(e))
        else:
            raise UnableToRetrieveBackendVersion(
                "exit code {0!r} from the backend".format(code))

    def maxsize(self, **kwargs):
        """Get the maximum size of dialog boxes.

        If the exit status from the backend corresponds to
        :attr:`Dialog.OK`, return a :samp:`({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 :program:`dialog` options
        such as :option:`--backtitle` modify the returned values.

        Notable exceptions:

          - :exc:`PythonDialogReModuleError`
          - any exception raised by :meth:`Dialog._perform`

        .. versionadded:: 2.12

        """
        code, output = self._perform(["--print-maxsize"], **kwargs)
        if code == self.OK:
            try:
                mo = self._print_maxsize_cre.match(output)
                if mo:
                    return tuple(imap(int, mo.group("rows", "columns")))
                else:
                    raise PythonDialogBug(
                        "Unable to parse the output of '{0} --print-maxsize': "
                        "{1!r}".format(self._dialog_prg, output))
            except re.error, e:
                raise PythonDialogReModuleError(unicode(e))
        else:
            return None

    def _default_size(self, values, defaults):
        # If 'autowidgetsize' is enabled, set the default values for the
        # width/height/... parameters of widget-producing methods to 0 (this
        # will actually be done by the caller, this function is only a helper).
        if self.autowidgetsize:
            defaults = (0,) * len(defaults)

        # For every element of 'values': keep it if different from None,
        # otherwise replace it with the corresponding value from 'defaults'.
        return [ v if v is not None else defaults[i]
                 for i, v in enumerate(values) ]

    @widget
    def buildlist(self, text, height=0, width=0, list_height=0, items=[],
                  **kwargs):
        """Display a buildlist box.

        :param str text:        text to display in the box
        :param int height:      height of the box
        :param int width:       width of the box
        :param int list_height: height of the selected and unselected
                                list boxes
        :param items:
          an iterable of :samp:`({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.

        :return: a tuple of the form :samp:`({code}, {tags})` where:

          - *code* is a :term:`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.

        :rtype: tuple

        A :meth:`!buildlist` dialog is similar in logic to the
        :meth:`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.

        +--------------+------------------------------------------------+
        |     Key      |                     Action                     |
        +==============+================================================+
        | :kbd:`Space` | select or deselect the highlighted item,       |
        |              | *i.e.*, move it between the left and right     |
        |              | lists                                          |
        +--------------+------------------------------------------------+
        | :kbd:`^`     | move the focus to the left list                |
        +--------------+------------------------------------------------+
        | :kbd:`$`     | move the focus to the right list               |
        +--------------+------------------------------------------------+
        | :kbd:`Tab`   | move focus (see *visit_items* below)           |
        +--------------+------------------------------------------------+
        | :kbd:`Enter` | press the focused button                       |
        +--------------+------------------------------------------------+

        If called with ``visit_items=True``, the :kbd:`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 :kbd:`^` and :kbd:`$` for this purpose.

        This widget requires dialog >= 1.2-20121230.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform` or :func:`_to_onoff`

        .. versionadded:: 3.0

        """
        self._dialog_version_check("1.2-20121230", "the buildlist widget")

        cmd = ["--buildlist", text, unicode(height), unicode(width), unicode(list_height)]
        for t in items:
            cmd.extend([ t[0], t[1], _to_onoff(t[2]) ] + list(t[3:]))

        code, output = self._perform(cmd, **kwargs)

        if code == self.HELP:
            help_data = self._parse_help(output, kwargs, multival=True,
                                         multival_on_single_line=True)
            if self._help_status_on(kwargs):
                help_id, selected_tags = help_data

                updated_items = []
                for elt in items:
                    tag, item, status = elt[:3]
                    rest = elt[3:]
                    updated_items.append([ tag, item, tag in selected_tags ]
                                         + list(rest))
                return (code, (help_id, selected_tags, updated_items))
            else:
                return (code, help_data)
        elif code in (self.OK, self.EXTRA):
            return (code, self._split_shellstyle_arglist(output))
        else:
            return (code, None)

    def _calendar_parse_date(self, date_str):
        try:
            mo = _calendar_date_cre.match(date_str)
        except re.error, e:
            raise PythonDialogReModuleError(unicode(e))

        if not mo:
            raise UnexpectedDialogOutput(
                "the dialog-like program returned the following "
                "unexpected output (a date string was expected) from the "
                "calendar box: {0!r}".format(date_str))

        return [ int(s) for s in mo.group("day", "month", "year") ]

    @widget
    def calendar(self, text, height=None, width=0, day=-1, month=-1, year=-1,
                 **kwargs):
        """Display a calendar dialog box.

        :param str text:  text to display in the box
        :param height:    height of the box (minus the calendar height)
        :type height:     int or ``None``
        :param int width: width of the box
        :param int day:   inititial day highlighted
        :param int month: inititial month displayed
        :param int year:  inititial year selected
        :return: a tuple of the form :samp:`({code}, {date})` where:

          - *code* is a :term:`Dialog exit code`;
          - *date* is a list of the form :samp:`[{day}, {month},
            {year}]`, where *day*, *month* and *year* are integers
            corresponding to the date chosen by the user.

        :rtype: tuple

        A :meth:`!calendar` box displays day, month and year in
        separately adjustable windows. If *year* is given as ``0``, the
        current date is used as initial value; otherwise, if any of the
        values for *day*, *month* and *year* is negative, the current
        date's corresponding value is used. You can increment or
        decrement any of those using the :kbd:`Left`, :kbd:`Up`,
        :kbd:`Right` and :kbd:`Down` arrows. Use :kbd:`Tab` or
        :kbd:`Backtab` to move between windows.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=6, width=0``.

        Notable exceptions:

          - any exception raised by :meth:`Dialog._perform`
          - :exc:`UnexpectedDialogOutput`
          - :exc:`PythonDialogReModuleError`

        .. versionchanged:: 3.2
           The default values for *day*, *month* and *year* have been
           changed from ``0`` to ``-1``.

        """
        (height,) = self._default_size((height, ), (6,))
        (code, output) = self._perform(
            ["--calendar", text, unicode(height), unicode(width), unicode(day),
               unicode(month), unicode(year)],
            **kwargs)

        if code == self.HELP:
            # The output does not depend on whether --help-status was passed
            # (dialog 1.2-20130902).
            help_data = self._parse_help(output, kwargs, raw_format=True)
            return (code, self._calendar_parse_date(help_data))
        elif code in (self.OK, self.EXTRA):
            return (code, self._calendar_parse_date(output))
        else:
            return (code, None)

    @widget
    def checklist(self, text, height=None, width=None, list_height=None,
                  choices=[], **kwargs):
        """Display a checklist box.

        :param str text:    text to display in the box
        :param height:      height of the box
        :type height:       int or ``None``
        :param width:       width of the box
        :type width:        int or ``None``
        :param list_height:
          number of entries displayed in the box at a given time (the
          contents can be scrolled)
        :type list_height:  int or ``None``
        :param choices:
          an iterable of :samp:`({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.
        :return: a tuple of the form :samp:`({code}, [{tag}, ...])`
          whose first element is a :term:`Dialog exit code` and second
          element lists all tags for the entries selected by the user.
          If the user exits with :kbd:`Esc` or :guilabel:`Cancel`, the
          returned tag list is empty.

        :rtype: tuple

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=15, width=54, list_height=7``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform` or :func:`_to_onoff`

        """
        height, width, list_height = self._default_size(
            (height, width, list_height), (15, 54, 7))
        cmd = ["--checklist", text, unicode(height), unicode(width), unicode(list_height)]
        for t in choices:
            t = [ t[0], t[1], _to_onoff(t[2]) ] + list(t[3:])
            cmd.extend(t)

        # The dialog output cannot be parsed reliably (at least in dialog
        # 0.9b-20040301) without --separate-output (because double quotes in
        # tags are escaped with backslashes, but backslashes are not
        # themselves escaped and you have a problem when a tag ends with a
        # backslash--the output makes you think you've encountered an embedded
        # double-quote).
        kwargs["separate_output"] = True

        (code, output) = self._perform(cmd, **kwargs)
        # Since we used --separate-output, the tags are separated by a newline
        # in the output. There is also a final newline after the last tag.

        if code == self.HELP:
            help_data = self._parse_help(output, kwargs, multival=True)
            if self._help_status_on(kwargs):
                help_id, selected_tags = help_data

                updated_choices = []
                for elt in choices:
                    tag, item, status = elt[:3]
                    rest = elt[3:]
                    updated_choices.append([ tag, item, tag in selected_tags ]
                                           + list(rest))

                return (code, (help_id, selected_tags, updated_choices))
            else:
                return (code, help_data)
        else:
            return (code, output.split('\n')[:-1])

    def _form_updated_items(self, status, elements):
        """Return a complete list with up-to-date items from 'status'.

        Return a new list of same length as 'elements'. Items are
        taken from 'status', except when data inside 'elements'
        indicates a read-only field: such items are not output by
        dialog ... --help-status ..., and therefore have to be
        extracted from 'elements' instead of 'status'.

        Actually, for 'mixedform', the elements that are defined as
        read-only using the attribute instead of a non-positive
        field_length are not concerned by this function, since they
        are included in the --help-status output.

        """
        res = []
        for i, elt in enumerate(elements):
            label, yl, xl, item, yi, xi, field_length = elt[:7]
            res.append(status[i] if field_length > 0 else item)

        return res

    def _generic_form(self, widget_name, method_name, text, elements, height=0,
                      width=0, form_height=0, **kwargs):
        cmd = ["--%s" % widget_name, text, unicode(height), unicode(width),
               unicode(form_height)]

        if not elements:
            raise BadPythonDialogUsage(
                "{0}.{1}.{2}: empty ELEMENTS sequence: {3!r}".format(
                    __name__, type(self).__name__, method_name, elements))

        elt_len = len(elements[0]) # for consistency checking
        for i, elt in enumerate(elements):
            if len(elt) != elt_len:
                raise BadPythonDialogUsage(
                    "{0}.{1}.{2}: ELEMENTS[0] has length {3}, whereas "
                    "ELEMENTS[{4}] has length {5}".format(
                        __name__, type(self).__name__, method_name,
                        elt_len, i, len(elt)))

            # Give names to make the code more readable
            if widget_name in ("form", "passwordform"):
                label, yl, xl, item, yi, xi, field_length, input_length = \
                    elt[:8]
                rest = elt[8:]  # optional "item_help" string
            elif widget_name == "mixedform":
                label, yl, xl, item, yi, xi, field_length, input_length, \
                    attributes = elt[:9]
                rest = elt[9:]  # optional "item_help" string
            else:
                raise PythonDialogBug(
                    "unexpected widget name in {0}.{1}._generic_form(): "
                    "{2!r}".format(__name__, type(self).__name__, widget_name))

            for name, value in (("LABEL", label), ("ITEM", item)):
                if not isinstance(value, basestring):
                    raise BadPythonDialogUsage(
                        "{0}.{1}.{2}: {3!r} element not a string: {4!r}".format(
                            __name__, type(self).__name__,
                            method_name, name, value))

            cmd.extend((label, unicode(yl), unicode(xl), item, unicode(yi), unicode(xi),
                        unicode(field_length), unicode(input_length)))
            if widget_name == "mixedform":
                cmd.append(unicode(attributes))
            # "item help" string when using --item-help, nothing otherwise
            cmd.extend(rest)

        (code, output) = self._perform(cmd, **kwargs)

        if code == self.HELP:
            help_data = self._parse_help(output, kwargs, multival=True)
            if self._help_status_on(kwargs):
                help_id, status = help_data
                # 'status' does not contain the fields marked as read-only in
                # 'elements'. Build a list containing all up-to-date items.
                updated_items = self._form_updated_items(status, elements)

                # Reconstruct 'elements' with the updated items taken from
                # 'status'.
                updated_elements = []
                for elt, updated_item in izip(elements, updated_items):
                    label, yl, xl, item = elt[:4]
                    rest = elt[4:]
                    updated_elements.append([ label, yl, xl, updated_item ]
                                            + list(rest))
                return (code, (help_id, status, updated_elements))
            else:
                return (code, help_data)
        else:
            return (code, output.split('\n')[:-1])

    @widget
    def form(self, text, elements, height=0, width=0, form_height=0, **kwargs):
        """Display a form consisting of labels and fields.

        :param str text:        text to display in the box
        :param elements:        sequence describing the labels and
                                fields (see below)
        :param int height:      height of the box
        :param int width:       width of the box
        :param int form_height: number of form lines displayed at the
                                same time
        :return: a tuple of the form :samp:`({code}, {list})` where:

          - *code* is a :term:`Dialog exit code`;
          - *list* gives the contents of every editable field on exit,
            with the same order as in *elements*.

        :rtype: tuple

        A :meth:`!form` box consists in a series of :dfn:`fields` and
        associated :dfn:`labels`. This type of dialog is suitable for
        adjusting configuration parameters and similar tasks.

        Each element of *elements* must itself be a sequence
        :samp:`({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*.

        Notable exceptions:

          - :exc:`BadPythonDialogUsage`
          - any exception raised by :meth:`Dialog._perform`

        """
        return self._generic_form("form", "form", text, elements,
                                  height, width, form_height, **kwargs)

    @widget
    def 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 :meth:`form` box, except that
        all text fields are treated as :meth:`passwordbox` widgets
        rather than :meth:`inputbox` widgets.

        By default (as in :program:`dialog)`, nothing is echoed to the
        terminal as the user types in the invisible fields. This can be
        confusing to users. Use ``insecure=True`` (keyword argument) if
        you want an asterisk to be echoed for each character entered by
        the user.

        Notable exceptions:

          - :exc:`BadPythonDialogUsage`
          - any exception raised by :meth:`Dialog._perform`

        """
        return self._generic_form("passwordform", "passwordform", text,
                                  elements, height, width, form_height,
                                  **kwargs)

    @widget
    def mixedform(self, text, elements, height=0, width=0, form_height=0,
                  **kwargs):
        """Display a form consisting of labels and fields.

        :param str text:        text to display in the box
        :param elements:        sequence describing the labels and
                                fields (see below)
        :param int height:      height of the box
        :param int width:       width of the box
        :param int form_height: number of form lines displayed at the
                                same time
        :return: a tuple of the form :samp:`({code}, {list})` where:

          - *code* is a :term:`Dialog exit code`;
          - *list* gives the contents of every field on exit, with the
            same order as in *elements*.

        :rtype: tuple

        A :meth:`!mixedform` box is very similar to a :meth:`form` box,
        and differs from the latter by allowing field attributes to be
        specified.

        Each element of *elements* must itself be a sequence
        :samp:`({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 an integer interpreted as a bit mask with the
        following meaning (bit 0 being the least significant bit):

        +------------+-----------------------------------------------+
        | Bit number |                    Meaning                    |
        +============+===============================================+
        |     0      | the field should be hidden (e.g., a password) |
        +------------+-----------------------------------------------+
        |     1      | the field should be read-only (e.g., a label) |
        +------------+-----------------------------------------------+

        For all other parameters, please refer to the documentation of
        the :meth:`form` box.

        The return value is the same as would be with the :meth:`!form`
        box, except that fields marked as read-only with bit 1 of
        *attributes* are also included in the output list.

        Notable exceptions:

          - :exc:`BadPythonDialogUsage`
          - any exception raised by :meth:`Dialog._perform`

        """
        return self._generic_form("mixedform", "mixedform", text, elements,
                                  height, width, form_height, **kwargs)

    @widget
    def dselect(self, filepath, height=0, width=0, **kwargs):
        """Display a directory selection dialog box.

        :param str filepath: initial path
        :param int height:   height of the box
        :param int width:    width of the box
        :return: a tuple of the form :samp:`({code}, {path})` where:

          - *code* is a :term:`Dialog exit code`;
          - *path* is the directory chosen by the user.

        :rtype: tuple

        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 path to a file, in which case the
        directory window will display the contents of the path and the
        text entry window will contain the preselected directory.

        Use :kbd:`Tab` or the arrow keys to move between the windows.
        Within the directory window, use the :kbd:`Up` and :kbd:`Down`
        arrow keys to scroll the current selection. Use the :kbd:`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 window to the closest match.

        Use :kbd:`Enter` or the :guilabel:`OK` button to accept the
        current value in the text entry window and exit.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        # The help output does not depend on whether --help-status was passed
        # (dialog 1.2-20130902).
        return self._widget_with_string_output(
            ["--dselect", filepath, unicode(height), unicode(width)],
            kwargs, raw_help=True)

    @widget
    def editbox(self, filepath, height=0, width=0, **kwargs):
        """Display a basic text editor dialog box.

        :param str filepath: path to a file which determines the initial
                             contents of the dialog box
        :param int height:   height of the box
        :param int width:    width of the box
        :return: a tuple of the form :samp:`({code}, {text})` where:

          - *code* is a :term:`Dialog exit code`;
          - *text* is the contents of the text entry window on exit.

        :rtype: tuple

        The :meth:`!editbox` dialog displays a copy of the file
        contents. You may edit it using the :kbd:`Backspace`,
        :kbd:`Delete` and cursor keys to correct typing errors. It also
        recognizes :kbd:`Page Up` and :kbd:`Page Down`. Unlike the
        :meth:`inputbox`, you must tab to the :guilabel:`OK` or
        :guilabel:`Cancel` buttons to close the dialog. Pressing the
        :kbd:`Enter` key within the box will split the corresponding
        line.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        return self._widget_with_string_output(
            ["--editbox", filepath, unicode(height), unicode(width)],
            kwargs)

    @widget
    def fselect(self, filepath, height=0, width=0, **kwargs):
        """Display a file selection dialog box.

        :param str filepath: initial path
        :param int height:   height of the box
        :param int width:    width of the box
        :return: a tuple of the form :samp:`({code}, {path})` where:

          - *code* is a :term:`Dialog exit code`;
          - *path* is the path chosen by the user (the last element of
            which may be a directory or a file).

        :rtype: tuple

        The file selection dialog displays a text entry window in
        which you can type a file name (or directory), and above that
        two windows with directory names and file names.

        Here, *filepath* can be a path to a file, in which case the file
        and directory windows will display the contents of the path and
        the text entry window will contain the preselected file name.

        Use :kbd:`Tab` or the arrow keys to move between the windows.
        Within the directory or file name windows, use the :kbd:`Up` and
        :kbd:`Down` arrow keys to scroll the current selection. Use the
        :kbd:`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 file name windows to the closest match.

        Use :kbd:`Enter` or the :guilabel:`OK` button to accept the
        current value in the text entry window, or the
        :guilabel:`Cancel` button to cancel.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        # The help output does not depend on whether --help-status was passed
        # (dialog 1.2-20130902).
        return self._widget_with_string_output(
            ["--fselect", filepath, unicode(height), unicode(width)],
            kwargs, strip_xdialog_newline=True, raw_help=True)

    def gauge_start(self, text="", height=None, width=None, percent=0,
                    **kwargs):
        """Display a gauge box.

        :param str text:    text to display in the box
        :param height:      height of the box
        :type height:       int or ``None``
        :param width:       width of the box
        :type width:        int or ``None``
        :param int percent: initial percentage shown in the meter
        :return:            undefined

        A gauge box displays a meter along the bottom of the box. The
        meter indicates a percentage.

        This function starts the :program:`dialog`-like program, telling
        it to display a gauge box containing a text and an initial
        percentage in the meter.


        .. rubric:: Gauge typical usage

        Gauge typical usage (assuming that *d* is an instance of the
        :class:`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
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=8, width=54``.

        Notable exceptions:

          - any exception raised by :meth:`_call_program`
          - :exc:`PythonDialogOSError`

        """
        height, width = self._default_size((height, width), (8, 54))
        with _OSErrorHandling():
            # We need a pipe to send data to the child (dialog) process's
            # stdin while it is running.
            # rfd = File Descriptor for Reading
            # wfd = File Descriptor for Writing
            (child_stdin_rfd, child_stdin_wfd)  = os.pipe()

            child_pid, child_output_rfd, args_file = self._call_program(
                ["--gauge", text, unicode(height), unicode(width),
                 unicode(percent)],
                redir_child_stdin_from_fd=child_stdin_rfd,
                close_fds=(child_stdin_wfd,), **kwargs)

            # fork() is done. We don't need child_stdin_rfd in the father
            # process anymore.
            os.close(child_stdin_rfd)

            self._gauge_process = {
                "pid": child_pid,
                "stdin": open(child_stdin_wfd, "w"),
                "child_output_rfd": child_output_rfd,
                "args_file": args_file
                }

    def gauge_update(self, percent, text="", update_text=False):
        """Update a running gauge box.

        :param int percent:      new percentage to show in the gauge
                                 meter
        :param str text:         new text to optionally display in the
                                 box
        :param bool update_text: whether to update the text in the box
        :return:                 undefined

        This function updates the percentage shown by the meter of a
        running gauge box (meaning :meth:`gauge_start` must have been
        called previously). If *update_text* is ``True``, the text
        displayed in the box is also updated.

        See the :meth:`gauge_start` method documentation for information
        about how to use a gauge.

        Notable exception:

          :exc:`PythonDialogIOError` (:exc:`PythonDialogOSError` from
          Python 3.3 onwards) can be raised if there is an I/O error
          while trying to write to the pipe used to talk to the
          :program:`dialog`-like program.

        """
        if not isinstance(percent, int):
            raise BadPythonDialogUsage(
                "the 'percent' argument of gauge_update() must be an integer, "
                "but {0!r} is not".format(percent))

        if update_text:
            gauge_data = "XXX\n{0}\n{1}\nXXX\n".format(percent, text)
        else:
            gauge_data = "{0}\n".format(percent)
        with _OSErrorHandling():
            self._gauge_process["stdin"].write(gauge_data)
            self._gauge_process["stdin"].flush()

    # For "compatibility" with the old dialog.py...
    def gauge_iterate(*args, **kwargs):
        """Update a running gauge box.

        .. deprecated:: 2.03
          Use :meth:`gauge_update` instead.

        """
        warnings.warn("Dialog.gauge_iterate() has been obsolete for "
                      "many years", DeprecationWarning)
        gauge_update(*args, **kwargs)

    @widget
    @retval_is_code
    def gauge_stop(self):
        """Terminate a running gauge widget.

        :return:         a :term:`Dialog exit code`
        :rtype:          str

        This function performs the appropriate cleanup actions to
        terminate a running gauge started with :meth:`gauge_start`.

        See the :meth:`!gauge_start` method documentation for
        information about how to use a gauge.

        Notable exceptions:

          - any exception raised by :meth:`_handle_program_exit`;
          - :exc:`PythonDialogIOError` (:exc:`PythonDialogOSError` from
            Python 3.3 onwards) can be raised if closing the pipe used
            to talk to the :program:`dialog`-like program fails.

        """
        p = self._gauge_process
        # Close the pipe that we are using to feed dialog's stdin
        with _OSErrorHandling():
            p["stdin"].close()
        # According to dialog(1), the output should always be empty.
        exit_code = self._handle_program_exit(p["pid"],
                                              p["child_output_rfd"],
                                              p["args_file"])[0]
        return exit_code

    @widget
    @retval_is_code
    def infobox(self, text, height=None, width=None, **kwargs):
        """Display an information dialog box.

        :param str text: text to display in the box
        :param height:   height of the box
        :type height:    int or ``None``
        :param width:    width of the box
        :type width:     int or ``None``
        :return:         a :term:`Dialog exit code`
        :rtype:          str

        An info box is basically a message box. However, in this case,
        :program:`dialog` will exit immediately after displaying the
        message to the user. The screen is not cleared when
        :program:`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.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=10, width=30``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (10, 30))
        return self._widget_with_no_output(
            "infobox",
            ["--infobox", text, unicode(height), unicode(width)],
            kwargs)

    @widget
    def inputbox(self, text, height=None, width=None, init='', **kwargs):
        """Display an input dialog box.

        :param str text: text to display in the box
        :param height:   height of the box
        :type height:    int or ``None``
        :param width:    width of the box
        :type width:     int or ``None``
        :param str init: default input string
        :return: a tuple of the form :samp:`({code}, {string})` where:

          - *code* is a :term:`Dialog exit code`;
          - *string* is the string entered by the user.

        :rtype: tuple

        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 :kbd:`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.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=10, width=30``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (10, 30))
        # The help output does not depend on whether --help-status was passed
        # (dialog 1.2-20130902).
        return self._widget_with_string_output(
            ["--inputbox", text, unicode(height), unicode(width), init],
            kwargs, strip_xdialog_newline=True, raw_help=True)

    @widget
    def inputmenu(self, text, height=0, width=None, menu_height=None,
                  choices=[], **kwargs):
        """Display an inputmenu dialog box.

        :param str text:    text to display in the box
        :param int height:  height of the box
        :param width:       width of the box
        :type width:        int or ``None``
        :param menu_height: height of the menu (scrollable part)
        :type menu_height:  int or ``None``
        :param choices:     an iterable of :samp:`({tag}, {item})`
                            tuples, the meaning of which is explained
                            below
        :return:            see :ref:`below <inputmenu-return-value>`


        .. rubric:: Overview

        An :meth:`!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 :meth:`menu` dialog box are:

          - entries are not automatically centered, but left-adjusted;

          - the current entry can be renamed by pressing the
            :guilabel:`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 :dfn:`tag` gives the entry a name to distinguish it from the
        other entries in the menu and to provide quick keyboard access.
        The :dfn:`item` is a short description of the option that the
        entry represents.

        The user can move between the menu entries by pressing the
        :kbd:`Up` and :kbd:`Down` arrow 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.

        At the time of this writing (with :program:`dialog`
        1.2-20140219), it is not possible to add an Extra button to this
        widget, because internally, the :guilabel:`Rename` button *is*
        the Extra button.

        .. note::

          It is strongly advised not to put any space in tags, otherwise
          the :program:`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 :program:`dialog` output
          is :samp:`RENAMED {tag} {item}` and pythondialog cannot guess
          whether spaces after the :samp:`RENAMED` + *space* 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
          :guilabel:`Help` button (or any button other than
          :guilabel:`Rename`) once one has started to rename an item.

        .. _inputmenu-return-value:

        .. rubric:: Return value

        Return a tuple of the form :samp:`({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 :term:`Dialog exit codes <Dialog exit
              code>` :attr:`Dialog.CANCEL`, :attr:`Dialog.ESC` or
              :attr:`Dialog.HELP` (:attr:`Dialog.EXTRA` can't be
              returned, because internally, the :guilabel:`Rename`
              button *is* the Extra button).

          + *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 :guilabel:`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
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=0, width=60, menu_height=7``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        width, menu_height = self._default_size((width, menu_height), (60, 7))
        cmd = ["--inputmenu", text, unicode(height), unicode(width), unicode(menu_height)]
        for t in choices:
            cmd.extend(t)
        (code, output) = self._perform(cmd, **kwargs)

        if code == self.HELP:
            help_id = self._parse_help(output, kwargs)
            return (code, help_id, None)
        elif code == self.OK:
            return ("accepted", output, None)
        elif code == self.EXTRA:
            if not output.startswith("RENAMED "):
                raise PythonDialogBug(
                    "'output' does not start with 'RENAMED ': {0!r}".format(
                        output))
            t = output.split(' ', 2)
            return ("renamed", t[1], t[2])
        else:
            return (code, None, None)

    @widget
    def menu(self, text, height=None, width=None, menu_height=None, choices=[],
             **kwargs):
        """Display a menu dialog box.

        :param str text:        text to display in the box
        :param height:      height of the box
        :type height:       int or ``None``
        :param width:       width of the box
        :type width:        int or ``None``
        :param menu_height: number of entries displayed in the box
                            (which can be scrolled) at a given time
        :type menu_height:  int or ``None``
        :param choices:     an iterable of :samp:`({tag}, {item})`
                            tuples, the meaning of which is explained
                            below
        :return: a tuple of the form :samp:`({code}, {tag})` where:

          - *code* is a :term:`Dialog exit code`;
          - *tag* is the tag string corresponding to the item that the
            user chose.

        :rtype: tuple

        As its name suggests, a :meth:`!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 :dfn:`tag` gives the entry a name to distinguish it from the
        other entries in the menu and to provide quick keyboard access.
        The :dfn:`item` is a short description of the option that the
        entry represents.

        The user can move between the menu entries by pressing the
        :kbd:`Up` and :kbd:`Down` arrow keys, the first letter of the
        tag as a hotkey, or the number keys :kbd:`1` through :kbd:`9`.
        There are *menu_height* entries displayed in the menu at one
        time, but it will be scrolled if there are more entries than
        that.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=15, width=54, menu_height=7``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width, menu_height = self._default_size(
            (height, width, menu_height), (15, 54, 7))
        cmd = ["--menu", text, unicode(height), unicode(width), unicode(menu_height)]
        for t in choices:
            cmd.extend(t)

        return self._widget_with_string_output(
            cmd, kwargs, strip_xdialog_newline=True)

    @widget
    @retval_is_code
    def mixedgauge(self, text, height=0, width=0, percent=0, elements=[],
             **kwargs):
        """Display a mixed gauge dialog box.

        :param str text:    text to display in the middle of the box,
                            between the elements list and the progress
                            bar
        :param int height:  height of the box
        :param int width:   width of the box
        :param int percent: integer giving the percentage for the global
                            progress bar
        :param elements:    an iterable of :samp:`({tag}, {item})`
                            tuples, the meaning of which is explained
                            below
        :return:            a :term:`Dialog exit code`
        :rtype:             str

        A :meth:`!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* part of an element can be an arbitrary string.
        Special values listed in the :manpage:`dialog(3)` manual page
        are translated 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 :program:`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 regular :ref:`gauge widget <gauge-widget>`,
        :meth:`!mixedgauge` is completely static. You have to call
        :meth:`!mixedgauge` several times in order to display different
        percentages in the global progress bar or various status
        indicators for a given task.

        .. note::

           Calling :meth:`!mixedgauge` several times is likely to cause
           unwanted flickering because of the screen initializations
           performed by :program:`dialog` on every run.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        cmd = ["--mixedgauge", text, unicode(height), unicode(width), unicode(percent)]
        for t in elements:
            cmd.extend( (t[0], unicode(t[1])) )
        return self._widget_with_no_output("mixedgauge", cmd, kwargs)

    @widget
    @retval_is_code
    def msgbox(self, text, height=None, width=None, **kwargs):
        """Display a message dialog box, with scrolling and line wrapping.

        :param str text: text to display in the box
        :param height:   height of the box
        :type height:    int or ``None``
        :param width:    width of the box
        :type width:     int or ``None``
        :return:         a :term:`Dialog exit code`
        :rtype:          str

        Display *text* in a message box, with a scrollbar and percentage
        indication if *text* is too long to fit in a single "screen".

        An :meth:`!msgbox` is very similar to a :meth:`yesno` box. The
        only difference between an :meth:`!msgbox` and a :meth:`!yesno`
        box is that the former only has a single :guilabel:`OK` button.
        You can use :meth:`!msgbox` to display any message you like.
        After reading the message, the user can press the :kbd:`Enter`
        key so that :program:`dialog` will exit and the calling program
        can continue its operation.

        :meth:`!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
        :program:`dialog` only inserts **additional** newlines when
        needed. If you want no automatic line wrapping, consider using
        :meth:`scrollbox`.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=10, width=30``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (10, 30))
        return self._widget_with_no_output(
            "msgbox",
            ["--msgbox", text, unicode(height), unicode(width)],
            kwargs)

    @widget
    @retval_is_code
    def pause(self, text, height=None, width=None, seconds=5, **kwargs):
        """Display a pause dialog box.

        :param str text:    text to display in the box
        :param height:      height of the box
        :type height:       int or ``None``
        :param width:       width of the box
        :type width:        int or ``None``
        :param int seconds: number of seconds to pause for
        :return:
          a :term:`Dialog exit code` (which is :attr:`Dialog.OK` if the
          widget ended automatically after *seconds* seconds or if the
          user pressed the :guilabel:`OK` button)
        :rtype:             str

        A :meth:`!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
        :guilabel:`OK` button, the :guilabel:`Cancel` button or the
        :kbd:`Esc` key.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=15, width=60``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (15, 60))
        return self._widget_with_no_output(
            "pause",
            ["--pause", text, unicode(height), unicode(width), unicode(seconds)],
            kwargs)

    @widget
    def passwordbox(self, text, height=None, width=None, init='', **kwargs):
        """Display a password input dialog box.

        :param str text:  text to display in the box
        :param height:    height of the box
        :type height:     int or ``None``
        :param width:     width of the box
        :type width:      int or ``None``
        :param str init:  default input password
        :return: a tuple of the form :samp:`({code}, {password})` where:

          - *code* is a :term:`Dialog exit code`;
          - *password* is the password entered by the user.

        :rtype: tuple

        A :meth:`!passwordbox` is similar to an :meth:`inputbox`, 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 :program:`dialog`), nothing is echoed to the
        terminal as the user enters the sensitive text. This can be
        confusing to users. Use ``insecure=True`` (keyword argument) if
        you want an asterisk to be echoed for each character entered by
        the user.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=10, width=60``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (10, 60))
        # The help output does not depend on whether --help-status was passed
        # (dialog 1.2-20130902).
        return self._widget_with_string_output(
            ["--passwordbox", text, unicode(height), unicode(width), init],
            kwargs, strip_xdialog_newline=True, raw_help=True)

    def _progressboxoid(self, widget, file_path=None, file_flags=os.O_RDONLY,
                        fd=None, text=None, height=20, width=78, **kwargs):
        if (file_path is None and fd is None) or \
                (file_path is not None and fd is not None):
            raise BadPythonDialogUsage(
                "{0}.{1}.{2}: either 'file_path' or 'fd' must be provided, and "
                "not both at the same time".format(
                    __name__, self.__class__.__name__, widget))

        with _OSErrorHandling():
            if file_path is not None:
                if fd is not None:
                    raise PythonDialogBug(
                        "unexpected non-None value for 'fd': {0!r}".format(fd))
                # No need to pass 'mode', as the file is not going to be
                # created here.
                fd = os.open(file_path, file_flags)

            try:
                args = [ "--{0}".format(widget) ]
                if text is not None:
                    args.append(text)
                args.extend([unicode(height), unicode(width)])

                kwargs["redir_child_stdin_from_fd"] = fd
                code = self._widget_with_no_output(widget, args, kwargs)
            finally:
                with _OSErrorHandling():
                    if file_path is not None:
                        # We open()ed file_path ourselves, let's close it now.
                        os.close(fd)

        return code

    @widget
    @retval_is_code
    def progressbox(self, file_path=None, file_flags=os.O_RDONLY,
                    fd=None, text=None, height=None, width=None, **kwargs):
        """
        Display a possibly growing stream in a dialog box, as with ``tail -f``.

        A file, or more generally a stream that can be read from, must
        be specified with either:

        :param str file_path: path to the file that is going to be displayed
        :param file_flags:
          flags used when opening *file_path*; those are passed to
          :func:`os.open` (not the built-in :func:`open` function!). By
          default, only one flag is set: :data:`os.O_RDONLY`.

        or

        :param int fd: file descriptor for the stream to be displayed

        Remaining parameters:

        :param text:   caption continuously displayed at the top, above
                       the stream text, or ``None`` to disable the
                       caption
        :param height: height of the box
        :type height:  int or ``None``
        :param width:  width of the box
        :type width:   int or ``None``
        :return:       a :term:`Dialog exit code`
        :rtype:        str

        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 :func:`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 :func:`os.pipe`).

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=20, width=78``.

        Notable exceptions:

          - :exc:`PythonDialogOSError` (:exc:`PythonDialogIOError` if
            the Python version is < 3.3)
          - any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (20, 78))
        return self._progressboxoid(
            "progressbox", file_path=file_path, file_flags=file_flags,
            fd=fd, text=text, height=height, width=width, **kwargs)

    @widget
    @retval_is_code
    def programbox(self, file_path=None, file_flags=os.O_RDONLY,
                   fd=None, text=None, height=None, width=None, **kwargs):
        """
        Display a possibly growing stream in a dialog box, as with ``tail -f``.

        A :meth:`!programbox` is very similar to a :meth:`progressbox`.
        The only difference between a :meth:`!programbox` and a
        :meth:`!progressbox` is that a :meth:`!programbox` displays an
        :guilabel:`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 :kbd:`Enter` key to close the dialog and resume
        execution of the calling program.

        The parameters and exceptions are the same as for
        :meth:`progressbox`. Please refer to the corresponding
        documentation.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=20, width=78``.

        This widget requires :program:`dialog` >= 1.1-20110302.

        .. versionadded:: 2.14

        """
        self._dialog_version_check("1.1-20110302", "the programbox widget")

        height, width = self._default_size((height, width), (20, 78))
        return self._progressboxoid(
            "programbox", file_path=file_path, file_flags=file_flags,
            fd=fd, text=text, height=height, width=width, **kwargs)

    @widget
    def radiolist(self, text, height=None, width=None, list_height=None,
                  choices=[], **kwargs):
        """Display a radiolist box.

        :param str text:    text to display in the box
        :param height:      height of the box
        :type height:       int or ``None``
        :param width:       width of the box
        :type width:        int or ``None``
        :param list_height: number of entries displayed in the box
                            (which can be scrolled) at a given time
        :type list_height:  int or ``None``
        :param choices:
          an iterable of :samp:`({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. No more than one entry should be set to ``True``.
        :return: a tuple of the form :samp:`({code}, {tag})` where:

          - *code* is a :term:`Dialog exit code`;
          - *tag* is the tag string corresponding to the entry that was
            chosen by the user.

        :rtype: tuple

        A :meth:`!radiolist` box is similar to a :meth:`menu` box. The
        main differences are presentation and that the
        :meth:`!radiolist` allows you to indicate which entry is
        initially selected, by setting its status to ``True``.

        If the user exits with :kbd:`Esc` or :guilabel:`Cancel`, or if
        all entries were initially set to ``False`` and not altered
        before the user chose :guilabel:`OK`, the returned tag is the
        empty string.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=15, width=54, list_height=7``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform` or :func:`_to_onoff`

        """
        height, width, list_height = self._default_size(
            (height, width, list_height), (15, 54, 7))

        cmd = ["--radiolist", text, unicode(height), unicode(width), unicode(list_height)]
        for t in choices:
            cmd.extend([ t[0], t[1], _to_onoff(t[2]) ] + list(t[3:]))
        (code, output) = self._perform(cmd, **kwargs)

        output = self._strip_xdialog_newline(output)

        if code == self.HELP:
            help_data = self._parse_help(output, kwargs)
            if self._help_status_on(kwargs):
                help_id, selected_tag = help_data

                # Reconstruct 'choices' with the selected item inferred from
                # 'selected_tag'.
                updated_choices = []
                for elt in choices:
                    tag, item, status = elt[:3]
                    rest = elt[3:]
                    updated_choices.append([ tag, item, tag == selected_tag ]
                                           + list(rest))

                return (code, (help_id, selected_tag, updated_choices))
            else:
                return (code, help_data)
        else:
            return (code, output)

    @widget
    def rangebox(self, text, height=0, width=0, min=None, max=None, init=None,
                 **kwargs):
        """Display a range dialog box.

        :param str text:   text to display above the actual range control
        :param int height: height of the box
        :param int width:  width of the box
        :param int min:    minimum value for the range control
        :param int max:    maximum value for the range control
        :param int init:   initial value for the range control
        :return: a tuple of the form :samp:`({code}, {val})` where:

          - *code* is a :term:`Dialog exit code`;
          - *val* is an integer: the value chosen by the user.

        :rtype: tuple

        The :meth:`!rangebox` dialog allows the user to select from a
        range of integers using a kind of slider. The range control
        shows the current value as a bar (like the :ref:`gauge dialog
        <gauge-widget>`).

        The :kbd:`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:

        +-----------------------+----------------------------+
        |          Key          |           Action           |
        +=======================+============================+
        | :kbd:`Left` and       | select a digit to modify   |
        | :kbd:`Right` arrows   |                            |
        +-----------------------+----------------------------+
        | :kbd:`+` / :kbd:`-`   | increment/decrement the    |
        |                       | selected digit by one unit |
        +-----------------------+----------------------------+
        | :kbd:`0`–:kbd:`9`     | set the selected digit to  |
        |                       | the given value            |
        +-----------------------+----------------------------+

        Some keys are also recognized in all cursor positions:

        +------------------+--------------------------------------+
        |       Key        |                Action                |
        +==================+======================================+
        | :kbd:`Home` /    | set the value to its minimum or      |
        | :kbd:`End`       | maximum                              |
        +------------------+--------------------------------------+
        | :kbd:`Page Up` / | decrement/increment the value so     |
        | :kbd:`Page Down` | that the slider moves by one column  |
        +------------------+--------------------------------------+

        This widget requires :program:`dialog` >= 1.2-20121230.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        .. versionadded:: 2.14

        """
        self._dialog_version_check("1.2-20121230", "the rangebox widget")

        for name in ("min", "max", "init"):
            if not isinstance(locals()[name], int):
                raise BadPythonDialogUsage(
                    "'{0}' argument not an int: {1!r}".format(name,
                                                              locals()[name]))
        (code, output) = self._perform(
            ["--rangebox", text] + [ unicode(i) for i in
                                     (height, width, min, max, init) ],
            **kwargs)

        if code == self.HELP:
            help_data = self._parse_help(output, kwargs, raw_format=True)
            # The help output does not depend on whether --help-status was
            # passed (dialog 1.2-20130902).
            return (code, int(help_data))
        elif code in (self.OK, self.EXTRA):
            return (code, int(output))
        else:
            return (code, None)

    @widget
    @retval_is_code
    def scrollbox(self, text, height=None, width=None, **kwargs):
        """Display a string in a scrollable box, with no line wrapping.

        :param str text: string to display in the box
        :param height:   height of the box
        :type height:    int or ``None``
        :param width:    width of the box
        :type width:     int or ``None``
        :return:         a :term:`Dialog exit code`
        :rtype:          str

        This method is a layer on top of :meth:`textbox`. The
        :meth:`!textbox` widget in :program:`dialog` allows one to
        display file contents only. This method can be used to display
        any text in a scrollable box. This is simply done by creating a
        temporary file, calling :meth:`!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 :meth:`msgbox`
        widget instead (the :mod:`textwrap` module from the Python
        standard library is also worth knowing about).

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=20, width=78``.

        Notable exceptions:

          :exc:`PythonDialogOSError` (:exc:`PythonDialogIOError` if the
          Python version is < 3.3)

        .. versionchanged:: 3.1
           :exc:`UnableToCreateTemporaryDirectory` exception can't be
           raised anymore. The equivalent condition now raises
           :exc:`PythonDialogOSError`.

        """
        height, width = self._default_size((height, width), (20, 78))

        with _OSErrorHandling():
            # There is currently no 'encoding' parameter in
            # tempfile.NamedTemporaryFile(), and the encoding for text files
            # defaults to ASCII in Python 2 → let's use binary mode.
            tmpfile = tempfile.NamedTemporaryFile(
                mode="wb", prefix="pythondialog.tmp", delete=False)
            try:
                with tmpfile as f:
                    f.write(text.encode(locale.getpreferredencoding(False)))
                # The temporary file is now closed. According to the tempfile
                # module documentation, this is necessary if we want to be able
                # to reopen it reliably regardless of the platform.

                # Ask for an empty title unless otherwise specified
                if kwargs.get("title", None) is None:
                    kwargs["title"] = ""

                return self._widget_with_no_output(
                    "textbox",
                    ["--textbox", tmpfile.name, unicode(height), unicode(width)],
                    kwargs)
            finally:
                # The test should always succeed, but I prefer being on the
                # safe side.
                if os.path.exists(tmpfile.name):
                    os.unlink(tmpfile.name)

    @widget
    @retval_is_code
    def tailbox(self, filepath, height=None, width=None, **kwargs):
        """Display the contents of a file in a dialog box, as with ``tail -f``.

        :param str filepath: path to a file, the contents of which is to
                             be displayed in the box
        :param height:       height of the box
        :type height:        int or ``None``
        :param width:        width of the box
        :type width:         int or ``None``
        :return:             a :term:`Dialog exit code`
        :rtype:              str

        Display the contents of the file specified with *filepath*,
        updating the dialog box whenever the file grows, as with the
        ``tail -f`` command.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=20, width=60``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (20, 60))
        return self._widget_with_no_output(
            "tailbox",
            ["--tailbox", filepath, unicode(height), unicode(width)],
            kwargs)
    # No tailboxbg widget, at least for now.

    @widget
    @retval_is_code
    def textbox(self, filepath, height=None, width=None, **kwargs):
        """Display the contents of a file in a dialog box.

        :param str filepath: path to a file, the contents of which is to
                             be displayed in the box
        :param height:       height of the box
        :type height:        int or ``None``
        :param width:        width of the box
        :type width:         int or ``None``
        :return:             a :term:`Dialog exit code`
        :rtype:              str

        A :meth:`!textbox` 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 using the :kbd:`Up` and :kbd:`Down`
        arrow keys, :kbd:`Page Up` and :kbd:`Page Down` as well as the
        :kbd:`Home` and :kbd:`End` keys available on most keyboards. If
        the lines are too long to be displayed in the box, the
        :kbd:`Left` and :kbd:`Right` arrow keys can be used to scroll
        the text region horizontally. For more convenience, forward and
        backward search functions are also provided.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=20, width=60``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (20, 60))
        # This is for backward compatibility... not that it is
        # stupid, but I prefer explicit programming.
        if kwargs.get("title", None) is None:
            kwargs["title"] = filepath

        return self._widget_with_no_output(
            "textbox",
            ["--textbox", filepath, unicode(height), unicode(width)],
            kwargs)

    def _timebox_parse_time(self, time_str):
        try:
            mo = _timebox_time_cre.match(time_str)
        except re.error, e:
            raise PythonDialogReModuleError(unicode(e))

        if not mo:
            raise UnexpectedDialogOutput(
                "the dialog-like program returned the following "
                "unexpected output (a time string was expected) with the "
                "--timebox option: {0!r}".format(time_str))

        return [ int(s) for s in mo.group("hour", "minute", "second") ]

    @widget
    def timebox(self, text, height=None, width=None, hour=-1, minute=-1,
                second=-1, **kwargs):
        """Display a time dialog box.

        :param str text:   text to display in the box
        :param height:     height of the box
        :type height:      int or ``None``
        :param int width:  width of the box
        :type width:       int or ``None``
        :param int hour:   inititial hour selected
        :param int minute: inititial minute selected
        :param int second: inititial second selected
        :return: a tuple of the form :samp:`({code}, {time})` where:

          - *code* is a :term:`Dialog exit code`;
          - *time* is a list of the form :samp:`[{hour}, {minute},
            {second}]`, where *hour*, *minute* and *second* are integers
            corresponding to the time chosen by the user.

        :rtype: tuple

        :meth:`timebox` is a dialog box which allows one to select an
        hour, minute and second. If any of the values for *hour*,
        *minute* and *second* is negative, the current time's
        corresponding value is used. You can increment or decrement any
        of those using the :kbd:`Left`, :kbd:`Up`, :kbd:`Right` and
        :kbd:`Down` arrows. Use :kbd:`Tab` or :kbd:`Backtab` to move
        between windows.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=3, width=30``.

        Notable exceptions:

          - any exception raised by :meth:`Dialog._perform`
          - :exc:`PythonDialogReModuleError`
          - :exc:`UnexpectedDialogOutput`

        """
        height, width = self._default_size((height, width), (3, 30))
        (code, output) = self._perform(
            ["--timebox", text, unicode(height), unicode(width),
               unicode(hour), unicode(minute), unicode(second)],
            **kwargs)

        if code == self.HELP:
            help_data = self._parse_help(output, kwargs, raw_format=True)
            # The help output does not depend on whether --help-status was
            # passed (dialog 1.2-20130902).
            return (code, self._timebox_parse_time(help_data))
        elif code in (self.OK, self.EXTRA):
            return (code, self._timebox_parse_time(output))
        else:
            return (code, None)

    @widget
    def treeview(self, text, height=0, width=0, list_height=0,
                 nodes=[], **kwargs):
        """Display a treeview box.

        :param str text:        text to display at the top of the box
        :param int height:      height of the box
        :param int width:       width of the box
        :param int list_height:
          number of lines reserved for the main part of the box,
          where the tree is displayed
        :param nodes:
          an iterable of :samp:`({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 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;
            - *depth* is a non-negative integer indicating the depth
              of the node in the tree (``0`` for the root node).

        :return: a tuple of the form :samp:`({code}, {tag})` where:

          - *code* is a :term:`Dialog exit code`;
          - *tag* is the tag of the selected 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;
        *tag*\s are only used for the return value. Only one node can
        be selected at a given time, as for the :meth:`radiolist`
        widget.

        This widget requires :program:`dialog` >= 1.2-20121230.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform` or :func:`_to_onoff`

        .. versionadded:: 2.14

        """
        self._dialog_version_check("1.2-20121230", "the treeview widget")
        cmd = ["--treeview", text, unicode(height), unicode(width), unicode(list_height)]

        nselected = 0
        for i, t in enumerate(nodes):
            if not isinstance(t[3], int):
                raise BadPythonDialogUsage(
                    "fourth element of node {0} not an int: {1!r}".format(
                        i, t[3]))

            status = _to_onoff(t[2])
            if status == "on":
                nselected += 1

            cmd.extend([ t[0], t[1], status, unicode(t[3]) ] + list(t[4:]))

        if nselected != 1:
            raise BadPythonDialogUsage(
                "exactly one node must be selected, not {0}".format(nselected))

        (code, output) = self._perform(cmd, **kwargs)

        if code == self.HELP:
            help_data = self._parse_help(output, kwargs)
            if self._help_status_on(kwargs):
                help_id, selected_tag = help_data

                # Reconstruct 'nodes' with the selected item inferred from
                # 'selected_tag'.
                updated_nodes = []
                for elt in nodes:
                    tag, item, status = elt[:3]
                    rest = elt[3:]
                    updated_nodes.append([ tag, item, tag == selected_tag ]
                                         + list(rest))

                return (code, (help_id, selected_tag, updated_nodes))
            else:
                return (code, help_data)
        elif code in (self.OK, self.EXTRA):
            return (code, output)
        else:
            return (code, None)

    @widget
    @retval_is_code
    def yesno(self, text, height=None, width=None, **kwargs):
        """Display a yes/no dialog box.

        :param str text: text to display in the box
        :param height:   height of the box
        :type height:    int or ``None``
        :param width:    width of the box
        :type width:     int or ``None``
        :return:         a :term:`Dialog exit code`
        :rtype:          str

        Display a dialog box containing *text* and two buttons labelled
        :guilabel:`Yes` and :guilabel:`No` by default.

        The box size is *height* rows by *width* columns. If *text* is
        too long to fit in one line, it will be automatically divided
        into multiple lines at appropriate places. *text* may also
        contain the substring ``"\\n"`` or newline characters to control
        line breaking explicitly.

        This :meth:`!yesno` dialog box is useful for asking questions
        that require the user to answer either "yes" or "no". These are
        the default button labels, however they can be freely set with
        the ``yes_label`` and ``no_label`` keyword arguments. The user
        can switch between the buttons by pressing the :kbd:`Tab` key.

        Default values for the size parameters when the
        :ref:`autowidgetsize <autowidgetsize>` option is disabled:
        ``height=10, width=30``.

        Notable exceptions:

          any exception raised by :meth:`Dialog._perform`

        """
        height, width = self._default_size((height, width), (10, 30))
        return self._widget_with_no_output(
            "yesno",
            ["--yesno", text, unicode(height), unicode(width)],
            kwargs)