MainWindow#

A window for displaying components to the user

Usage#

A MainWindow is used for desktop applications, where components need to be shown within a window-manager. Windows can be configured on instantiation and support displaying multiple widgets, toolbars and resizing.

import toga

window = toga.MainWindow('id-window', title='This is a window!')
window.show()

Reference#

class toga.app.MainWindow(id=None, title=None, position=(100, 100), size=(640, 480), toolbar=None, resizeable=True, minimizable=True, factory=None, on_close=None)#

property app#

Instance of the toga.App that this window belongs to.

Returns:: The app that it belongs to toga.App.
Raises:: Exception – If the window already is associated with another app.

close()#

confirm_dialog(title, message, on_result=None)#

Ask the user to confirm if they wish to proceed with an action.

Presents as a dialog with ‘Cancel’ and ‘OK’ buttons (or whatever labels are appropriate on the current platform)

Parameters:

title – The title of the dialog window.
message – A message describing the action to be confirmed.
on_result – A callback that will be invoked when the user selects an option on the dialog.

Returns:

An awaitable Dialog object. The Dialog object returns True when the ‘OK’ button was pressed, False when the ‘CANCEL’ button was pressed.

property content#

Content of the window. On setting, the content is added to the same app as the window and to the same app.

Returns:: A Widget

error_dialog(title, message, on_result=None)#

Ask the user to acknowledge an error state.

Presents as an error dialog with a ‘OK’ button to close the dialog.

Parameters:

title – The title of the dialog window.
message – The error message to display.
on_result – A callback that will be invoked when the user selects an option on the dialog.

Returns:

An awaitable Dialog object. The Dialog object returns None after the user pressed the ‘OK’ button.

property full_screen#

hide()#: Hide window, if shown.

property id#

The DOM identifier for the window. This id can be used to target CSS directives.

Returns:: The identifier as a str.

info_dialog(title, message, on_result=None)#

Ask the user to acknowledge some information.

Presents as a dialog with a single ‘OK’ button to close the dialog.

Parameters:

title – The title of the dialog window.
message – The message to display.
on_result – A callback that will be invoked when the user selects an option on the dialog.

Returns:

An awaitable Dialog object. The Dialog object returns None after the user pressed the ‘OK’ button.

property on_close#

The handler to invoke before the window is closed.

Returns:: The function callable that is called before the window is closed.

open_file_dialog(title, initial_directory=None, file_types=None, multiselect=False, on_result=None)#

Ask the user to select a file (or files) to open.

Presents the user a system-native “Open file” dialog.

Parameters:

title – The title of the dialog window
initial_directory – The initial folder in which to open the dialog. If None, use the default location provided by the operating system (which will often be “last used location”)
file_types – A list of strings with the allowed file extensions.
multiselect – If True, the user will be able to select multiple files; if False, the selection will be restricted to a single file/
on_result – A callback that will be invoked when the user selects an option on the dialog.

Returns:

An awaitable Dialog object. The Dialog object returns a list of Path objects if multiselect is True, or a single Path otherwise. Returns None if the open operation is cancelled by the user.

property position#

Position of the window, as x, y.

Returns:: A tuple of (int, int) int the from (x, y).

question_dialog(title, message, on_result=None)#

Ask the user a yes/no question.

Presents as a dialog with a ‘YES’ and ‘NO’ button.

Parameters:

title – The title of the dialog window.
message – The question to be answered.
on_result – A callback that will be invoked when the user selects an option on the dialog.

Returns:

An awaitable Dialog object. The Dialog object returns True when the ‘YES’ button was pressed, False when the ‘NO’ button was pressed.

save_file_dialog(title, suggested_filename, file_types=None, on_result=None)#

Prompt the user for a location to save a file.

Presents the user a system-native “Save file” dialog.

This opens a native dialog where the user can select a place to save a file. It is possible to suggest a filename and force the user to use a specific file extension. If no path is returned (eg. dialog is canceled), a ValueError is raised.

Parameters:

title – The title of the dialog window
suggested_filename – A default filename
file_types – A list of strings with the allowed file extensions.
on_result – A callback that will be invoked when the user selects an option on the dialog.

Returns:

An awaitable Dialog object. The Dialog object returns a path object for the selected file location, or None if the user cancelled the save operation.

select_folder_dialog(title, initial_directory=None, multiselect=False, on_result=None)#

Ask the user to select a directory/folder (or folders) to open.

Presents the user a system-native “Open folder” dialog.

Parameters:

title – The title of the dialog window
initial_directory – The initial folder in which to open the dialog. If None, use the default location provided by the operating system (which will often be “last used location”)
multiselect – If True, the user will be able to select multiple files; if False, the selection will be restricted to a single file/
on_result – A callback that will be invoked when the user selects an option on the dialog.

Returns:

An awaitable Dialog object. The Dialog object returns a list of Path objects if multiselect is True, or a single Path otherwise. Returns None if the open operation is cancelled by the user.

show()#: Show window, if hidden.

property size#

Size of the window, as width, height.

Returns:: A tuple of (int, int) where the first value is the width and the second it the height of the window.

stack_trace_dialog(title, message, content, retry=False, on_result=None)#

Open a dialog that allows to display a large text body, such as a stack trace.

Parameters:

title – The title of the dialog window.
message – Contextual information about the source of the stack trace.
content – The stack trace, pre-formatted as a multi-line string.
retry – A boolean; if True, the user will be given the a “Retry” and “Quit” option; if False, a single option to acknowledge the error will be displayed.
on_result – A callback that will be invoked when the user selects an option on the dialog.

Returns:

An awaitable Dialog object. If retry is enabled, the Dialog object returns True if the user selected retry, and False otherwise; if retry is not enabled, the dialog object returns None.

property title#

Title of the window. If no title is given it defaults to “Toga”.

Returns:: The current title of the window as a str.

property toolbar#

Toolbar for the window.

Returns:: A list of Widget

property visible#