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
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
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
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
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
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)[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: <class 'PySide2.QtWidgets.QFileDialog.FileMode'>

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

accept_mode: <class 'PySide2.QtWidgets.QFileDialog.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: <class 'PySide2.QtWidgets.QFileDialog.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: <class 'PySide2.QtWidgets.QMessageBox.Icon'>

The icon shown inside the dialog.

buttons: 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
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.