Window

macOS

GTK+

Windows

iOS

Android

Django

y

y

y

y

y

y

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 a 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 toga.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.

  • factory (module) – A python module that is capable to return a implementation of this class with the same name. (optional; normally not needed)

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 toga.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
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 toga.Widget