Window#

Availability (Key)#

macOS

GTK

Windows

iOS

Android

Web

○

○

○

○

○

○

A window for displaying components to the user

Usage#

The window class 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


class ExampleWindow(toga.App):
    def startup(self):
        self.label = toga.Label('Hello World')
        outer_box = toga.Box(
            children=[self.label]
        )
        self.window = toga.Window()
        self.window.content = outer_box

        self.window.show()


def main():
    return ExampleWindow('Window', 'org.beeware.window')


if __name__ == '__main__':
    app = main()
    app.main_loop()

Reference#

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

The top level container of an application.

Parameters:

  • id (str) – The ID of the window (optional).

  • title (str) – Title for the window (optional).

  • position (tuple of (int, int)) – Position of the window, as x,y coordinates.

  • size (tuple of (int, int)) – Size of the window, as (width, height) sizes, in pixels.

  • toolbar (list of Widget) – A list of widgets to add to a toolbar

  • resizeable (bool) – Toggle if the window is resizable by the user, defaults to True.

  • closeable (bool) – Toggle if the window is closable by the user, defaults to True.

  • minimizable (bool) – Toggle if the window is minimizable by the user, defaults to True.

  • on_close – A callback to invoke when the user makes a request to close the window.

property app#

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

Returns:

The app that it belongs to toga.app.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 (e.g. 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 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#