Window#

An operating system-managed container of widgets.

Usage#

A window is the top-level container that the operating system uses to display widgets. A window may also have other decorations, such as a title bar or toolbar.

When first created, a window is not visible. To display it, call the show() method.

The window has content, which will usually be a container widget of some kind. The content of the window can be changed by re-assigning its content attribute to a different widget.

import toga

window = toga.Window()
window.content = toga.Box(children=[...])
window.show()

# Change the window's content to something new
window.content = toga.Box(children=[...])

If the user attempts to close the window, Toga will call the on_close handler. This handler must return a bool confirming whether the close is permitted. This can be used to implement protections against closing a window with unsaved changes.

Once a window has been closed (either by user action, or programmatically with close()), it cannot be reused. The behavior of any method on a Window instance after it has been closed is undefined.

Notes#

The operating system may provide controls that allow the user to resize, reposition, minimize, maximize or close the window. However, the availability of these controls is entirely operating system dependent.
While Toga provides methods for specifying the size and position of windows, these are ultimately at the discretion of the OS (or window manager). For example, on macOS, depending on a user’s OS-level settings, new windows may open as tabs on the main window; on Linux, some window managers (e.g., tiling window managers) may not honor an app’s size and position requests. You should avoid making UI design decisions that are dependent on specific size and placement of windows.
A mobile application can only have a single window (the MainWindow), and that window cannot be moved, resized, hidden, or made full screen. Toga will raise an exception if you attempt to create a secondary window on a mobile platform. If you try to modify the size, position, or visibility of the main window, the request will be ignored.

Reference#

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

Create a new Window.

Parameters:

id (str | None) – A unique identifier for the window. If not provided, one will be automatically generated.
title (str | None) – Title for the window. Defaults to “Toga”.
position (tuple[int, int]) – Position of the window, as a tuple of (x, y) coordinates, in CSS pixels.
size (tuple[int, int]) – Size of the window, as a tuple of (width, height), in CSS pixels.
resizable (bool) – Can the window be resized by the user?
closable (bool) – Can the window be closed by the user?
minimizable (bool) – Can the window be minimized by the user?
on_close (OnCloseHandler | None) – The initial on_close handler.
resizeable – DEPRECATED - Use resizable.
closeable – DEPRECATED - Use closable.

property app: App#

The App that this window belongs to (read-only).

New windows are automatically associated with the currently active app.

as_image(format=Image)#

Render the current contents of the window as an image.

Parameters:: format (type[ImageT]) – Format to provide. Defaults to Image; also supports PIL.Image.Image if Pillow is installed
Returns:: An image containing the window content, in the format requested.
Return type:: ImageT

property closable: bool#: Can the window be closed by the user?

close()#

Close the window.

This does not invoke the on_close handler; the window will be immediately and unconditionally closed.

Once a window has been closed, it cannot be reused. The behavior of any method or property on a Window instance after it has been closed is undefined, except for closed which can be used to check if the window was closed.

Return type:: None

property closeable: bool#: DEPRECATED Use closable

property closed: bool#: Whether the window was closed.

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).

This is an asynchronous method. If you invoke this method in synchronous context, it will show the dialog, but will return immediately. The object returned by this method can be awaited to obtain the result of the dialog.

Parameters:

title (str) – The title of the dialog window.
message (str) – A message describing the action to be confirmed.
on_result (DialogResultHandler[bool] | None) – DEPRECATED await the return value of this method.

Returns:

An awaitable Dialog object. The Dialog object returns True when the “OK” button is pressed, False when the “Cancel” button is pressed.

Return type:

Dialog

property content: Widget | None#: Content of the window. On setting, the content is added to the same app as the window.

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 (str) – The title of the dialog window.
message (str) – The error message to display.
on_result (DialogResultHandler[None] | None) – DEPRECATED await the return value of this method.

Returns:

An awaitable Dialog object. The Dialog object returns None when the user presses the “OK” button.

Return type:

Dialog

property full_screen: bool#

Is the window in full screen mode?

Full screen mode is not the same as “maximized”. A full screen window has no title bar, toolbar or window controls; some or all of these items may be visible on a maximized window. A good example of “full screen” mode is a slideshow app in presentation mode - the only visible content is the slide.

hide()#

Hide the window. If the window is already hidden, this method has no effect.

Return type:: None

property id: str#: A unique identifier for the window.

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 (str) – The title of the dialog window.
message (str) – The message to display.
on_result (DialogResultHandler[None] | None) – DEPRECATED await the return value of this method.

Returns:

An awaitable Dialog object. The Dialog object returns None when the user presses the ‘OK’ button.

Return type:

Dialog

property minimizable: bool#: Can the window be minimized by the user?

property on_close: OnCloseHandler#: The handler to invoke if the user attempts to close the window.

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

This dialog is not currently supported on Android or iOS.

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 the last used location)
file_types – The allowed filename extensions, without leading dots. If not provided, all files will be shown.
multiple_select – If True, the user will be able to select multiple files; if False, the selection will be restricted to a single file.
on_result – DEPRECATED await the return value of this method.
multiselect – DEPRECATED Use multiple_select.

Returns:

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

property position: tuple[int, int]#: Position of the window, as a tuple of (x, y) coordinates, in CSS pixels.

question_dialog(title, message, on_result=None)#

Ask the user a yes/no question.

Presents as a dialog with “Yes” and “No” buttons.

Parameters:

title (str) – The title of the dialog window.
message (str) – The question to be answered.
on_result (DialogResultHandler[bool] | None) – DEPRECATED await the return value of this method.

Returns:

An awaitable Dialog object. The Dialog object returns True when the “Yes” button is pressed, False when the “No” button is pressed.

Return type:

Dialog

property resizable: bool#: Can the window be resized by the user?

property resizeable: bool#: DEPRECATED Use resizable

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

Prompt the user for a location to save a file.

This dialog is not currently supported on Android or iOS.

Parameters:

title (str) – The title of the dialog window
suggested_filename (Path | str) – A default filename
file_types (list[str] | None) – The allowed filename extensions, without leading dots. If not provided, any extension will be allowed.
on_result (DialogResultHandler[Path | None] | None) – DEPRECATED await the return value of this method.

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.

Return type:

Dialog

select_folder_dialog(title: str, initial_directory: Path | str | None = None, multiple_select: Literal[False] = False, on_result: DialogResultHandler[Path | None] | None = None, multiselect=None) → Dialog#

select_folder_dialog(title: str, initial_directory: Path | str | None = None, multiple_select: Literal[True] = True, on_result: DialogResultHandler[list[Path] | None] | None = None, multiselect=None) → Dialog

Prompt the user to select a directory (or directories).

This dialog is not currently supported on Android or iOS.

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”)
multiple_select – If True, the user will be able to select multiple directories; if False, the selection will be restricted to a single directory. This option is not supported on WinForms.
on_result – DEPRECATED await the return value of this method.
multiselect – DEPRECATED Use multiple_select.

Returns:

show()#

Show the window. If the window is already visible, this method has no effect.

Return type:: None

property size: tuple[int, int]#: Size of the window, as a tuple of (width, height), in CSS pixels.

stack_trace_dialog(title: str, message: str, content: str, retry: Literal[False] = False, on_result: DialogResultHandler[None] | None = None) → Dialog#

stack_trace_dialog(title: str, message: str, content: str, retry: Literal[True] = False, on_result: DialogResultHandler[bool] | None = None) → Dialog

stack_trace_dialog(title: str, message: str, content: str, retry: bool = False, on_result: DialogResultHandler[bool | None] | None = None) → Dialog

Open a dialog to display a large block of text, 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 – If true, the user will be given options to “Retry” or “Quit”; if false, a single option to acknowledge the error will be displayed.
on_result – DEPRECATED await the return value of this method.

Returns:

An awaitable Dialog object. If retry is true, the Dialog object returns True when the user selects “Retry”, and False when they select “Quit”. If retry is false, the Dialog object returns None.

property title: str#: Title of the window. If no title is provided, the title will default to “Toga”.

property toolbar: MutableSet[Command]#: Toolbar for the window.

property visible: bool#: Is the window visible?

property widgets: Mapping[str, Widget]#

The widgets contained in the window.

Can be used to look up widgets by ID (e.g., window.widgets["my_id"]).

protocol toga.window.OnCloseHandler#

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(window, **kwargs)#

A handler to invoke when a window is about to close.

The return value of this callback controls whether the window is allowed to close. This can be used to prevent a window closing with unsaved changes, etc.

Parameters:

window (Window) – The window instance that is closing.
kwargs (Any) – Ensures compatibility with additional arguments introduced in future versions.

Returns:

True if the window is allowed to close; False if the window is not allowed to close.

Return type:

bool

protocol toga.window.DialogResultHandler#

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

__call__(window, result, **kwargs)#

A handler to invoke when a dialog is closed.

Parameters:

window (Window) – The window that opened the dialog.
result (T) – The result returned by the dialog.
kwargs (Any) – Ensures compatibility with additional arguments introduced in future versions.

Return type:

None