Window¶

An operating system-managed container of widgets.

Usage¶

A window is the top-level container that the operating system uses to display widgets. On desktop platforms, an instance of Window will have a title bar, but will not have a menu or toolbar. On mobile, web and console platforms, Window is a bare container with no other decoration. Subclasses of Window (such as MainWindow) add other decorations.

When first created, a window is not visible. To display it, call the show() method. The title of the window will default to the formal name of the app.

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 main_window), and that window cannot be moved, resized, or hidden. 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.
On mobile platforms, a window's state cannot be WindowState.MINIMIZED or WindowState.MAXIMIZED. Any request to move to these states will be ignored.
On Linux, when using Wayland, a request to put a window into a WindowState.MINIMIZED state, or to restore from the WindowState.MINIMIZED state, will be ignored, and any associated events like on_hide() and on_show(), will not be triggered. This is due to limitations in window management features that Wayland allows apps to use.

Reference¶

toga.Window ¶

Window(
    id=None,
    title=None,
    position=None,
    size=(640, 480),
    resizable=True,
    closable=True,
    minimizable=True,
    on_close=None,
    on_gain_focus=None,
    on_lose_focus=None,
    on_show=None,
    on_hide=None,
    content=None,
)

Create a new Window.

PARAMETER	DESCRIPTION
`id`	A unique identifier for the window. If not provided, one will be automatically generated. TYPE: `str \| None` DEFAULT: `None`
`title`	Title for the window. Defaults to the formal name of the app. TYPE: `str \| None` DEFAULT: `None`
`position`	Position of the window, as a `toga.Position` or tuple of `(x, y)` coordinates, in CSS pixels. TYPE: `PositionT \| None` DEFAULT: `None`
`size`	Size of the window, as a `toga.Size` or tuple of `(width, height)`, in CSS pixels. TYPE: `SizeT` DEFAULT: `(640, 480)`
`resizable`	Can the window be resized by the user? TYPE: `bool` DEFAULT: `True`
`closable`	Can the window be closed by the user? TYPE: `bool` DEFAULT: `True`
`minimizable`	Can the window be minimized by the user? TYPE: `bool` DEFAULT: `True`
`on_close`	The initial `on_close` handler. TYPE: `OnCloseHandler \| None` DEFAULT: `None`
`content`	The initial content for the window. TYPE: `Widget \| None` DEFAULT: `None`

app `property` `writable` ¶

app

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

New windows are automatically associated with the currently active app.

closable `property` ¶

closable

Can the window be closed by the user?

closed `property` ¶

closed

Whether the window was closed.

content `property` `writable` ¶

content

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

full_screen `property` `writable` ¶

full_screen

DEPRECATED – Use Window.state.

id `property` ¶

id

A unique identifier for the window (read-only).

minimizable `property` ¶

minimizable

Can the window be minimized by the user?

on_close `property` `writable` ¶

on_close

The handler to invoke if the user attempts to close the window.

on_gain_focus `property` `writable` ¶

on_gain_focus

The handler to invoke if the window gains input focus.

on_hide `property` `writable` ¶

on_hide

The handler to invoke if the window is hidden from a visible state.

on_lose_focus `property` `writable` ¶

on_lose_focus

The handler to invoke if the window loses input focus.

on_show `property` `writable` ¶

on_show

The handler to invoke if the window is shown from a hidden state.

position `property` `writable` ¶

position

Absolute position of the window, in CSS pixels.

The origin is the top left corner of the primary screen.

RAISES	DESCRIPTION
`RuntimeError`	If position change is requested while in `WindowState.FULLSCREEN` or `WindowState.PRESENTATION`.

resizable `property` ¶

resizable

Can the window be resized by the user?

screen `property` `writable` ¶

screen

Instance of the toga.Screen on which this window is present.

screen_position `property` `writable` ¶

screen_position

Position of the window with respect to current screen, in CSS pixels.

RAISES	DESCRIPTION
`RuntimeError`	If position change is requested while in `WindowState.FULLSCREEN` or `WindowState.PRESENTATION`.

size `property` `writable` ¶

size

Size of the window, in CSS pixels.

RAISES	DESCRIPTION
`RuntimeError`	If resize is requested while in `WindowState.FULLSCREEN` or `WindowState.PRESENTATION`.

state `property` `writable` ¶

state

The current state of the window.

When the window is in transition, then this will return the state it is transitioning towards, instead of the actual instantaneous state.

RAISES	DESCRIPTION
`RuntimeError`	If state change is requested while the window is hidden.
`ValueError`	If any state other than `WindowState.MINIMIZED` or `WindowState.NORMAL` is requested on a non-resizable window.

title `property` `writable` ¶

title

Title of the window. If no title is provided, the title will default to "Toga".

visible `property` `writable` ¶

visible

Is the window visible?

widgets `property` ¶

widgets

The widgets contained in the window.

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

as_image ¶

as_image(format=Image)

Render the current contents of the window as an image.

PARAMETER	DESCRIPTION
`format`	Format to provide. Defaults to `Image`; also supports `PIL.Image.Image` if Pillow is installed, as well as any image types defined by installed image format plugins. TYPE: `type[ImageT]` DEFAULT: `Image`

RETURNS	DESCRIPTION
`ImageT`	An image containing the window content, in the format requested.

close ¶

close()

Close the window.

This does not invoke the on_close handler. If the window being closed is the app's main window, it will trigger on_exit handling; otherwise, 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.

RETURNS	DESCRIPTION
`None`	True if the window was actually closed; False if closing the window triggered `on_exit` handling.

confirm_dialog ¶

confirm_dialog(title, message, on_result=None)

DEPRECATED - await dialog() with a ConfirmDialog

dialog `async` ¶

dialog(dialog)

Display a dialog to the user, modal to this window.

PARAMETER	DESCRIPTION
`dialog`	The toga.Window.dialog to display to the user. TYPE: `Dialog[DialogResultT]`

RETURNS	DESCRIPTION
`DialogResultT`	The result of the dialog.

error_dialog ¶

error_dialog(title, message, on_result=None)

DEPRECATED - await dialog() with an ErrorDialog

hide ¶

hide()

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

RAISES	DESCRIPTION
`ValueError`	If the window is currently in a minimized, full screen or presentation state.

info_dialog ¶

info_dialog(title, message, on_result=None)

DEPRECATED - await dialog() with an InfoDialog

open_file_dialog ¶

open_file_dialog(
    title,
    initial_directory=None,
    file_types=None,
    multiple_select=False,
    on_result=None,
)

DEPRECATED - await dialog() with an OpenFileDialog

question_dialog ¶

question_dialog(title, message, on_result=None)

DEPRECATED - await dialog() with a QuestionDialog

save_file_dialog ¶

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

DEPRECATED - await dialog() with a SaveFileDialog

select_folder_dialog ¶

select_folder_dialog(
    title, initial_directory=None, multiple_select=False, on_result=None
)

DEPRECATED - await dialog() with a SelectFolderDialog

show ¶

show()

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

RAISES	DESCRIPTION
`ValueError`	If the window is currently in a minimized, full screen or presentation state.

stack_trace_dialog ¶

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

DEPRECATED - await dialog() with a StackTraceDialog

toga.app.WindowSet ¶

WindowSet(app)

Bases: MutableSet[Window]

A collection of windows managed by an app.

A window is automatically added to the app when it is created, and removed when it is closed. Adding a window to an App's window set automatically sets the Window.app property of the Window.

toga.window.Dialog ¶

Dialog(window, on_result)

Bases: AsyncResult

toga.window.OnCloseHandler ¶

Bases: Protocol

call ¶

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

PARAMETER	DESCRIPTION
`window`	The window instance that is closing. TYPE: `Window`
`kwargs`	Ensures compatibility with arguments added in future versions. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`bool`	`True` if the window is allowed to close; `False` if the window is not allowed to close.

toga.window.DialogResultHandler ¶

Bases: Protocol[_DialogResultT]

call ¶

__call__(window, result, **kwargs)

A handler to invoke when a dialog is closed.

PARAMETER	DESCRIPTION
`window`	The window that opened the dialog. TYPE: `Window`
`result`	The result returned by the dialog. TYPE: `_DialogResultT`
`kwargs`	Ensures compatibility with arguments added in future versions. TYPE: `Any` DEFAULT: `{}`

Window¶

Usage¶

Notes¶

Reference¶

toga.Window ¶

app property writable ¶

closable property ¶

closed property ¶

content property writable ¶

full_screen property writable ¶

id property ¶

minimizable property ¶

on_close property writable ¶

on_gain_focus property writable ¶

on_hide property writable ¶

on_lose_focus property writable ¶

on_show property writable ¶

position property writable ¶

resizable property ¶

screen property writable ¶

screen_position property writable ¶

size property writable ¶

state property writable ¶

title property writable ¶

visible property writable ¶

widgets property ¶

as_image ¶

close ¶

confirm_dialog ¶

dialog async ¶

error_dialog ¶

hide ¶

info_dialog ¶

open_file_dialog ¶

question_dialog ¶

save_file_dialog ¶

select_folder_dialog ¶

show ¶

stack_trace_dialog ¶

toga.app.WindowSet ¶

toga.window.Dialog ¶

toga.window.OnCloseHandler ¶

__call__ ¶

toga.window.DialogResultHandler ¶

__call__ ¶

app `property` `writable` ¶

closable `property` ¶

closed `property` ¶

content `property` `writable` ¶

full_screen `property` `writable` ¶

id `property` ¶

minimizable `property` ¶

on_close `property` `writable` ¶

on_gain_focus `property` `writable` ¶

on_hide `property` `writable` ¶

on_lose_focus `property` `writable` ¶

on_show `property` `writable` ¶

position `property` `writable` ¶

resizable `property` ¶

screen `property` `writable` ¶

screen_position `property` `writable` ¶

size `property` `writable` ¶

state `property` `writable` ¶

title `property` `writable` ¶

visible `property` `writable` ¶

widgets `property` ¶

dialog `async` ¶

call ¶

call ¶