Dialogs¶

Usage Pattern¶

Creation Functions¶

qtrio.dialogs.create_integer_dialog(parent=None)[source]¶

Create an integer input dialog.

Parameters:: parent (Optional[QWidget]) – See qtrio.dialogs.IntegerDialog.parent.
Return type:: IntegerDialog
Returns:: The dialog manager.

qtrio.dialogs.create_text_input_dialog(title=None, label=None, parent=None)[source]¶

Create a text input dialog.

Parameters:

title (Optional[str]) – The text to use for the input dialog title bar.
label (Optional[str]) – The text to use for the input text box label.
parent (Optional[QWidget]) – See qtrio.dialogs.IntegerDialog.parent.

Return type:

TextInputDialog

Returns:

The dialog manager.

qtrio.dialogs.create_file_open_dialog(parent=None, default_directory=None, default_file=None, options=PySide2.QtWidgets.QFileDialog.Option(0))[source]¶

Create a file open dialog.

Parameters:

parent (Optional[QWidget]) – See qtrio.dialogs.FileDialog.parent.
default_directory (Optional[Path]) – See qtrio.dialogs.FileDialog.default_directory.
default_file (Optional[Path]) – See qtrio.dialogs.FileDialog.default_file.
options (Option) – See qtrio.dialogs.FileDialog.options.

Return type:

FileDialog

qtrio.dialogs.create_file_save_dialog(parent=None, default_directory=None, default_file=None, options=PySide2.QtWidgets.QFileDialog.Option(0))[source]¶

Create a file save dialog.

Parameters:

parent (Optional[QWidget]) – See qtrio.dialogs.FileDialog.parent.
default_directory (Optional[Path]) – See qtrio.dialogs.FileDialog.default_directory.
default_file (Optional[Path]) – See qtrio.dialogs.FileDialog.default_file.
options (Option) – See qtrio.dialogs.FileDialog.options.

Return type:

FileDialog

qtrio.dialogs.create_message_box(title='', text='', icon=PySide2.QtWidgets.QMessageBox.Icon.Information, buttons=PySide2.QtWidgets.QMessageBox.StandardButton.Ok, parent=None)[source]¶

Create a message box.

Parameters:

title (str) – See qtrio.dialogs.MessageBox.title.
text (str) – See qtrio.dialogs.MessageBox.text.
icon (Icon) – See qtrio.dialogs.MessageBox.icon.
buttons (Union[StandardButton, StandardButtons]) – See qtrio.dialogs.MessageBox.buttons.
parent (Optional[QWidget]) – See qtrio.dialogs.MessageBox.parent.

Return type:

MessageBox

qtrio.dialogs.create_progress_dialog(title='', text='', cancel_button_text=None, minimum=0, maximum=0, parent=None)[source]¶

Create a progress dialog.

Parameters:

title (str) – See qtrio.dialogs.ProgressDialog.title.
text (str) – See qtrio.dialogs.ProgressDialog.text.
cancel_button_text (Optional[str]) – See qtrio.dialogs.ProgressDialog.cancel_button_text.
minimum (int) – See qtrio.dialogs.ProgressDialog.minimum.
maximum (int) – See qtrio.dialogs.ProgressDialog.maximum.
parent (Optional[QWidget]) – See qtrio.dialogs.ProgressDialog.parent.

Return type:

ProgressDialog

Classes¶

class qtrio.dialogs.IntegerDialog(parent=None, dialog=None, edit_widget=None, accept_button=None, reject_button=None, result=None)[source]¶

Bases: object

Manage a dialog for inputting an integer from the user. Generally instances should be built via qtrio.dialogs.create_integer_dialog().

parent: Optional[QWidget]¶: The parent widget for the dialog.

dialog: Optional[QInputDialog]¶: The actual dialog widget instance.

edit_widget: Optional[QLineEdit]¶: The line edit that the user will enter the input into.

accept_button: Optional[QAbstractButton]¶: The entry confirmation button.

reject_button: Optional[QAbstractButton]¶: The input cancellation button.

result: Optional[int]¶: The result of parsing the user input.

shown¶: See qtrio.dialogs.DialogProtocol.shown.

finished¶: See qtrio.dialogs.BasicDialogProtocol.finished.

setup()[source]¶

See qtrio.dialogs.BasicDialogProtocol.setup().

Return type:: None

teardown()[source]¶

See qtrio.dialogs.BasicDialogProtocol.teardown().

Return type:: None

await wait()[source]¶

See qtrio.dialogs.DialogProtocol.wait().

Return type:: int

class qtrio.dialogs.TextInputDialog(title=None, label=None, parent=None, dialog=None, accept_button=None, reject_button=None, line_edit=None, result=None, finished_event=_Nothing.NOTHING)[source]¶

Bases: object

Manage a dialog for inputting an integer from the user. Generally instances should be built via qtrio.dialogs.create_text_input_dialog().

title: Optional[str]¶: The title of the dialog.

label: Optional[str]¶: The label for the input widget.

parent: Optional[QWidget]¶: The parent widget for the dialog.

dialog: Optional[QInputDialog]¶: The actual dialog widget instance.

accept_button: Optional[QAbstractButton]¶: The entry confirmation button.

reject_button: Optional[QAbstractButton]¶: The input cancellation button.

line_edit: Optional[QLineEdit]¶: The line edit that the user will enter the input into.

result: Optional[str]¶: The result of parsing the user input.

shown¶: See qtrio.dialogs.DialogProtocol.shown.

finished¶: See qtrio.dialogs.BasicDialogProtocol.finished.

finished_event: Event¶

setup()[source]¶

See qtrio.dialogs.BasicDialogProtocol.setup().

Return type:: None

teardown()[source]¶

See qtrio.dialogs.BasicDialogProtocol.teardown().

Return type:: None

await wait(shown_event=<trio.Event object>)[source]¶

See qtrio.dialogs.DialogProtocol.wait().

Return type:: str

class qtrio.dialogs.FileDialog(file_mode, accept_mode, default_directory=None, default_file=None, options=PySide2.QtWidgets.QFileDialog.Option(0), parent=None, dialog=None, accept_button=None, reject_button=None, file_name_line_edit=None, result=None)[source]¶

Bases: object

Manage a dialog for allowing the user to select a file or directory. Generally instances should be built via qtrio.dialogs.create_file_save_dialog().

file_mode: FileMode¶: Controls whether the dialog is for picking an existing vs. new file or directory, etc.

accept_mode: AcceptMode¶: Specify an open vs. a save dialog.

default_directory: Optional[Path]¶: The directory to be initially presented in the dialog.

default_file: Optional[Path]¶: The file to be initially selected in the dialog.

options: Option¶: Miscellaneous options. See the Qt documentation.

parent: Optional[QWidget]¶: The parent widget for the dialog.

dialog: Optional[QFileDialog]¶: The actual dialog widget instance.

accept_button: Optional[QAbstractButton]¶: The confirmation button.

reject_button: Optional[QAbstractButton]¶: The cancellation button.

file_name_line_edit: Optional[QLineEdit]¶: The file name line edit widget.

result: Optional[Path]¶: The path selected by the user.

shown¶: See qtrio.dialogs.DialogProtocol.shown.

finished¶: See qtrio.dialogs.BasicDialogProtocol.finished.

await set_path(path)[source]¶

Set the directory and enter the file name in the text box. Note that this does not select the file in the file list.

Parameters:: path (Path) – The full path to the file to be set.
Return type:: None

setup()[source]¶

See qtrio.dialogs.BasicDialogProtocol.setup().

Return type:: None

teardown()[source]¶

See qtrio.dialogs.BasicDialogProtocol.teardown().

Return type:: None

await wait(shown_event=<trio.Event object>)[source]¶

See qtrio.dialogs.DialogProtocol.wait().

Return type:: Path

class qtrio.dialogs.MessageBox(title, text, icon, buttons, parent=None, dialog=None, accept_button=None, result=None)[source]¶

Bases: object

Manage a message box for notifying the user. Generally instances should be built via qtrio.dialogs.create_message_box().

title: str¶: The message box title.

text: str¶: The message text shown inside the dialog.

icon: Icon¶: The icon shown inside the dialog.

buttons: Union[StandardButton, StandardButtons]¶: The buttons to be shown in the dialog.

parent: Optional[QWidget]¶: The parent widget for the dialog.

dialog: Optional[QMessageBox]¶: The actual dialog widget instance.

accept_button: Optional[QAbstractButton]¶: The button to accept the dialog.

result: Optional[Path]¶: Not generally relevant for a message box.

shown¶: See qtrio.dialogs.DialogProtocol.shown.

finished¶: See qtrio.dialogs.BasicDialogProtocol.finished.

setup()[source]¶

See qtrio.dialogs.BasicDialogProtocol.setup().

Return type:: None

teardown()[source]¶

See qtrio.dialogs.BasicDialogProtocol.teardown().

Return type:: None

await wait(shown_event=<trio.Event object>)[source]¶

See qtrio.dialogs.DialogProtocol.wait().

Return type:: None

class qtrio.dialogs.ProgressDialog(title, text, cancel_button_text, minimum, maximum, parent=None, dialog=None, cancel_button=None)[source]¶

Bases: object

Manage a progress dialog for updating the user. Generally instances should be built via qtrio.dialogs.create_progress_dialog().

title: str¶: The message box title.

text: str¶: The message text shown as the progress bar label.

cancel_button_text: Optional[str]¶: The cancel button text.

minimum: int¶: The progress value corresponding to no progress.

maximum: int¶: The progress value corresponding to completion.

parent: Optional[QWidget]¶: The parent widget for the dialog.

dialog: Optional[QProgressDialog]¶: The actual dialog widget instance.

cancel_button: Optional[QPushButton]¶: The cancellation button.

shown¶: See qtrio.dialogs.DialogProtocol.shown.

finished¶: See qtrio.dialogs.BasicDialogProtocol.finished.

setup()[source]¶

See qtrio.dialogs.BasicDialogProtocol.setup().

Return type:: None

teardown()[source]¶

See qtrio.dialogs.BasicDialogProtocol.teardown().

Return type:: None

async with manage()[source]¶

A context manager to setup the progress dialog, cancel the managed context and teardown the dialog when done.

Return type:: AsyncIterator[None]

Protocols¶

class qtrio.dialogs.BasicDialogProtocol(*args, **kwargs)[source]¶

Bases: Protocol

The minimal common interface used for working with QTrio dialogs. To check that a class implements this protocol see qtrio.dialogs.check_basic_dialog_protocol().

finished: Signal¶: The signal to be emitted when the dialog is finished.

setup()[source]¶

Setup and show the dialog. Emit qtrio.dialogs.DialogProtocol.shown when done.

Return type:: None

teardown()[source]¶

Hide and teardown the dialog.

Return type:: None

class qtrio.dialogs.DialogProtocol(*args, **kwargs)[source]¶

Bases: BasicDialogProtocol, Protocol

The common interface used for working with QTrio dialogs. To check that a class implements this protocol see qtrio.dialogs.check_dialog_protocol().

shown: Signal¶: The signal to be emitted when the dialog is shown.

await wait()[source]¶

Show the dialog, wait for the user interaction, and return the result.

Raises:

qtrio.InvalidInputError – If the input can’t be parsed as an integer.
qtrio.UserCancelledError – If the user cancels the dialog.

Return type:

object

Protocol Checkers¶

These callables can be used if you want to verify that your own classes properly implement the associated protocols. They are simple pass through decorators at runtime but when checking type hints they will result in a failure if the class does not implement the protocol.

qtrio.dialogs.check_basic_dialog_protocol = <qtrio._util.ProtocolChecker object>¶

Assert proper implementation of qtrio.dialogs.BasicDialogProtocol when type hint checking.

Parameters:: cls – The class to verify.
Returns:: The same class, unmodified, that was passed in.

qtrio.dialogs.check_dialog_protocol = <qtrio._util.ProtocolChecker object>¶

Assert proper implementation of qtrio.dialogs.DialogProtocol when type hint checking.

Parameters:: cls – The class to verify.
Returns:: The same class, unmodified, that was passed in.