The Dialog widgets

This section describes all widgets (or dialog boxes) offered by the Dialog class. The descriptions of many of them are adapted from the dialog(1) manual page, with the kind permission of Thomas Dickey.

Note

All unqualified method names in this section are methods of the Dialog class. In other words, whenever a method foo() is mentioned, you have to understand dialog.Dialog.foo().

Warning

Concerning the older widgets that have fixed defaults for the length parameters such as width and height:

Even though explicitely setting one of these length parameters to None will not cause any error in this version, please don’t do it. If you know the size you want, specify it directly (e.g., width=78). On the other hand, if you want dialog to automagically figure out a suitable size, you have two options:

• either enable the autowidgetsize option and make sure not to specify the length parameter in the widget call;

• or explicitely set it to 0 (e.g., width=0).

Displaying multi-line text

Message box

Dialog.msgbox(text, height=None, width=None, **kwargs)

Display a message dialog box, with scrolling and line wrapping.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

Returns

a Dialog exit code

Return type

str

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

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

msgbox() performs automatic line wrapping. If you want to force a newline at some point, simply insert it in text. In other words (with the default settings), newline characters in text are respected; the line wrapping process performed by dialog only inserts additional newlines when needed. If you want no automatic line wrapping, consider using scrollbox().

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

Notable exceptions:

any exception raised by Dialog._perform()

msgbox() example

Text box

Dialog.textbox(filepath, height=None, width=None, **kwargs)

Display the contents of a file in a dialog box.

Parameters

• filepath (str) – path to a file, the contents of which is to be displayed in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

Returns

a Dialog exit code

Return type

str

A textbox() lets you display the contents of a text file in a dialog box. It is like a simple text file viewer. The user can move through the file using the Up and Down arrow keys, Page Up and Page Down as well as the Home and End keys available on most keyboards. If the lines are too long to be displayed in the box, the Left and Right arrow keys can be used to scroll the text region horizontally. For more convenience, forward and backward search functions are also provided.

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

Notable exceptions:

any exception raised by Dialog._perform()

textbox() example

Scroll box

Dialog.scrollbox(text, height=None, width=None, **kwargs)

Display a string in a scrollable box, with no line wrapping.

Parameters

• text (str) – string to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

Returns

a Dialog exit code

Return type

str

This method is a layer on top of textbox(). The textbox() widget in dialog allows one to display file contents only. This method can be used to display any text in a scrollable box. This is simply done by creating a temporary file, calling textbox() and deleting the temporary file afterwards.

The text is not automatically wrapped. New lines in the scrollable box will be placed exactly as in text. If you want automatic line wrapping, you should use the msgbox() widget instead (the textwrap module from the Python standard library is also worth knowing about).

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

Notable exceptions:

PythonDialogOSError (PythonDialogIOError if the Python version is < 3.3)

Changed in version 3.1: UnableToCreateTemporaryDirectory exception can’t be raised anymore. The equivalent condition now raises PythonDialogOSError.

scrollbox() example

Edit box

Dialog.editbox(filepath, height=0, width=0, **kwargs)

Display a basic text editor dialog box.

Parameters

• filepath (str) – path to a file which determines the initial contents of the dialog box

• height (int) – height of the box

• width (int) – width of the box

Returns

a tuple of the form (code, text) where:

• code is a Dialog exit code;

• text is the contents of the text entry window on exit.

Return type

tuple

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

Notable exceptions:

any exception raised by Dialog._perform()

See also

method editbox_str()

editbox() example

Dialog.editbox_str(init_contents, *args, **kwargs)

Display a basic text editor dialog box (wrapper around editbox()).

Parameters

• init_contents (str) – initial contents of the dialog box

• args – positional arguments to pass to editbox()

• kwargs – keyword arguments to pass to editbox()

Returns

a tuple of the form (code, text) where:

• code is a Dialog exit code;

• text is the contents of the text entry window on exit.

Return type

tuple

The editbox_str() method is a thin wrapper around editbox(). editbox_str() accepts a string as its first argument, instead of a file path. That string is written to a temporary file whose path is passed to editbox() along with the arguments specified via args and kwargs. Please refer to editbox()’s documentation for more details.

Notes:

• the temporary file is deleted before the method returns;

• if init_contents does not end with a newline character ('\n'), then this method automatically adds one. This is done in order to avoid unexpected behavior resulting from the fact that, before version 1.3-20160209, dialog’s editbox widget ignored the last line of the input file unless it was terminated by a newline character.

Notable exceptions:

• PythonDialogOSError

• any exception raised by Dialog._perform()

New in version 3.4.

See also

method editbox()

Progress box

Dialog.progressbox(file_path=None, file_flags=0, fd=None, text=None, height=None, width=None, **kwargs)

Display a possibly growing stream in a dialog box, as with tail -f.

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

Parameters

• file_path (str) – path to the file that is going to be displayed

• file_flags – flags used when opening file_path; those are passed to os.open() (not the built-in open() function!). By default, only one flag is set: os.O_RDONLY.

or

Parameters

fd (int) – file descriptor for the stream to be displayed

Remaining parameters:

Parameters

• text – caption continuously displayed at the top, above the stream text, or None to disable the caption

• height (int or None) – height of the box

• width (int or None) – width of the box

Returns

a Dialog exit code

Return type

str

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

The file can be specified in two ways:

• either by giving its path (and optionally os.open() flags) with parameters file_path and file_flags;

• or by passing its file descriptor with parameter fd (in which case it may not even be a file; for instance, it could be an anonymous pipe created with os.pipe()).

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

Notable exceptions:

• PythonDialogOSError (PythonDialogIOError if the Python version is < 3.3)

• any exception raised by Dialog._perform()

progressbox() example

Program box

Dialog.programbox(file_path=None, file_flags=0, fd=None, text=None, height=None, width=None, **kwargs)

Display a possibly growing stream in a dialog box, as with tail -f.

A programbox() is very similar to a progressbox(). The only difference between a programbox() and a progressbox() is that a programbox() displays an OK button, but only after the input stream has been exhausted (i.e., End Of File has been reached).

This dialog box can be used to display the piped output of an external program. After the program completes, the user can press the Enter key to close the dialog and resume execution of the calling program.

The parameters and exceptions are the same as for progressbox(). Please refer to the corresponding documentation.

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

This widget requires dialog >= 1.1-20110302.

New in version 2.14.

programbox() example

Tail box

Dialog.tailbox(filepath, height=None, width=None, **kwargs)

Display the contents of a file in a dialog box, as with tail -f.

Parameters

• filepath (str) – path to a file, the contents of which is to be displayed in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

Returns

a Dialog exit code

Return type

str

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

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

Notable exceptions:

any exception raised by Dialog._perform()

tailbox() example

Displaying transient messages

Info box

Dialog.infobox(text, height=None, width=None, **kwargs)

Display an information dialog box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

Returns

a Dialog exit code

Return type

str

An info box is basically a message box. However, in this case, dialog will exit immediately after displaying the message to the user. The screen is not cleared when dialog exits, so that the message will remain on the screen after the method returns. This is useful when you want to inform the user that some operations are carrying on that may require some time to finish.

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

Notable exceptions:

any exception raised by Dialog._perform()

infobox() example

Pause

Dialog.pause(text, height=None, width=None, seconds=5, **kwargs)

Display a pause dialog box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

• seconds (int) – number of seconds to pause for

Returns

a Dialog exit code (which is Dialog.OK if the widget ended automatically after seconds seconds or if the user pressed the OK button)

Return type

str

A pause() box displays a text and a meter along the bottom of the box, during a specified amount of time (seconds). The meter indicates how many seconds remain until the end of the pause. The widget exits when the specified number of seconds is elapsed, or immediately if the user presses the OK button, the Cancel button or the Esc key.

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

Notable exceptions:

any exception raised by Dialog._perform()

pause() example

Progress meters

Regular gauge

Dialog.gauge_start(text='', height=None, width=None, percent=0, **kwargs)

Display a gauge box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

• percent (int) – initial percentage shown in the meter

Returns

undefined

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

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

Gauge typical usage

Gauge typical usage (assuming that d is an instance of the Dialog class) looks like this:

d.gauge_start()
# do something
d.gauge_update(10)       # 10% of the whole task is done
# ...
d.gauge_update(100, "any text here") # work is done
exit_code = d.gauge_stop()           # cleanup actions

Default values for the size parameters when the autowidgetsize option is disabled: height=8, width=54.

Notable exceptions:

• any exception raised by _call_program()

• PythonDialogOSError

Dialog.gauge_update(percent, text='', update_text=False)

Update a running gauge box.

Parameters

• percent (int) – new percentage to show in the gauge meter

• text (str) – new text to optionally display in the box

• update_text (bool) – whether to update the text in the box

Returns

undefined

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

See the gauge_start() method documentation for information about how to use a gauge.

Notable exception:

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

Dialog.gauge_iterate(**kwargs)

Update a running gauge box.

Deprecated since version 2.03: Use gauge_update() instead.

Dialog.gauge_stop()

Terminate a running gauge widget.

Returns

a Dialog exit code

Return type

str

This function performs the appropriate cleanup actions to terminate a running gauge started with gauge_start().

See the gauge_start() method documentation for information about how to use a gauge.

Notable exceptions:

• any exception raised by _handle_program_exit();

• PythonDialogIOError (PythonDialogOSError from Python 3.3 onwards) can be raised if closing the pipe used to talk to the dialog-like program fails.

gauge() example

Mixed gauge

Dialog.mixedgauge(text, height=0, width=0, percent=0, elements=[], **kwargs)

Display a mixed gauge dialog box.

Parameters

• text (str) – text to display in the middle of the box, between the elements list and the progress bar

• height (int) – height of the box

• width (int) – width of the box

• percent (int) – integer giving the percentage for the global progress bar

• elements – an iterable of (tag, item) tuples, the meaning of which is explained below

Returns

a Dialog exit code

Return type

str

A mixedgauge() box displays a list of “elements” with status indication for each of them, followed by a text and finally a global progress bar along the bottom of the box.

The top part (“elements”) is suitable for displaying a task list. One element is displayed per line, with its tag part on the left and its item part on the right. The item part is a string that is displayed on the right of the same line.

The item part of an element can be an arbitrary string. Special values listed in the dialog(3) manual page are translated into a status indication for the corresponding task (tag), such as: “Succeeded”, “Failed”, “Passed”, “Completed”, “Done”, “Skipped”, “In Progress”, “Checked”, “N/A” or a progress bar.

A progress bar for an element is obtained by supplying a negative number for the item. For instance, "-75" will cause a progress bar indicating 75% to be displayed on the corresponding line.

For your convenience, if an item appears to be an integer or a float, it will be converted to a string before being passed to the dialog-like program.

text is shown as a sort of caption between the list and the global progress bar. The latter displays percent as the percentage of completion.

Contrary to the regular gauge widget, mixedgauge() is completely static. You have to call mixedgauge() several times in order to display different percentages in the global progress bar or various status indicators for a given task.

Note

Calling mixedgauge() several times is likely to cause unwanted flickering because of the screen initializations performed by dialog on every run.

Notable exceptions:

any exception raised by Dialog._perform()

mixedgauge() example

List-like widgets

Build list

Dialog.buildlist(text, height=0, width=0, list_height=0, items=[], **kwargs)

Display a buildlist box.

Parameters

• text (str) – text to display in the box

• height (int) – height of the box

• width (int) – width of the box

• list_height (int) – height of the selected and unselected list boxes

• items – an iterable of (tag, item, status) tuples where status specifies the initial selected/unselected state of each entry; can be True or False, 1 or 0, "on" or "off" (True, 1 and "on" meaning selected), or any case variation of these two strings.

Returns

a tuple of the form (code, tags) where:

• code is a Dialog exit code;

• tags is a list of the tags corresponding to the selected items, in the order they have in the list on the right.

Return type

tuple

A buildlist() dialog is similar in logic to the checklist(), but differs in presentation. In this widget, two lists are displayed, side by side. The list on the left shows unselected items. The list on the right shows selected items. As items are selected or unselected, they move between the two lists. The status component of items specifies which items are initially selected.

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

If called with visit_items=True, the Tab key can move the focus to the left and right lists, which is probably more intuitive for users than the default behavior that requires using ^ and $ for this purpose.

This widget requires dialog >= 1.2-20121230.

Notable exceptions:

any exception raised by Dialog._perform() or _to_onoff()

New in version 3.0.

buildlist() example

Check list

Dialog.checklist(text, height=None, width=None, list_height=None, choices=[], **kwargs)

Display a checklist box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

• list_height (int or None) – number of entries displayed in the box at a given time (the contents can be scrolled)

• choices – an iterable of (tag, item, status) tuples where status specifies the initial selected/unselected state of each entry; can be True or False, 1 or 0, "on" or "off" (True, 1 and "on" meaning selected), or any case variation of these two strings.

Returns

a tuple of the form (code, [tag, ...]) whose first element is a Dialog exit code and second element lists all tags for the entries selected by the user. If the user exits with Esc or Cancel, the returned tag list is empty.

Return type

tuple

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

Notable exceptions:

any exception raised by Dialog._perform() or _to_onoff()

checklist() example

Menu

Dialog.menu(text, height=None, width=None, menu_height=None, choices=[], **kwargs)

Display a menu dialog box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

• menu_height (int or None) – number of entries displayed in the box (which can be scrolled) at a given time

• choices – an iterable of (tag, item) tuples, the meaning of which is explained below

Returns

a tuple of the form (code, tag) where:

• code is a Dialog exit code;

• tag is the tag string corresponding to the item that the user chose.

Return type

tuple

As its name suggests, a menu() box is a dialog box that can be used to present a list of choices in the form of a menu for the user to choose. Choices are displayed in the given order.

Each menu entry consists of a tag string and an item string. The tag gives the entry a name to distinguish it from the other entries in the menu and to provide quick keyboard access. The item is a short description of the option that the entry represents.

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

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

Notable exceptions:

any exception raised by Dialog._perform()

menu() example

Radio list

Dialog.radiolist(text, height=None, width=None, list_height=None, choices=[], **kwargs)

Display a radiolist box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

• list_height (int or None) – number of entries displayed in the box (which can be scrolled) at a given time

• choices – an iterable of (tag, item, status) tuples where status specifies the initial selected/unselected state of each entry; can be True or False, 1 or 0, "on" or "off" (True, 1 and "on" meaning selected), or any case variation of these two strings. No more than one entry should be set to True.

Returns

a tuple of the form (code, tag) where:

• code is a Dialog exit code;

• tag is the tag string corresponding to the entry that was chosen by the user.

Return type

tuple

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

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

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

Notable exceptions:

any exception raised by Dialog._perform() or _to_onoff()

radiolist() example

Tree view

Dialog.treeview(text, height=0, width=0, list_height=0, nodes=[], **kwargs)

Display a treeview box.

Parameters

• text (str) – text to display at the top of the box

• height (int) – height of the box

• width (int) – width of the box

• list_height (int) – number of lines reserved for the main part of the box, where the tree is displayed

• nodes –

  an iterable of (tag, item, status, depth) tuples describing nodes, where:

  • tag is used to indicate which node was selected by the user on exit;

  • item is the text displayed for the node;

  • status specifies the initial selected/unselected state of each entry; can be True or False, 1 or 0, "on" or "off" (True, 1 and "on" meaning selected), or any case variation of these two strings;

  • depth is a non-negative integer indicating the depth of the node in the tree (0 for the root node).

Returns

a tuple of the form (code, tag) where:

• code is a Dialog exit code;

• tag is the tag of the selected node.

Display nodes organized in a tree structure. Each node has a tag, an item text, a selected status, and a depth in the tree. Only the item texts are displayed in the widget; tags are only used for the return value. Only one node can be selected at a given time, as for the radiolist() widget.

This widget requires dialog >= 1.2-20121230.

Notable exceptions:

any exception raised by Dialog._perform() or _to_onoff()

New in version 2.14.

treeview() example

Single-line input fields

Input box

Dialog.inputbox(text, height=None, width=None, init='', **kwargs)

Display an input dialog box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

• init (str) – default input string

Returns

a tuple of the form (code, string) where:

• code is a Dialog exit code;

• string is the string entered by the user.

Return type

tuple

An input box is useful when you want to ask questions that require the user to input a string as the answer. If init is supplied, it is used to initialize the input string. When entering the string, the Backspace key can be used to correct typing errors. If the input string is longer than can fit in the dialog box, the input field will be scrolled.

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

Notable exceptions:

any exception raised by Dialog._perform()

inputbox() example

Input menu

Dialog.inputmenu(text, height=0, width=None, menu_height=None, choices=[], **kwargs)

Display an inputmenu dialog box.

Parameters

• text (str) – text to display in the box

• height (int) – height of the box

• width (int or None) – width of the box

• menu_height (int or None) – height of the menu (scrollable part)

• choices – an iterable of (tag, item) tuples, the meaning of which is explained below

Returns

see below

Overview

An inputmenu() box is a dialog box that can be used to present a list of choices in the form of a menu for the user to choose. Choices are displayed in the given order. The main differences with the menu() dialog box are:

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

• the current entry can be renamed by pressing the Rename button, which allows editing the item part of the current entry.

Each menu entry consists of a tag string and an item string. The tag gives the entry a name to distinguish it from the other entries in the menu and to provide quick keyboard access. The item is a short description of the option that the entry represents.

The user can move between the menu entries by pressing the Up and Down arrow keys or the first letter of the tag as a hot key. There are menu_height lines (not entries!) displayed in the scrollable part of the menu at one time.

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

Note

It is strongly advised not to put any space in tags, otherwise the dialog output can be ambiguous if the corresponding entry is renamed, causing pythondialog to return a wrong tag string and new item text.

The reason is that in this case, the dialog output is RENAMED tag item and pythondialog cannot guess whether spaces after the RENAMED + space prefix belong to the tag or the new item text.

Note

There is no point in calling this method with help_status=True, because it is not possible to rename several items nor is it possible to choose the Help button (or any button other than Rename) once one has started to rename an item.

Return value

Return a tuple of the form (exit_info, tag, new_item_text) where:

• exit_info is either:

  • the string "accepted", meaning that an entry was accepted without renaming;

  • the string "renamed", meaning that an entry was accepted after being renamed;

  • one of the standard Dialog exit codes Dialog.CANCEL, Dialog.ESC or Dialog.HELP (Dialog.EXTRA can’t be returned, because internally, the Rename button is the Extra button).

• tag indicates which entry was accepted (with or without renaming), if any. If no entry was accepted (e.g., if the dialog was exited with the Cancel button), then tag is None.

• new_item_text gives the new item part of the renamed entry if exit_info is "renamed", otherwise it is None.

Default values for the size parameters when the autowidgetsize option is disabled: height=0, width=60, menu_height=7.

Notable exceptions:

any exception raised by Dialog._perform()

inputmenu() example

Password box

Dialog.passwordbox(text, height=None, width=None, init='', **kwargs)

Display a password input dialog box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

• init (str) – default input password

Returns

a tuple of the form (code, password) where:

• code is a Dialog exit code;

• password is the password entered by the user.

Return type

tuple

A passwordbox() is similar to an inputbox(), except that the text the user enters is not displayed. This is useful when prompting for passwords or other sensitive information. Be aware that if anything is passed in init, it will be visible in the system’s process table to casual snoopers. Also, it is very confusing to the user to provide them with a default password they cannot see. For these reasons, using init is highly discouraged.

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

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

Notable exceptions:

any exception raised by Dialog._perform()

passwordbox() example

Forms

Form

Dialog.form(text, elements, height=0, width=0, form_height=0, **kwargs)

Display a form consisting of labels and fields.

Parameters

• text (str) – text to display in the box

• elements – sequence describing the labels and fields (see below)

• height (int) – height of the box

• width (int) – width of the box

• form_height (int) – number of form lines displayed at the same time

Returns

a tuple of the form (code, list) where:

• code is a Dialog exit code;

• list gives the contents of every editable field on exit, with the same order as in elements.

Return type

tuple

A form() box consists in a series of fields and associated labels. This type of dialog is suitable for adjusting configuration parameters and similar tasks.

Each element of elements must itself be a sequence (label, yl, xl, item, yi, xi, field_length, input_length) containing the various parameters concerning a given field and the associated label.

label is a string that will be displayed at row yl, column xl. item is a string giving the initial value for the field, which will be displayed at row yi, column xi (row and column numbers starting from 1).

field_length and input_length are integers that respectively specify the number of characters used for displaying the field and the maximum number of characters that can be entered for this field. These two integers also determine whether the contents of the field can be modified, as follows:

• if field_length is zero, the field cannot be altered and its contents determines the displayed length;

• if field_length is negative, the field cannot be altered and the opposite of field_length gives the displayed length;

• if input_length is zero, it is set to field_length.

Notable exceptions:

• BadPythonDialogUsage

• any exception raised by Dialog._perform()

form() example

Mixed form

Dialog.mixedform(text, elements, height=0, width=0, form_height=0, **kwargs)

Display a form consisting of labels and fields.

Parameters

• text (str) – text to display in the box

• elements – sequence describing the labels and fields (see below)

• height (int) – height of the box

• width (int) – width of the box

• form_height (int) – number of form lines displayed at the same time

Returns

a tuple of the form (code, list) where:

• code is a Dialog exit code;

• list gives the contents of every field on exit, with the same order as in elements.

Return type

tuple

A mixedform() box is very similar to a form() box, and differs from the latter by allowing field attributes to be specified.

Each element of elements must itself be a sequence (label, yl, xl, item, yi, xi, field_length, input_length, attributes) containing the various parameters concerning a given field and the associated label.

attributes is an integer interpreted as a bit mask with the following meaning (bit 0 being the least significant bit):

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

For all other parameters, please refer to the documentation of the form() box.

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

Notable exceptions:

• BadPythonDialogUsage

• any exception raised by Dialog._perform()

mixedform() example

Password form

Dialog.passwordform(text, elements, height=0, width=0, form_height=0, **kwargs)

Display a form consisting of labels and invisible fields.

This widget is identical to the form() box, except that all text fields are treated as passwordbox() widgets rather than inputbox() widgets.

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

Notable exceptions:

• BadPythonDialogUsage

• any exception raised by Dialog._perform()

passwordform() example

Selecting files and directories

Directory selection

Dialog.dselect(filepath, height=0, width=0, **kwargs)

Display a directory selection dialog box.

Parameters

• filepath (str) – initial path

• height (int) – height of the box

• width (int) – width of the box

Returns

a tuple of the form (code, path) where:

• code is a Dialog exit code;

• path is the directory chosen by the user.

Return type

tuple

The directory selection dialog displays a text entry window in which you can type a directory, and above that a window with directory names.

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

Use Tab or the arrow keys to move between the windows. Within the directory window, use the Up and Down arrow keys to scroll the current selection. Use the Space bar to copy the current selection into the text entry window.

Typing any printable character switches focus to the text entry window, entering that character as well as scrolling the directory window to the closest match.

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

Notable exceptions:

any exception raised by Dialog._perform()

dselect() example

File or directory selection

Dialog.fselect(filepath, height=0, width=0, **kwargs)

Display a file selection dialog box.

Parameters

• filepath (str) – initial path

• height (int) – height of the box

• width (int) – width of the box

Returns

a tuple of the form (code, path) where:

• code is a Dialog exit code;

• path is the path chosen by the user (the last element of which may be a directory or a file).

Return type

tuple

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

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

Use Tab or the arrow keys to move between the windows. Within the directory or file name windows, use the Up and Down arrow keys to scroll the current selection. Use the Space bar to copy the current selection into the text entry window.

Typing any printable character switches focus to the text entry window, entering that character as well as scrolling the directory and file name windows to the closest match.

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

Notable exceptions:

any exception raised by Dialog._perform()

fselect() example

Date and time

Calendar

Dialog.calendar(text, height=None, width=0, day=- 1, month=- 1, year=- 1, **kwargs)

Display a calendar dialog box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box (minus the calendar height)

• width (int) – width of the box

• day (int) – inititial day highlighted

• month (int) – inititial month displayed

• year (int) – inititial year selected

Returns

a tuple of the form (code, date) where:

• code is a Dialog exit code;

• date is a list of the form [day, month, year], where day, month and year are integers corresponding to the date chosen by the user.

Return type

tuple

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

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

Notable exceptions:

• any exception raised by Dialog._perform()

• UnexpectedDialogOutput

• PythonDialogReModuleError

Changed in version 3.2: The default values for day, month and year have been changed from 0 to -1.

calendar() example

Time box

Dialog.timebox(text, height=None, width=None, hour=- 1, minute=- 1, second=- 1, **kwargs)

Display a time dialog box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

• hour (int) – inititial hour selected

• minute (int) – inititial minute selected

• second (int) – inititial second selected

Returns

a tuple of the form (code, time) where:

• code is a Dialog exit code;

• time is a list of the form [hour, minute, second], where hour, minute and second are integers corresponding to the time chosen by the user.

Return type

tuple

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

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

Notable exceptions:

• any exception raised by Dialog._perform()

• PythonDialogReModuleError

• UnexpectedDialogOutput

timebox() example

Miscellaneous

Range box

Dialog.rangebox(text, height=0, width=0, min=None, max=None, init=None, **kwargs)

Display a range dialog box.

Parameters

• text (str) – text to display above the actual range control

• height (int) – height of the box

• width (int) – width of the box

• min (int) – minimum value for the range control

• max (int) – maximum value for the range control

• init (int) – initial value for the range control

Returns

a tuple of the form (code, val) where:

• code is a Dialog exit code;

• val is an integer: the value chosen by the user.

Return type

tuple

The rangebox() dialog allows the user to select from a range of integers using a kind of slider. The range control shows the current value as a bar (like the gauge dialog).

The Tab and arrow keys move the cursor between the buttons and the range control. When the cursor is on the latter, you can change the value with the following keys:

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

Some keys are also recognized in all cursor positions:

Key	Action
Home / End	set the value to its minimum or maximum
Page Up / Page Down	decrement/increment the value so that the slider moves by one column

This widget requires dialog >= 1.2-20121230.

Notable exceptions:

any exception raised by Dialog._perform()

New in version 2.14.

rangebox() example

Yes/No

Dialog.yesno(text, height=None, width=None, **kwargs)

Display a yes/no dialog box.

Parameters

• text (str) – text to display in the box

• height (int or None) – height of the box

• width (int or None) – width of the box

Returns

a Dialog exit code

Return type

str

Display a dialog box containing text and two buttons labelled Yes and No by default.

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

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

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

Notable exceptions:

any exception raised by Dialog._perform()

yesno() example