| Server IP : 107.13.46.68 / Your IP : 216.73.216.232 Web Server : Apache/2.4.58 (Ubuntu) System : Linux mariOS 6.8.0-51-generic #52-Ubuntu SMP PREEMPT_DYNAMIC Thu Dec 5 13:09:44 UTC 2024 x86_64 User : www-data ( 33) PHP Version : 8.3.6 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : OFF | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/python3-dialog/html/ |
Upload File : |
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Dialog class overview — pythondialog 3.5.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="The Dialog widgets" href="widgets.html" />
<link rel="prev" title="A gentle introduction" href="intro/intro.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="widgets.html" title="The Dialog widgets"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="intro/intro.html" title="A gentle introduction"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pythondialog 3.5.1 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code> class overview</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="dialog-class-overview">
<h1><a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> class overview<a class="headerlink" href="#dialog-class-overview" title="Permalink to this heading">¶</a></h1>
<section id="initializing-a-dialog-instance">
<h2>Initializing a <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> instance<a class="headerlink" href="#initializing-a-dialog-instance" title="Permalink to this heading">¶</a></h2>
<p>Since all widgets in pythondialog are implemented as methods of the
<a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> class, a pythondialog-based application usually starts by
creating a <code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code> instance.</p>
<dl class="py class">
<dt class="sig sig-object py" id="dialog.Dialog">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dialog.</span></span><span class="sig-name descname"><span class="pre">Dialog</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dialog</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'dialog'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">DIALOGRC</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'dialog'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">use_stdout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">autowidgetsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pass_args_via_file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog" title="Permalink to this definition">¶</a></dt>
<dd><p>Class providing bindings for <strong class="program">dialog</strong>-compatible programs.</p>
<p>This class allows you to invoke <strong class="program">dialog</strong> or a compatible
program in a pythonic way to quickly and easily build simple but
nice text interfaces.</p>
<p>An application typically creates one instance of the <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a>
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.</p>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.__init__">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dialog</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'dialog'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">DIALOGRC</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compat</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'dialog'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">use_stdout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">autowidgetsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pass_args_via_file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Constructor for <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> instances.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>dialog</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – name of (or path to) the <strong class="program">dialog</strong>-like program to
use. If it contains a slash (<code class="docutils literal notranslate"><span class="pre">/</span></code>), it must be a relative or
absolute path to a file that has read and execute permissions,
and is used as is; otherwise, it is looked for according to
the contents of the <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> environment variable, which
defaults to <code class="docutils literal notranslate"><span class="pre">/bin:/usr/bin</span></code> if unset. In case you decide to
use a relative path containing a <code class="docutils literal notranslate"><span class="pre">/</span></code>, be <em>very careful</em>
about the current directory at the time the Dialog instance is
created. Indeed, if for instance you use <code class="docutils literal notranslate"><span class="pre">"foobar/dialog"</span></code>
and your program creates the Dialog instance at a time where
the current directory is for instance <code class="docutils literal notranslate"><span class="pre">/tmp</span></code>, then
<code class="docutils literal notranslate"><span class="pre">/tmp/foobar/dialog</span></code> will be run, which could be risky. If
you don’t understand this, stay with the default, use a value
containing no <code class="docutils literal notranslate"><span class="pre">/</span></code>, or use an absolute path (i.e., one
starting with a <code class="docutils literal notranslate"><span class="pre">/</span></code>).</p></li>
<li><p><strong>DIALOGRC</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – string to pass to the <strong class="program">dialog</strong>-like program as the
<span class="target" id="index-1"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">DIALOGRC</span></code> environment variable, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if no
modification to the environment regarding this variable should
be done in the call to the <strong class="program">dialog</strong>-like program</p></li>
<li><p><strong>compat</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – compatibility mode (see <a class="reference internal" href="#dialog-constructor-compat-arg"><span class="std std-ref">below</span></a>)</p></li>
<li><p><strong>use_stdout</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/functions.html#bool" title="(in Python v3.11)"><em>bool</em></a>) – read <strong class="program">dialog</strong>’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 <strong class="program">Xdialog</strong> and should only be used if you have a
good reason to do so.</p></li>
<li><p><strong>autowidgetsize</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/functions.html#bool" title="(in Python v3.11)"><em>bool</em></a>) – whether to enable <em>autowidgetsize</em> mode. When enabled, all
pythondialog widget-producing methods will behave as if
<code class="docutils literal notranslate"><span class="pre">width=0</span></code>, <code class="docutils literal notranslate"><span class="pre">height=0</span></code>, etc. had been passed, except where
these parameters are explicitely specified with different
values. This has the effect that, by default, the
<strong class="program">dialog</strong> backend will automatically compute a
suitable size for the widgets. More details about this option
are given <a class="reference internal" href="#autowidgetsize"><span class="std std-ref">below</span></a>.</p></li>
<li><p><strong>pass_args_via_file</strong> (bool or <code class="docutils literal notranslate"><span class="pre">None</span></code>) – whether to use the <code class="xref std std-option docutils literal notranslate"><span class="pre">--file</span></code> option with a temporary
file in order to pass arguments to the <strong class="program">dialog</strong>
backend, instead of including them directly into the argument
list; using <code class="xref std std-option docutils literal notranslate"><span class="pre">--file</span></code> has the advantage of not exposing
the “real” arguments to other users through the process table.
With the default value (<code class="docutils literal notranslate"><span class="pre">None</span></code>), the option is enabled if
the <strong class="program">dialog</strong> version is recent enough to offer a
reliable <code class="xref std std-option docutils literal notranslate"><span class="pre">--file</span></code> implementation (i.e., 1.2-20150513
or later).</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>a <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> instance</p>
</dd>
</dl>
<p id="dialog-constructor-compat-arg">The officially supported <strong class="program">dialog</strong>-like program in
pythondialog is the well-known <a class="reference external" href="https://invisible-island.net/dialog/dialog.html">dialog</a> program written in C,
based on the <a class="reference external" href="https://invisible-island.net/ncurses/ncurses.html">ncurses</a> library.</p>
<p>If you want to use a different program such as <a class="reference external" href="http://xdialog.free.fr/">Xdialog</a>, you
should indicate the executable file name with the <em>dialog</em>
argument <strong>and</strong> the compatibility type that you think it
conforms to with the <em>compat</em> argument. Currently, <em>compat</em> can
be either <code class="docutils literal notranslate"><span class="pre">"dialog"</span></code> (for <strong class="program">dialog</strong>; this is the
default) or <code class="docutils literal notranslate"><span class="pre">"Xdialog"</span></code> (for, well, <strong class="program">Xdialog</strong>).</p>
<p>The <em>compat</em> argument allows me to cope with minor differences
in behaviour between the various programs implementing the
<strong class="program">dialog</strong> 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 <strong class="program">dialog</strong>. This is for the
benefit of pretty much everyone that relies on the
<strong class="program">dialog</strong> interface.</p>
<p>Notable exceptions:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="exceptions.html#dialog.ExecutableNotFound" title="dialog.ExecutableNotFound"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ExecutableNotFound</span></code></a></p></li>
<li><p><a class="reference internal" href="exceptions.html#dialog.PythonDialogOSError" title="dialog.PythonDialogOSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PythonDialogOSError</span></code></a></p></li>
<li><p><a class="reference internal" href="exceptions.html#dialog.UnableToRetrieveBackendVersion" title="dialog.UnableToRetrieveBackendVersion"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnableToRetrieveBackendVersion</span></code></a></p></li>
<li><p><a class="reference internal" href="exceptions.html#dialog.UnableToParseBackendVersion" title="dialog.UnableToParseBackendVersion"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnableToParseBackendVersion</span></code></a></p></li>
</ul>
</div></blockquote>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.1: </span>Support for the <em>autowidgetsize</em> parameter.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.3: </span>Support for the <em>pass_args_via_file</em> parameter.</p>
</div>
</dd></dl>
</dd></dl>
<p class="rubric" id="autowidgetsize">About the <em>autowidgetsize</em> option</p>
<p>The <em>autowidgetsize</em> option should be convenient in situations where figuring
out suitable widget size parameters is a burden, for instance when developing
little scripts that don’t need too much visual polishing, when a widget is
used to display data, the size of which is not easily predictable, or simply
when one doesn’t want to hardcode the widget size.</p>
<p>This option is implemented in the following way: for a given size parameter
(for instance, <em>width</em>) of a given widget, the default value in the
widget-producing method is now <code class="docutils literal notranslate"><span class="pre">None</span></code> if it previously had a non-zero
default. At runtime, if the value seen by the widget-producing method is not
<code class="docutils literal notranslate"><span class="pre">None</span></code>, it is used as is; on the contrary, if that value is <code class="docutils literal notranslate"><span class="pre">None</span></code>, it is
automatically replaced with:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">0</span></code> if the <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> instance has been initialized with
<em>autowidgetsize</em> set to <code class="docutils literal notranslate"><span class="pre">True</span></code>;</p></li>
<li><p>the old default otherwise, in order to preserve backward-comptability.</p></li>
</ul>
</div></blockquote>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ul class="simple">
<li><p>the <em>autowidgetsize</em> option is currently marked as experimental, please
give some feedback;</p></li>
<li><p>you may encounter questionable results if you only set one of the <em>width</em>
and <em>height</em> parameters to <code class="docutils literal notranslate"><span class="pre">0</span></code> for a given widget (seen in
<strong class="program">dialog</strong> 1.2-20140219).</p></li>
</ul>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>You should not explicitly pass <code class="docutils literal notranslate"><span class="pre">None</span></code> for a size parameter such as <em>width</em>
or <em>height</em>. If you want a fixed size, specify it directly (as an int);
otherwise, either use the <em>autowidgetsize</em> option or set the parameter to
<code class="docutils literal notranslate"><span class="pre">0</span></code> (e.g., <code class="docutils literal notranslate"><span class="pre">width=0</span></code>).</p>
</div>
</section>
<section id="passing-dialog-common-options">
<span id="id1"></span><h2>Passing <strong class="program">dialog</strong> “common options”<a class="headerlink" href="#passing-dialog-common-options" title="Permalink to this heading">¶</a></h2>
<p>Every widget method has a **kwargs argument allowing you to pass
<a class="reference internal" href="glossary.html#term-dialog-common-options"><span class="xref std std-term">common options</span></a> (see the <em class="manpage">dialog(1)</em>
manual page) to <strong class="program">dialog</strong> for this widget call. For instance, if <em>d</em>
is a <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> instance, you can write:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d</span><span class="o">.</span><span class="n">checklist</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">title</span><span class="o">=</span><span class="s2">"A Great Title"</span><span class="p">,</span> <span class="n">no_shadow</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>The <em>no_shadow</em> option is worth looking at:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>It is an option that takes no argument as far as <strong class="program">dialog</strong> is
concerned (unlike the <code class="xref std std-option docutils literal notranslate"><span class="pre">--title</span></code> option, for instance). When you
list it as a keyword argument, the option is really passed to
<strong class="program">dialog</strong> only if the value you gave it evaluates to <code class="docutils literal notranslate"><span class="pre">True</span></code> in
a boolean context. For instance, <code class="docutils literal notranslate"><span class="pre">no_shadow=True</span></code> will cause
<code class="xref std std-option docutils literal notranslate"><span class="pre">--no-shadow</span></code> to be passed to <strong class="program">dialog</strong> whereas
<code class="docutils literal notranslate"><span class="pre">no_shadow=False</span></code> will cause this option not to be passed to
<strong class="program">dialog</strong> at all.</p></li>
<li><p>It is an option that has a hyphen (<code class="docutils literal notranslate"><span class="pre">-</span></code>) in its name, which you must
change into an underscore (<code class="docutils literal notranslate"><span class="pre">_</span></code>) to pass it as a Python keyword
argument. Therefore, <code class="xref std std-option docutils literal notranslate"><span class="pre">--no-shadow</span></code> is passed by giving a
<code class="docutils literal notranslate"><span class="pre">no_shadow=True</span></code> keyword argument to <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> methods (the
leading two dashes are also consistently removed).</p></li>
</ol>
</div></blockquote>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When <a class="reference internal" href="#dialog.Dialog.__init__" title="dialog.Dialog.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog.__init__()</span></code></a> is called with
<code class="samp docutils literal notranslate"><em><span class="pre">pass_args_via_file</span></em><span class="pre">=True</span></code> (or without any explicit setting for this
option, and the pythondialog as well as <strong class="program">dialog</strong> versions are
recent enough so that the option is enabled by default), then the options
are not directly passed to <strong class="program">dialog</strong>. Instead, all options are
written to a temporary file which <strong class="program">dialog</strong> is pointed to via
<code class="xref std std-option docutils literal notranslate"><span class="pre">--file</span></code>. This ensures better confidentiality with respect to other
users of the same computer.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.14: </span>Support for the <em>default_button</em> and <em>no_tags</em> common options.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.0: </span>Proper support for the <em>extra_button</em>, <em>item_help</em> and <em>help_status</em> common
options.</p>
</div>
</section>
<section id="return-value-of-widget-producing-methods">
<h2>Return value of widget-producing methods<a class="headerlink" href="#return-value-of-widget-producing-methods" title="Permalink to this heading">¶</a></h2>
<p>Most <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> methods that create a widget (actually: all methods that
supervise the exit of a widget) return a value which fits into one of these
categories:</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>The return value is a <a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> (see below).</p></li>
<li><p>The return value is a sequence whose first element is a Dialog exit code
(the rest of the sequence being related to what the user entered in the
widget).</p></li>
</ol>
</div></blockquote>
<p>For instance, <a class="reference internal" href="widgets.html#dialog.Dialog.yesno" title="dialog.Dialog.yesno"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog.yesno()</span></code></a> returns a single Dialog exit code that will
typically be <a class="reference internal" href="#dialog.Dialog.OK" title="dialog.Dialog.OK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.OK</span></code></a> or <a class="reference internal" href="#dialog.Dialog.CANCEL" title="dialog.Dialog.CANCEL"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.CANCEL</span></code></a>, depending on the
button chosen by the user. However, <a class="reference internal" href="widgets.html#dialog.Dialog.checklist" title="dialog.Dialog.checklist"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog.checklist()</span></code></a> returns a tuple
of the form <code class="samp docutils literal notranslate"><span class="pre">(</span><em><span class="pre">code</span></em><span class="pre">,</span> <span class="pre">[</span><em><span class="pre">tag</span></em><span class="pre">,</span> <span class="pre">...])</span></code> whose first element is a Dialog
exit code and second element lists all tags for the entries selected by the
user.</p>
<section id="dialog-exit-code-high-level">
<span id="dialog-exit-code"></span><h3>“Dialog exit code” (high-level)<a class="headerlink" href="#dialog-exit-code-high-level" title="Permalink to this heading">¶</a></h3>
<p>A <em class="dfn">Dialog exit code</em>, or <em class="dfn">high-level exit code</em>, is a string
indicating how/why a widget-producing method ended. Most widgets return one of
the <a class="reference internal" href="glossary.html#term-standard-Dialog-exit-code"><span class="xref std std-term">standard Dialog exit codes</span></a>: <code class="docutils literal notranslate"><span class="pre">"ok"</span></code>,
<code class="docutils literal notranslate"><span class="pre">"cancel"</span></code>, <code class="docutils literal notranslate"><span class="pre">"esc"</span></code>, <code class="docutils literal notranslate"><span class="pre">"help"</span></code> and <code class="docutils literal notranslate"><span class="pre">"extra"</span></code>, respectively available as
<a class="reference internal" href="#dialog.Dialog.OK" title="dialog.Dialog.OK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.OK</span></code></a>, <a class="reference internal" href="#dialog.Dialog.CANCEL" title="dialog.Dialog.CANCEL"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.CANCEL</span></code></a>, <a class="reference internal" href="#dialog.Dialog.ESC" title="dialog.Dialog.ESC"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.ESC</span></code></a>,
<a class="reference internal" href="#dialog.Dialog.HELP" title="dialog.Dialog.HELP"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.HELP</span></code></a> and <a class="reference internal" href="#dialog.Dialog.EXTRA" title="dialog.Dialog.EXTRA"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.EXTRA</span></code></a>, <em>i.e.,</em> attributes of the
<a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> class. However, some widgets may return additional,
non-standard exit codes; for instance, the <a class="reference internal" href="widgets.html#dialog.Dialog.inputmenu" title="dialog.Dialog.inputmenu"><code class="xref py py-meth docutils literal notranslate"><span class="pre">inputmenu()</span></code></a> widget
may return <code class="docutils literal notranslate"><span class="pre">"accepted"</span></code> or <code class="docutils literal notranslate"><span class="pre">"renamed"</span></code> in addition to the standard Dialog
exit codes.</p>
<p>When getting a Dialog exit code from a widget-producing method, user code
should compare it with <a class="reference internal" href="#dialog.Dialog.OK" title="dialog.Dialog.OK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.OK</span></code></a> and friends (or equivalently, with
<code class="docutils literal notranslate"><span class="pre">"ok"</span></code> and friends) using the <code class="docutils literal notranslate"><span class="pre">==</span></code> operator. This allows to easily replace
<a class="reference internal" href="#dialog.Dialog.OK" title="dialog.Dialog.OK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.OK</span></code></a> and friends with objects that compare the same with <code class="docutils literal notranslate"><span class="pre">"ok"</span></code>
and <code class="docutils literal notranslate"><span class="pre">u"ok"</span></code> in Python 2, for instance.</p>
<p>The following attributes of the <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> class hold the <a class="reference internal" href="glossary.html#term-standard-Dialog-exit-code"><span class="xref std std-term">standard
Dialog exit codes</span></a>:</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.OK">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">OK</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'ok'</span></em><a class="headerlink" href="#dialog.Dialog.OK" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> corresponding to the <code class="docutils literal notranslate"><span class="pre">DIALOG_OK</span></code>
<a class="reference internal" href="glossary.html#term-dialog-exit-status"><span class="xref std std-term">dialog exit status</span></a></p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.CANCEL">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">CANCEL</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'cancel'</span></em><a class="headerlink" href="#dialog.Dialog.CANCEL" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> corresponding to the <code class="docutils literal notranslate"><span class="pre">DIALOG_CANCEL</span></code>
<a class="reference internal" href="glossary.html#term-dialog-exit-status"><span class="xref std std-term">dialog exit status</span></a></p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.ESC">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">ESC</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'esc'</span></em><a class="headerlink" href="#dialog.Dialog.ESC" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> corresponding to the <code class="docutils literal notranslate"><span class="pre">DIALOG_ESC</span></code>
<a class="reference internal" href="glossary.html#term-dialog-exit-status"><span class="xref std std-term">dialog exit status</span></a></p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.EXTRA">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">EXTRA</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'extra'</span></em><a class="headerlink" href="#dialog.Dialog.EXTRA" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> corresponding to the <code class="docutils literal notranslate"><span class="pre">DIALOG_EXTRA</span></code>
<a class="reference internal" href="glossary.html#term-dialog-exit-status"><span class="xref std std-term">dialog exit status</span></a></p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.HELP">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">HELP</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'help'</span></em><a class="headerlink" href="#dialog.Dialog.HELP" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> corresponding to the <code class="docutils literal notranslate"><span class="pre">DIALOG_HELP</span></code> and
<code class="docutils literal notranslate"><span class="pre">DIALOG_ITEM_HELP</span></code> <a class="reference internal" href="glossary.html#term-dialog-exit-status"><span class="xref std std-term">dialog exit statuses</span></a></p>
</dd></dl>
<p>The following attributes are obsolete and should not be used in pythondialog
3.0 and later:</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.DIALOG_OK">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">DIALOG_OK</span></span><a class="headerlink" href="#dialog.Dialog.DIALOG_OK" title="Permalink to this definition">¶</a></dt>
<dd><p>Obsolete property superseded by <a class="reference internal" href="#dialog.Dialog.OK" title="dialog.Dialog.OK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.OK</span></code></a> since version 3.0</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.DIALOG_CANCEL">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">DIALOG_CANCEL</span></span><a class="headerlink" href="#dialog.Dialog.DIALOG_CANCEL" title="Permalink to this definition">¶</a></dt>
<dd><p>Obsolete property superseded by <a class="reference internal" href="#dialog.Dialog.CANCEL" title="dialog.Dialog.CANCEL"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.CANCEL</span></code></a> since version 3.0</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.DIALOG_ESC">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">DIALOG_ESC</span></span><a class="headerlink" href="#dialog.Dialog.DIALOG_ESC" title="Permalink to this definition">¶</a></dt>
<dd><p>Obsolete property superseded by <a class="reference internal" href="#dialog.Dialog.ESC" title="dialog.Dialog.ESC"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.ESC</span></code></a> since version 3.0</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.DIALOG_EXTRA">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">DIALOG_EXTRA</span></span><a class="headerlink" href="#dialog.Dialog.DIALOG_EXTRA" title="Permalink to this definition">¶</a></dt>
<dd><p>Obsolete property superseded by <a class="reference internal" href="#dialog.Dialog.EXTRA" title="dialog.Dialog.EXTRA"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.EXTRA</span></code></a> since version 3.0</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.DIALOG_HELP">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">DIALOG_HELP</span></span><a class="headerlink" href="#dialog.Dialog.DIALOG_HELP" title="Permalink to this definition">¶</a></dt>
<dd><p>Obsolete property superseded by <a class="reference internal" href="#dialog.Dialog.HELP" title="dialog.Dialog.HELP"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.HELP</span></code></a> since version 3.0</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.DIALOG_ITEM_HELP">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">DIALOG_ITEM_HELP</span></span><a class="headerlink" href="#dialog.Dialog.DIALOG_ITEM_HELP" title="Permalink to this definition">¶</a></dt>
<dd><p>Obsolete property superseded by <a class="reference internal" href="#dialog.Dialog.HELP" title="dialog.Dialog.HELP"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.HELP</span></code></a> since version 3.0</p>
</dd></dl>
</section>
<section id="dialog-exit-status-low-level">
<span id="dialog-exit-status"></span><h3>“dialog exit status” (low-level)<a class="headerlink" href="#dialog-exit-status-low-level" title="Permalink to this heading">¶</a></h3>
<p>When returning from a widget call, the <a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> is normally
derived by pythondialog from an integer called <em class="dfn">dialog exit status</em>, or
<em class="dfn">low-level exit code</em>. This integer is returned by the <strong class="program">dialog</strong>
backend upon exit. The different possible values for the dialog exit status
are referred to as <code class="docutils literal notranslate"><span class="pre">DIALOG_OK</span></code>, <code class="docutils literal notranslate"><span class="pre">DIALOG_CANCEL</span></code>, <code class="docutils literal notranslate"><span class="pre">DIALOG_ESC</span></code>,
<code class="docutils literal notranslate"><span class="pre">DIALOG_ERROR</span></code>, <code class="docutils literal notranslate"><span class="pre">DIALOG_EXTRA</span></code>, <code class="docutils literal notranslate"><span class="pre">DIALOG_HELP</span></code> and <code class="docutils literal notranslate"><span class="pre">DIALOG_ITEM_HELP</span></code>
in the <em class="manpage">dialog(1)</em> manual page.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">DIALOG_HELP</span></code> and <code class="docutils literal notranslate"><span class="pre">DIALOG_ITEM_HELP</span></code> both map to <a class="reference internal" href="#dialog.Dialog.HELP" title="dialog.Dialog.HELP"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.HELP</span></code></a>
in pythondialog, because they both correspond to the same user action and
the difference brings no information that the caller does not already
have;</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">DIALOG_ERROR</span></code> has no counterpart as a <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> attribute,
because it is automatically translated into a <a class="reference internal" href="exceptions.html#dialog.DialogError" title="dialog.DialogError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DialogError</span></code></a> exception
when received.</p></li>
</ul>
</div>
<p>In pythondialog 2.x, the low-level exit codes were available as the
<code class="docutils literal notranslate"><span class="pre">DIALOG_OK</span></code>, <code class="docutils literal notranslate"><span class="pre">DIALOG_CANCEL</span></code>, etc. attributes of <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a>
instances. For compatibility, the <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> class has attributes of the
same names that are mapped to <a class="reference internal" href="#dialog.Dialog.OK" title="dialog.Dialog.OK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.OK</span></code></a>, <a class="reference internal" href="#dialog.Dialog.CANCEL" title="dialog.Dialog.CANCEL"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.CANCEL</span></code></a>, etc.,
but their use is deprecated as of pythondialog 3.0.</p>
</section>
</section>
<section id="adding-an-extra-button">
<h2>Adding an Extra button<a class="headerlink" href="#adding-an-extra-button" title="Permalink to this heading">¶</a></h2>
<p>With most widgets, it is possible to add a supplementary button called
<em class="dfn">Extra button</em>. To do that, you simply have to use <code class="docutils literal notranslate"><span class="pre">extra_button=True</span></code>
(keyword argument) in the widget call. By default, the button text is “Extra”,
but you can specify another string with the <em>extra_label</em> keyword argument.</p>
<p>When the widget exits, you know if the <span class="guilabel">Extra</span> button was pressed if
the <a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> is <a class="reference internal" href="#dialog.Dialog.EXTRA" title="dialog.Dialog.EXTRA"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.EXTRA</span></code></a> (<code class="docutils literal notranslate"><span class="pre">"extra"</span></code>). Normally,
the rest of the return value is the same as if the widget had been closed with
<span class="guilabel">OK</span>. Therefore, if the widget normally returns a list of three
integers, for instance, you can expect to get the same information if
<span class="guilabel">Extra</span> is pressed instead of <span class="guilabel">OK</span>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This feature can be particularly useful in combination with the <em>yes_label</em>,
<em>no_label</em>, <em>help_button</em> and <em>help_label</em> <a class="reference internal" href="glossary.html#term-dialog-common-options"><span class="xref std std-term">common options</span></a> to provide a completely different set of buttons than the
default for a given widget.</p>
</div>
</section>
<section id="providing-on-line-help-facilities">
<h2>Providing on-line help facilities<a class="headerlink" href="#providing-on-line-help-facilities" title="Permalink to this heading">¶</a></h2>
<p>With most <strong class="program">dialog</strong> widgets, it is possible to provide online help to
the final user. At the time of this writing (October 2014), there are three
main options governing these help facilities in the <strong class="program">dialog</strong> backend:
<code class="xref std std-option docutils literal notranslate"><span class="pre">--help-button</span></code>, <code class="xref std std-option docutils literal notranslate"><span class="pre">--item-help</span></code> and <code class="xref std std-option docutils literal notranslate"><span class="pre">--help-status</span></code>.
Since <strong class="program">dialog</strong> 1.2-20130902, there is also <code class="xref std std-option docutils literal notranslate"><span class="pre">--help-tags</span></code> that
modifies the way <code class="xref std std-option docutils literal notranslate"><span class="pre">--item-help</span></code> works. As explained previously
(<a class="reference internal" href="#passing-dialog-common-options"><span class="std std-ref">Passing dialog “common options”</span></a>), in order to use these options in
pythondialog, you can pass the <em>help_button</em>, <em>item_help</em>, <em>help_status</em> and
<em>help_tags</em> keyword arguments to <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> widget-producing methods.</p>
<section id="adding-a-help-button">
<h3>Adding a <span class="guilabel">Help</span> button<a class="headerlink" href="#adding-a-help-button" title="Permalink to this heading">¶</a></h3>
<p>In order to provide a <span class="guilabel">Help</span> button in addition to the normal
buttons of a widget, you can pass <code class="docutils literal notranslate"><span class="pre">help_button=True</span></code> (keyword argument) to
the corresponding <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> method. For instance, if <em>d</em> is a
<a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> instance, you can write:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">code</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">yesno</span><span class="p">(</span><span class="s2">"<text>"</span><span class="p">,</span> <span class="n">height</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">width</span><span class="o">=</span><span class="mi">40</span><span class="p">,</span> <span class="n">help_button</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>or:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">code</span><span class="p">,</span> <span class="n">answer</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">inputbox</span><span class="p">(</span><span class="s2">"<text>"</span><span class="p">,</span> <span class="n">init</span><span class="o">=</span><span class="s2">"<init>"</span><span class="p">,</span>
<span class="n">help_button</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>When the method returns, the <a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> is <a class="reference internal" href="#dialog.Dialog.HELP" title="dialog.Dialog.HELP"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.HELP</span></code></a>
(i.e., the string <code class="docutils literal notranslate"><span class="pre">"help"</span></code>) if the user pressed the <span class="guilabel">Help</span> button.
Apart from that, it works exactly as if <code class="docutils literal notranslate"><span class="pre">help_button=True</span></code> had not been
used. In the last example, if the user presses the <span class="guilabel">Help</span> button,
<em>answer</em> will contain the user input, just as if <span class="guilabel">OK</span> had been
pressed. Similarly, if you write:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">code</span><span class="p">,</span> <span class="n">t</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">checklist</span><span class="p">(</span>
<span class="s2">"<text>"</span><span class="p">,</span> <span class="n">height</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">width</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">list_height</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="n">choices</span><span class="o">=</span><span class="p">[</span> <span class="p">(</span><span class="s2">"Tag 1"</span><span class="p">,</span> <span class="s2">"Item 1"</span><span class="p">,</span> <span class="kc">False</span><span class="p">),</span>
<span class="p">(</span><span class="s2">"Tag 2"</span><span class="p">,</span> <span class="s2">"Item 2"</span><span class="p">,</span> <span class="kc">True</span><span class="p">),</span>
<span class="p">(</span><span class="s2">"Tag 3"</span><span class="p">,</span> <span class="s2">"Item 3"</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span> <span class="p">],</span>
<span class="n">help_button</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>and find that <code class="docutils literal notranslate"><span class="pre">code</span> <span class="pre">==</span> <span class="pre">Dialog.HELP</span></code>, then <em>t</em> contains the tag string for
the highlighted item when the <span class="guilabel">Help</span> button was pressed.</p>
<p>Finally, note that it is possible to choose the text written on the
<span class="guilabel">Help</span> button by supplying a string as the <em>help_label</em> keyword
argument.</p>
</section>
<section id="providing-inline-per-item-help">
<span id="id2"></span><h3>Providing inline per-item help<a class="headerlink" href="#providing-inline-per-item-help" title="Permalink to this heading">¶</a></h3>
<p>In addition to, or instead of the <span class="guilabel">Help</span> button, you can provide
<em class="dfn">item-specific help</em> that is normally displayed at the bottom of the
widget. This can be done by passing the <code class="docutils literal notranslate"><span class="pre">item_help=True</span></code> keyword argument to
the widget-producing method and by including the item-specific help strings in
the appropriate argument.</p>
<p>For widgets where item-specific help makes sense (i.e., there are several
elements that can be highlighted), there is usually a parameter, often called
<em>elements</em>, <em>choices</em>, <em>nodes</em>…, that must be provided as an iterable
describing the various lines/items/nodes/… that can be highlighted in the
widget. When <code class="docutils literal notranslate"><span class="pre">item_help=True</span></code> is passed, every element of this iterable must
be completed with a string which is the <em class="dfn">item-help string</em> of the element
(using <em class="manpage">dialog(1)</em> terminology). For instance, the following call
with no inline per-item help support:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">code</span><span class="p">,</span> <span class="n">t</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">checklist</span><span class="p">(</span>
<span class="s2">"<text>"</span><span class="p">,</span> <span class="n">height</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">width</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">list_height</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="n">choices</span><span class="o">=</span><span class="p">[</span> <span class="p">(</span><span class="s2">"Tag 1"</span><span class="p">,</span> <span class="s2">"Item 1"</span><span class="p">,</span> <span class="kc">False</span><span class="p">),</span>
<span class="p">(</span><span class="s2">"Tag 2"</span><span class="p">,</span> <span class="s2">"Item 2"</span><span class="p">,</span> <span class="kc">True</span><span class="p">),</span>
<span class="p">(</span><span class="s2">"Tag 3"</span><span class="p">,</span> <span class="s2">"Item 3"</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span> <span class="p">],</span>
<span class="n">help_button</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>can be altered this way to provide inline item-specific help:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">code</span><span class="p">,</span> <span class="n">t</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">checklist</span><span class="p">(</span>
<span class="s2">"<text>"</span><span class="p">,</span> <span class="n">height</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">width</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">list_height</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="n">choices</span><span class="o">=</span><span class="p">[</span> <span class="p">(</span><span class="s2">"Tag 1"</span><span class="p">,</span> <span class="s2">"Item 1"</span><span class="p">,</span> <span class="kc">False</span><span class="p">,</span> <span class="s2">"Help 1"</span><span class="p">),</span>
<span class="p">(</span><span class="s2">"Tag 2"</span><span class="p">,</span> <span class="s2">"Item 2"</span><span class="p">,</span> <span class="kc">True</span><span class="p">,</span> <span class="s2">"Help 2"</span><span class="p">),</span>
<span class="p">(</span><span class="s2">"Tag 3"</span><span class="p">,</span> <span class="s2">"Item 3"</span><span class="p">,</span> <span class="kc">True</span><span class="p">,</span> <span class="s2">"Help 3"</span><span class="p">)</span> <span class="p">],</span>
<span class="n">help_button</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">item_help</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">help_tags</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>With this modification, the item-help string for the highlighted item is
displayed in the bottom line of the screen and updated as the user highlights
other items.</p>
<p>If you don’t want a <span class="guilabel">Help</span> button, just use <code class="docutils literal notranslate"><span class="pre">item_help=True</span></code>
without <code class="docutils literal notranslate"><span class="pre">help_button=True</span></code> (<em>help_tags</em> doesn’t matter in this case). Then,
you have the inline help at the bottom of the screen, and the following
discussion about the return value can be ignored.</p>
<p>If the user chooses the <span class="guilabel">Help</span> button, <em>code</em> will be equal to
<a class="reference internal" href="#dialog.Dialog.HELP" title="dialog.Dialog.HELP"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.HELP</span></code></a> (<code class="docutils literal notranslate"><span class="pre">"help"</span></code>) and <em>t</em> will contain the tag string
corresponding to the highlighted item when the <span class="guilabel">Help</span> button was
pressed (<code class="docutils literal notranslate"><span class="pre">"Tag</span> <span class="pre">1/2/3"</span></code> in the example). This is because of the <em>help_tags</em>
option; without it (or with <code class="docutils literal notranslate"><span class="pre">help_tags=False</span></code>), <em>t</em> would have contained the
<a class="reference internal" href="glossary.html#term-item-help-string"><span class="xref std std-term">item-help string</span></a> of the highlighted choice (<code class="docutils literal notranslate"><span class="pre">"Help</span> <span class="pre">1/2/3"</span></code> in the
example).</p>
<p>If you remember what was said earlier, if <code class="docutils literal notranslate"><span class="pre">item_help=True</span></code> had not been used
in the previous example, <em>t</em> would still contain the tag of the highlighted
choice if the user closed the widget with the <span class="guilabel">Help</span> button. This is
the same as when using <code class="docutils literal notranslate"><span class="pre">item_help=True</span></code> in combination with
<code class="docutils literal notranslate"><span class="pre">help_tags=True</span></code>; however, you would get the <a class="reference internal" href="glossary.html#term-item-help-string"><span class="xref std std-term">item-help string</span></a>
instead if <em>help_tags</em> were <code class="docutils literal notranslate"><span class="pre">False</span></code> (which is the default, as in the
<strong class="program">dialog</strong> backend, and in order to preserve compatibility with the
<a class="reference internal" href="widgets.html#dialog.Dialog.menu" title="dialog.Dialog.menu"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog.menu()</span></code></a> implementation that is several years old).</p>
<p>Therefore, I recommend for consistency to use <code class="docutils literal notranslate"><span class="pre">help_tags=True</span></code> whenever
possible when specifying <code class="docutils literal notranslate"><span class="pre">item_help=True</span></code>. This makes <code class="docutils literal notranslate"><span class="pre">"--help-tags"</span></code> a
good candidate for use with <a class="reference internal" href="#dialog.Dialog.add_persistent_args" title="dialog.Dialog.add_persistent_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog.add_persistent_args()</span></code></a> to avoid
repeating it over and over. However, there are two cases where
<code class="docutils literal notranslate"><span class="pre">help_tags=True</span></code> cannot be used:</p>
<blockquote>
<div><ul class="simple">
<li><p>when the version of the <strong class="program">dialog</strong> backend is lower than
1.2-20130902 (the <code class="xref std std-option docutils literal notranslate"><span class="pre">--help-tags</span></code> option was added in this version);</p></li>
<li><p>when using empty or otherwise identical tags for presentation purposes
(unless you don’t need to tell which element was highlighted when the
<span class="guilabel">Help</span> button was pressed, in which case it doesn’t matter to be
unable to discriminate between the tags).</p></li>
</ul>
</div></blockquote>
</section>
<section id="getting-the-widget-status-before-the-help-button-was-pressed">
<h3>Getting the widget status before the <span class="guilabel">Help</span> button was pressed<a class="headerlink" href="#getting-the-widget-status-before-the-help-button-was-pressed" title="Permalink to this heading">¶</a></h3>
<p>Typically, when the user chooses <span class="guilabel">Help</span> in a widget, the application
will display a dialog box such as <a class="reference internal" href="widgets.html#dialog.Dialog.textbox" title="dialog.Dialog.textbox"><code class="xref py py-meth docutils literal notranslate"><span class="pre">textbox()</span></code></a>,
<a class="reference internal" href="widgets.html#dialog.Dialog.msgbox" title="dialog.Dialog.msgbox"><code class="xref py py-meth docutils literal notranslate"><span class="pre">msgbox()</span></code></a> or <a class="reference internal" href="widgets.html#dialog.Dialog.scrollbox" title="dialog.Dialog.scrollbox"><code class="xref py py-meth docutils literal notranslate"><span class="pre">scrollbox()</span></code></a> and redisplay the original
widget afterwards. For simple widgets such as <a class="reference internal" href="widgets.html#dialog.Dialog.inputbox" title="dialog.Dialog.inputbox"><code class="xref py py-meth docutils literal notranslate"><span class="pre">inputbox()</span></code></a>, when
the <a class="reference internal" href="glossary.html#term-Dialog-exit-code"><span class="xref std std-term">Dialog exit code</span></a> is equal to <a class="reference internal" href="#dialog.Dialog.HELP" title="dialog.Dialog.HELP"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.HELP</span></code></a>, the return value
contains enough information to redisplay the widget in the same state it had
when <span class="guilabel">Help</span> was chosen. However, for more complex widgets such as
<a class="reference internal" href="widgets.html#dialog.Dialog.radiolist" title="dialog.Dialog.radiolist"><code class="xref py py-meth docutils literal notranslate"><span class="pre">radiolist()</span></code></a> (resp. <a class="reference internal" href="widgets.html#dialog.Dialog.checklist" title="dialog.Dialog.checklist"><code class="xref py py-meth docutils literal notranslate"><span class="pre">checklist()</span></code></a>, or
<a class="reference internal" href="widgets.html#dialog.Dialog.form" title="dialog.Dialog.form"><code class="xref py py-meth docutils literal notranslate"><span class="pre">form()</span></code></a> and its derivatives), knowing the highlighted item is not
enough to restore the widget state after processing the help request: one
needs to know the checked item (resp. list of checked items, or form contents).</p>
<p>This is where the <em>help_status</em> keyword argument becomes useful. Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">code</span><span class="p">,</span> <span class="n">t</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">checklist</span><span class="p">(</span>
<span class="s2">"<text>"</span><span class="p">,</span> <span class="n">height</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">width</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">list_height</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span>
<span class="n">choices</span><span class="o">=</span><span class="p">[</span> <span class="p">(</span><span class="s2">"Tag 1"</span><span class="p">,</span> <span class="s2">"Item 1"</span><span class="p">,</span> <span class="kc">False</span><span class="p">),</span>
<span class="p">(</span><span class="s2">"Tag 2"</span><span class="p">,</span> <span class="s2">"Item 2"</span><span class="p">,</span> <span class="kc">True</span><span class="p">),</span>
<span class="p">(</span><span class="s2">"Tag 3"</span><span class="p">,</span> <span class="s2">"Item 3"</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span> <span class="p">],</span>
<span class="n">help_button</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">help_status</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>When <span class="guilabel">Help</span> is chosen, <code class="docutils literal notranslate"><span class="pre">code</span> <span class="pre">==</span> <span class="pre">Dialog.HELP</span></code> and <em>t</em> is a tuple of
the form <code class="samp docutils literal notranslate"><span class="pre">(</span><em><span class="pre">tag</span></em><span class="pre">,</span> <em><span class="pre">selected_tags</span></em><span class="pre">,</span> <em><span class="pre">choices</span></em><span class="pre">)</span></code> where:</p>
<blockquote>
<div><ul class="simple">
<li><p><em>tag</em> gives the tag string of the highlighted item (which would be the
value of <em>t</em> if <em>help_status</em> were set to <code class="docutils literal notranslate"><span class="pre">False</span></code>);</p></li>
<li><p><em>selected_tags</em> is the… list of selected tags (note that highlighting
and selecting an item are different things!);</p></li>
<li><p><em>choices</em> is a list built from the original <em>choices</em> argument of the
<a class="reference internal" href="widgets.html#dialog.Dialog.checklist" title="dialog.Dialog.checklist"><code class="xref py py-meth docutils literal notranslate"><span class="pre">checklist()</span></code></a> call and from the list of selected tags, that
can be used as is to create a widget with the same items and selection
state as the original widget had when <span class="guilabel">Help</span> was chosen.</p></li>
</ul>
</div></blockquote>
<p>Normally, pythondialog should always provide something similar to the last
item in the previous example in order to make it as easy as possible to
redisplay the widget in the appropriate state. To know precisely what is
returned with <code class="docutils literal notranslate"><span class="pre">help_status=True</span></code>, the best way is probably to experiment
and/or read the code (by the way, there are many examples of widgets with
various combinations of the <em>help_button</em>, <em>item_help</em> and <em>help_status</em>
keyword arguments in the demo).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The various options related to help support are not mutually exclusive; they
may be used together to provide good help support.</p>
</div>
<p>It is also worth noting that the documentation of the various widget-producing
methods is written, in most cases, under the assumption that the widget was
closed “normally” (typically, with the <span class="guilabel">OK</span> or <span class="guilabel">Extra</span>
button). For instance, a widget documentation may state that the method
returns a tuple of the form <code class="samp docutils literal notranslate"><span class="pre">(</span><em><span class="pre">code</span></em><span class="pre">,</span> <em><span class="pre">tag</span></em><span class="pre">)</span></code> where <em>tag</em> is …, but
actually, if using <code class="docutils literal notranslate"><span class="pre">item_help=True</span></code> with <code class="docutils literal notranslate"><span class="pre">help_tags=False</span></code>, the <em>tag</em> may
very well be an <a class="reference internal" href="glossary.html#term-item-help-string"><span class="xref std std-term">item-help string</span></a>, and if using <code class="docutils literal notranslate"><span class="pre">help_status=True</span></code>,
it is likely to be a structured object such as a tuple or list. Of course,
handling all these possible variations for all widgets would be a tedious task
and would probably significantly degrade the readability of said
documentation.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.0: </span>Proper support for the <em>item_help</em> and <em>help_status</em> common options.</p>
</div>
</section>
</section>
<section id="screen-related-methods">
<h2>Screen-related methods<a class="headerlink" href="#screen-related-methods" title="Permalink to this heading">¶</a></h2>
<p>Getting the terminal size:</p>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.maxsize">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">maxsize</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.maxsize"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.maxsize" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the maximum size of dialog boxes.</p>
<p>If the exit status from the backend corresponds to
<a class="reference internal" href="#dialog.Dialog.OK" title="dialog.Dialog.OK"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.OK</span></code></a>, return a <code class="samp docutils literal notranslate"><span class="pre">(</span><em><span class="pre">lines</span></em><span class="pre">,</span> <em><span class="pre">cols</span></em><span class="pre">)</span></code> tuple of
integers; otherwise, return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<p>If you want to obtain the number of lines and columns of the
terminal, you should call this method with
<code class="docutils literal notranslate"><span class="pre">use_persistent_args=False</span></code>, because <strong class="program">dialog</strong> options
such as <code class="xref std std-option docutils literal notranslate"><span class="pre">--backtitle</span></code> modify the returned values.</p>
<p>Notable exceptions:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="exceptions.html#dialog.PythonDialogReModuleError" title="dialog.PythonDialogReModuleError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PythonDialogReModuleError</span></code></a></p></li>
<li><p>any exception raised by <a class="reference internal" href="internals.html#dialog.Dialog._perform" title="dialog.Dialog._perform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog._perform()</span></code></a></p></li>
</ul>
</div></blockquote>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.12.</span></p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.set_background_title">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">set_background_title</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">text</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.set_background_title"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.set_background_title" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the background title for dialog.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>text</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – string to use as background title</p>
</dd>
</dl>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.13.</span></p>
</div>
</dd></dl>
<section id="obsolete-methods">
<h3>Obsolete methods<a class="headerlink" href="#obsolete-methods" title="Permalink to this heading">¶</a></h3>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.setBackgroundTitle">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">setBackgroundTitle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">text</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.setBackgroundTitle"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.setBackgroundTitle" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the background title for <strong class="program">dialog</strong>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>text</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/stdtypes.html#str" title="(in Python v3.11)"><em>str</em></a>) – background title to use behind widgets</p>
</dd>
</dl>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 2.03: </span>Use <a class="reference internal" href="#dialog.Dialog.set_background_title" title="dialog.Dialog.set_background_title"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_background_title()</span></code></a> instead.</p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.clear">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">clear</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.clear"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the screen.</p>
<p>Equivalent to the <code class="xref std std-option docutils literal notranslate"><span class="pre">--clear</span></code> option of <strong class="program">dialog</strong>.</p>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 2.03: </span>You may use the <em class="manpage">clear(1)</em> program instead.
cf. <code class="docutils literal notranslate"><span class="pre">clear_screen()</span></code> in <code class="file docutils literal notranslate"><span class="pre">examples/demo.py</span></code> for an
example.</p>
</div>
</dd></dl>
</section>
</section>
<section id="checking-the-versions-of-pythondialog-and-its-backend">
<h2>Checking the versions of pythondialog and its backend<a class="headerlink" href="#checking-the-versions-of-pythondialog-and-its-backend" title="Permalink to this heading">¶</a></h2>
<section id="version-of-pythondialog">
<h3>Version of pythondialog<a class="headerlink" href="#version-of-pythondialog" title="Permalink to this heading">¶</a></h3>
<dl class="py class">
<dt class="sig sig-object py" id="dialog.VersionInfo">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dialog.</span></span><span class="sig-name descname"><span class="pre">VersionInfo</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">major</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">minor</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">micro</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">releasesuffix</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#VersionInfo"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.VersionInfo" title="Permalink to this definition">¶</a></dt>
<dd><p>Class used to represent the version of pythondialog.</p>
<p>This class is based on <a class="reference external" href="file:///usr/share/doc/python3/html/library/collections.html#collections.namedtuple" title="(in Python v3.11)"><code class="xref py py-func docutils literal notranslate"><span class="pre">collections.namedtuple()</span></code></a> and has the
following field names: <code class="docutils literal notranslate"><span class="pre">major</span></code>, <code class="docutils literal notranslate"><span class="pre">minor</span></code>, <code class="docutils literal notranslate"><span class="pre">micro</span></code>,
<code class="docutils literal notranslate"><span class="pre">releasesuffix</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.14.</span></p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.VersionInfo.__repr__">
<span class="sig-name descname"><span class="pre">__repr__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#VersionInfo.__repr__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.VersionInfo.__repr__" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a nicely formatted representation string</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.VersionInfo.__str__">
<span class="sig-name descname"><span class="pre">__str__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#VersionInfo.__str__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.VersionInfo.__str__" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a string representation of the version.</p>
</dd></dl>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="dialog.version_info">
<span class="sig-prename descclassname"><span class="pre">dialog.</span></span><span class="sig-name descname"><span class="pre">version_info</span></span><a class="headerlink" href="#dialog.version_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Version of pythondialog as a <a class="reference internal" href="#dialog.VersionInfo" title="dialog.VersionInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">VersionInfo</span></code></a> instance.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.14.</span></p>
</div>
</dd></dl>
<dl class="py data">
<dt class="sig sig-object py" id="dialog.__version__">
<span class="sig-prename descclassname"><span class="pre">dialog.</span></span><span class="sig-name descname"><span class="pre">__version__</span></span><a class="headerlink" href="#dialog.__version__" title="Permalink to this definition">¶</a></dt>
<dd><p>Version of pythondialog as a string.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.12.</span></p>
</div>
</dd></dl>
</section>
<section id="version-of-the-backend">
<h3>Version of the backend<a class="headerlink" href="#version-of-the-backend" title="Permalink to this heading">¶</a></h3>
<p>The <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> constructor retrieves the version string of the
<strong class="program">dialog</strong> backend and stores it as an instance of a
<code class="xref py py-class docutils literal notranslate"><span class="pre">BackendVersion</span></code> subclass into the
<a class="reference internal" href="#dialog.Dialog.cached_backend_version" title="dialog.Dialog.cached_backend_version"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.cached_backend_version</span></code></a> attribute. This allows doing things such
as (<em>d</em> being a <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> instance):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">d</span><span class="o">.</span><span class="n">compat</span> <span class="o">==</span> <span class="s2">"dialog"</span> <span class="ow">and</span> \
<span class="n">d</span><span class="o">.</span><span class="n">cached_backend_version</span> <span class="o">>=</span> <span class="n">DialogBackendVersion</span><span class="p">(</span><span class="s2">"1.2-20130902"</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>in a reliable way, allowing to fix the parsing and comparison algorithms right
in the appropriate <code class="xref py py-class docutils literal notranslate"><span class="pre">BackendVersion</span></code> subclass, should the
<strong class="program">dialog</strong>-like backend versioning scheme change in unforeseen ways.</p>
<p>As <strong class="program">Xdialog</strong> seems to be dead and not to support
<code class="xref std std-option docutils literal notranslate"><span class="pre">--print-version</span></code>, the <a class="reference internal" href="#dialog.Dialog.cached_backend_version" title="dialog.Dialog.cached_backend_version"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.cached_backend_version</span></code></a> attribute
is set to <code class="docutils literal notranslate"><span class="pre">None</span></code> in <strong class="program">Xdialog</strong>-compatibility mode (2013-09-12).
Should this ever change, one should define an <code class="xref py py-class docutils literal notranslate"><span class="pre">XDialogBackendVersion</span></code>
class to handle the particularities of the <strong class="program">Xdialog</strong> versioning
scheme.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="dialog.Dialog.cached_backend_version">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">cached_backend_version</span></span><a class="headerlink" href="#dialog.Dialog.cached_backend_version" title="Permalink to this definition">¶</a></dt>
<dd><p>Instance of a <code class="xref py py-class docutils literal notranslate"><span class="pre">BackendVersion</span></code> subclass; it is initialized by the
<a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> constructor and used to store the backend version, avoiding
the need to repeatedly call <code class="docutils literal notranslate"><span class="pre">dialog</span> <span class="pre">--print-version</span></code> or a similar
command, depending on the backend.</p>
<p>When using the <strong class="program">dialog</strong> backend,
<a class="reference internal" href="#dialog.Dialog.cached_backend_version" title="dialog.Dialog.cached_backend_version"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Dialog.cached_backend_version</span></code></a> is a <a class="reference internal" href="DialogBackendVersion.html#dialog.DialogBackendVersion" title="dialog.DialogBackendVersion"><code class="xref py py-class docutils literal notranslate"><span class="pre">DialogBackendVersion</span></code></a>
instance.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.backend_version">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">backend_version</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.backend_version"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.backend_version" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the version of the <strong class="program">dialog</strong>-like program (backend).</p>
<p>If the version of the <strong class="program">dialog</strong>-like program can be
retrieved, return it as a string; otherwise, raise
<a class="reference internal" href="exceptions.html#dialog.UnableToRetrieveBackendVersion" title="dialog.UnableToRetrieveBackendVersion"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnableToRetrieveBackendVersion</span></code></a>.</p>
<p>This version is not to be confused with the pythondialog
version.</p>
<p>In most cases, you should rather use the
<a class="reference internal" href="#dialog.Dialog.cached_backend_version" title="dialog.Dialog.cached_backend_version"><code class="xref py py-attr docutils literal notranslate"><span class="pre">cached_backend_version</span></code></a> attribute of <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a>
instances, because:</p>
<blockquote>
<div><ul class="simple">
<li><p>it avoids calling the backend every time one needs the
version;</p></li>
<li><p>it is a <code class="xref py py-class docutils literal notranslate"><span class="pre">BackendVersion</span></code> instance (or instance of a
subclass) that allows easy and reliable comparisons between
versions;</p></li>
<li><p>the version string corresponding to a
<code class="xref py py-class docutils literal notranslate"><span class="pre">BackendVersion</span></code> instance (or instance of a subclass)
can be obtained with <code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code>.</p></li>
</ul>
</div></blockquote>
<p>Notable exceptions:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="exceptions.html#dialog.UnableToRetrieveBackendVersion" title="dialog.UnableToRetrieveBackendVersion"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnableToRetrieveBackendVersion</span></code></a></p></li>
<li><p><a class="reference internal" href="exceptions.html#dialog.PythonDialogReModuleError" title="dialog.PythonDialogReModuleError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PythonDialogReModuleError</span></code></a></p></li>
<li><p>any exception raised by <a class="reference internal" href="internals.html#dialog.Dialog._perform" title="dialog.Dialog._perform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog._perform()</span></code></a></p></li>
</ul>
</div></blockquote>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.12.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 2.14: </span>Raise <a class="reference internal" href="exceptions.html#dialog.UnableToRetrieveBackendVersion" title="dialog.UnableToRetrieveBackendVersion"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnableToRetrieveBackendVersion</span></code></a> instead of
returning <code class="docutils literal notranslate"><span class="pre">None</span></code> when the version of the
<strong class="program">dialog</strong>-like program can’t be retrieved.</p>
</div>
</dd></dl>
</section>
</section>
<section id="enabling-debug-facilities">
<h2>Enabling debug facilities<a class="headerlink" href="#enabling-debug-facilities" title="Permalink to this heading">¶</a></h2>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.setup_debug">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">setup_debug</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">enable</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">file</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">always_flush</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">expand_file_opt</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.setup_debug"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.setup_debug" title="Permalink to this definition">¶</a></dt>
<dd><p>Setup the debugging parameters.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>enable</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/functions.html#bool" title="(in Python v3.11)"><em>bool</em></a>) – whether to enable or disable debugging</p></li>
<li><p><strong>file</strong> (<em>file</em>) – where to write debugging information</p></li>
<li><p><strong>always_flush</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/functions.html#bool" title="(in Python v3.11)"><em>bool</em></a>) – whether to call <code class="xref py py-meth docutils literal notranslate"><span class="pre">file.flush()</span></code>
after each command written</p></li>
<li><p><strong>expand_file_opt</strong> (<a class="reference external" href="file:///usr/share/doc/python3/html/library/functions.html#bool" title="(in Python v3.11)"><em>bool</em></a>) – when <a class="reference internal" href="#dialog.Dialog.__init__" title="dialog.Dialog.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog.__init__()</span></code></a> has been called with
<code class="samp docutils literal notranslate"><em><span class="pre">pass_args_via_file</span></em><span class="pre">=True</span></code>, this option causes the
<code class="xref std std-option docutils literal notranslate"><span class="pre">--file</span></code> options that would normally be written to
<em>file</em> to be expanded, yielding a similar result to what would
be obtained with <code class="samp docutils literal notranslate"><em><span class="pre">pass_args_via_file</span></em><span class="pre">=False</span></code> (but
contrary to <code class="samp docutils literal notranslate"><em><span class="pre">pass_args_via_file</span></em><span class="pre">=False</span></code>, this only
affects <em>file</em>, not the actual <strong class="program">dialog</strong> calls). This
is useful, for instance, for copying some of the
<strong class="program">dialog</strong> commands into a shell.</p></li>
</ul>
</dd>
</dl>
<p>When <em>enable</em> is true, all <strong class="program">dialog</strong> commands are
written to <em>file</em> using POSIX shell syntax. In this case, you’ll
probably want to use either <code class="samp docutils literal notranslate"><em><span class="pre">expand_file_opt</span></em><span class="pre">=True</span></code> in
this method or <code class="samp docutils literal notranslate"><em><span class="pre">pass_args_via_file</span></em><span class="pre">=False</span></code> in
<a class="reference internal" href="#dialog.Dialog.__init__" title="dialog.Dialog.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog.__init__()</span></code></a>, otherwise you’ll mostly see
<strong class="program">dialog</strong> calls containing only one <code class="xref std std-option docutils literal notranslate"><span class="pre">--file</span></code>
option followed by a path to a temporary file.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.12.</span></p>
</div>
<div class="versionadded">
<p><span class="versionmodified added">New in version 3.3: </span>Support for the <em>expand_file_opt</em> parameter.</p>
</div>
</dd></dl>
</section>
<section id="miscellaneous-methods">
<h2>Miscellaneous methods<a class="headerlink" href="#miscellaneous-methods" title="Permalink to this heading">¶</a></h2>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.add_persistent_args">
<span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">add_persistent_args</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.add_persistent_args"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.add_persistent_args" title="Permalink to this definition">¶</a></dt>
<dd><p>Add arguments to use for every subsequent dialog call.</p>
<p>This method cannot guess which elements of <em>args</em> are dialog
options (such as <code class="docutils literal notranslate"><span class="pre">--title</span></code>) and which are not (for instance,
you might want to use <code class="docutils literal notranslate"><span class="pre">--title</span></code> or even <code class="docutils literal notranslate"><span class="pre">--</span></code> as an argument
to a dialog option). Therefore, this method does not perform any
kind of <a class="reference internal" href="glossary.html#term-dash-escaping"><span class="xref std std-term">dash escaping</span></a>; you have to do it yourself.
<a class="reference internal" href="#dialog.Dialog.dash_escape" title="dialog.Dialog.dash_escape"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dash_escape()</span></code></a> and <a class="reference internal" href="#dialog.Dialog.dash_escape_nf" title="dialog.Dialog.dash_escape_nf"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dash_escape_nf()</span></code></a> may be useful for
this purpose.</p>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When <a class="reference internal" href="#dialog.Dialog.__init__" title="dialog.Dialog.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Dialog.__init__()</span></code></a> is called with
<code class="samp docutils literal notranslate"><em><span class="pre">pass_args_via_file</span></em><span class="pre">=True</span></code> (or without any explicit setting for this
option, and the pythondialog as well as <strong class="program">dialog</strong> versions are
recent enough so that the option is enabled by default), then the arguments
are not directly passed to <strong class="program">dialog</strong>. Instead, all arguments are
written to a temporary file which <strong class="program">dialog</strong> is pointed to via
<code class="xref std std-option docutils literal notranslate"><span class="pre">--file</span></code>. This ensures better confidentiality with respect to other
users of the same computer.</p>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.dash_escape">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">dash_escape</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.dash_escape"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.dash_escape" title="Permalink to this definition">¶</a></dt>
<dd><p>Escape all elements of <em>args</em> that need escaping for <strong class="program">dialog</strong>.</p>
<p><em>args</em> may be any sequence and is not modified by this method.
Return a new list where every element that needs escaping has
been escaped.</p>
<p>An element needs escaping when it starts with two ASCII hyphens
(<code class="docutils literal notranslate"><span class="pre">--</span></code>). Escaping consists in prepending an element composed of
two ASCII hyphens, i.e., the string <code class="docutils literal notranslate"><span class="pre">'--'</span></code>.</p>
<p>All high-level <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> methods automatically perform
<a class="reference internal" href="glossary.html#term-dash-escaping"><span class="xref std std-term">dash escaping</span></a> where appropriate. In particular, this is
the case for every method that provides a widget: <a class="reference internal" href="widgets.html#dialog.Dialog.yesno" title="dialog.Dialog.yesno"><code class="xref py py-meth docutils literal notranslate"><span class="pre">yesno()</span></code></a>,
<a class="reference internal" href="widgets.html#dialog.Dialog.msgbox" title="dialog.Dialog.msgbox"><code class="xref py py-meth docutils literal notranslate"><span class="pre">msgbox()</span></code></a>, etc. You only need to do it yourself when
calling a low-level method such as <a class="reference internal" href="#dialog.Dialog.add_persistent_args" title="dialog.Dialog.add_persistent_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_persistent_args()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.12.</span></p>
</div>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="dialog.Dialog.dash_escape_nf">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">Dialog.</span></span><span class="sig-name descname"><span class="pre">dash_escape_nf</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/dialog.html#Dialog.dash_escape_nf"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dialog.Dialog.dash_escape_nf" title="Permalink to this definition">¶</a></dt>
<dd><p>Escape all elements of <em>args</em> that need escaping, except the first one.</p>
<p>See <a class="reference internal" href="#dialog.Dialog.dash_escape" title="dialog.Dialog.dash_escape"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dash_escape()</span></code></a> for details. Return a new list.</p>
<p>All high-level <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> methods automatically perform dash
escaping where appropriate. In particular, this is the case
for every method that provides a widget: <a class="reference internal" href="widgets.html#dialog.Dialog.yesno" title="dialog.Dialog.yesno"><code class="xref py py-meth docutils literal notranslate"><span class="pre">yesno()</span></code></a>, <a class="reference internal" href="widgets.html#dialog.Dialog.msgbox" title="dialog.Dialog.msgbox"><code class="xref py py-meth docutils literal notranslate"><span class="pre">msgbox()</span></code></a>,
etc. You only need to do it yourself when calling a low-level
method such as <a class="reference internal" href="#dialog.Dialog.add_persistent_args" title="dialog.Dialog.add_persistent_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_persistent_args()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 2.12.</span></p>
</div>
</dd></dl>
<p id="examples-of-dash-escaping">A contrived example using these methods could be the following, which sets a
weird background title starting with two dashes (<code class="docutils literal notranslate"><span class="pre">--My</span> <span class="pre">little</span> <span class="pre">program</span></code>) for
the life duration of a <a class="reference internal" href="#dialog.Dialog" title="dialog.Dialog"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code></a> instance <em>d</em>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d</span><span class="o">.</span><span class="n">add_persistent_args</span><span class="p">(</span><span class="n">d</span><span class="o">.</span><span class="n">dash_escape_nf</span><span class="p">(</span>
<span class="p">[</span><span class="s2">"--backtitle"</span><span class="p">,</span> <span class="s2">"--My little program"</span><span class="p">]))</span>
</pre></div>
</div>
<p>or, equivalently:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d</span><span class="o">.</span><span class="n">add_persistent_args</span><span class="p">([</span><span class="s2">"--backtitle"</span><span class="p">]</span>
<span class="o">+</span> <span class="n">d</span><span class="o">.</span><span class="n">dash_escape</span><span class="p">([</span><span class="s2">"--My little program"</span><span class="p">]))</span>
</pre></div>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code> class overview</a><ul>
<li><a class="reference internal" href="#initializing-a-dialog-instance">Initializing a <code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code> instance</a><ul>
<li><a class="reference internal" href="#dialog.Dialog"><code class="docutils literal notranslate"><span class="pre">Dialog</span></code></a><ul>
<li><a class="reference internal" href="#dialog.Dialog.__init__"><code class="docutils literal notranslate"><span class="pre">Dialog.__init__()</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#passing-dialog-common-options">Passing <strong class="program">dialog</strong> “common options”</a></li>
<li><a class="reference internal" href="#return-value-of-widget-producing-methods">Return value of widget-producing methods</a><ul>
<li><a class="reference internal" href="#dialog-exit-code-high-level">“Dialog exit code” (high-level)</a><ul>
<li><a class="reference internal" href="#dialog.Dialog.OK"><code class="docutils literal notranslate"><span class="pre">Dialog.OK</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.CANCEL"><code class="docutils literal notranslate"><span class="pre">Dialog.CANCEL</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.ESC"><code class="docutils literal notranslate"><span class="pre">Dialog.ESC</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.EXTRA"><code class="docutils literal notranslate"><span class="pre">Dialog.EXTRA</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.HELP"><code class="docutils literal notranslate"><span class="pre">Dialog.HELP</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.DIALOG_OK"><code class="docutils literal notranslate"><span class="pre">Dialog.DIALOG_OK</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.DIALOG_CANCEL"><code class="docutils literal notranslate"><span class="pre">Dialog.DIALOG_CANCEL</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.DIALOG_ESC"><code class="docutils literal notranslate"><span class="pre">Dialog.DIALOG_ESC</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.DIALOG_EXTRA"><code class="docutils literal notranslate"><span class="pre">Dialog.DIALOG_EXTRA</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.DIALOG_HELP"><code class="docutils literal notranslate"><span class="pre">Dialog.DIALOG_HELP</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.DIALOG_ITEM_HELP"><code class="docutils literal notranslate"><span class="pre">Dialog.DIALOG_ITEM_HELP</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#dialog-exit-status-low-level">“dialog exit status” (low-level)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#adding-an-extra-button">Adding an Extra button</a></li>
<li><a class="reference internal" href="#providing-on-line-help-facilities">Providing on-line help facilities</a><ul>
<li><a class="reference internal" href="#adding-a-help-button">Adding a <span class="guilabel">Help</span> button</a></li>
<li><a class="reference internal" href="#providing-inline-per-item-help">Providing inline per-item help</a></li>
<li><a class="reference internal" href="#getting-the-widget-status-before-the-help-button-was-pressed">Getting the widget status before the <span class="guilabel">Help</span> button was pressed</a></li>
</ul>
</li>
<li><a class="reference internal" href="#screen-related-methods">Screen-related methods</a><ul>
<li><a class="reference internal" href="#dialog.Dialog.maxsize"><code class="docutils literal notranslate"><span class="pre">Dialog.maxsize()</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.set_background_title"><code class="docutils literal notranslate"><span class="pre">Dialog.set_background_title()</span></code></a></li>
<li><a class="reference internal" href="#obsolete-methods">Obsolete methods</a><ul>
<li><a class="reference internal" href="#dialog.Dialog.setBackgroundTitle"><code class="docutils literal notranslate"><span class="pre">Dialog.setBackgroundTitle()</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.clear"><code class="docutils literal notranslate"><span class="pre">Dialog.clear()</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#checking-the-versions-of-pythondialog-and-its-backend">Checking the versions of pythondialog and its backend</a><ul>
<li><a class="reference internal" href="#version-of-pythondialog">Version of pythondialog</a><ul>
<li><a class="reference internal" href="#dialog.VersionInfo"><code class="docutils literal notranslate"><span class="pre">VersionInfo</span></code></a><ul>
<li><a class="reference internal" href="#dialog.VersionInfo.__repr__"><code class="docutils literal notranslate"><span class="pre">VersionInfo.__repr__()</span></code></a></li>
<li><a class="reference internal" href="#dialog.VersionInfo.__str__"><code class="docutils literal notranslate"><span class="pre">VersionInfo.__str__()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#dialog.version_info"><code class="docutils literal notranslate"><span class="pre">version_info</span></code></a></li>
<li><a class="reference internal" href="#dialog.__version__"><code class="docutils literal notranslate"><span class="pre">__version__</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#version-of-the-backend">Version of the backend</a><ul>
<li><a class="reference internal" href="#dialog.Dialog.cached_backend_version"><code class="docutils literal notranslate"><span class="pre">Dialog.cached_backend_version</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.backend_version"><code class="docutils literal notranslate"><span class="pre">Dialog.backend_version()</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#enabling-debug-facilities">Enabling debug facilities</a><ul>
<li><a class="reference internal" href="#dialog.Dialog.setup_debug"><code class="docutils literal notranslate"><span class="pre">Dialog.setup_debug()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous-methods">Miscellaneous methods</a><ul>
<li><a class="reference internal" href="#dialog.Dialog.add_persistent_args"><code class="docutils literal notranslate"><span class="pre">Dialog.add_persistent_args()</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.dash_escape"><code class="docutils literal notranslate"><span class="pre">Dialog.dash_escape()</span></code></a></li>
<li><a class="reference internal" href="#dialog.Dialog.dash_escape_nf"><code class="docutils literal notranslate"><span class="pre">Dialog.dash_escape_nf()</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="intro/intro.html"
title="previous chapter">A gentle introduction</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="widgets.html"
title="next chapter">The <code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code> widgets</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/Dialog_class_overview.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="widgets.html" title="The Dialog widgets"
>next</a> |</li>
<li class="right" >
<a href="intro/intro.html" title="A gentle introduction"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pythondialog 3.5.1 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialog</span></code> class overview</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2002-2023, Florent Rougon, Thomas Dickey.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
</div>
</body>
</html>