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 (
Optional
[str
]) – A unique identifier for the window. If not provided, one will be automatically generated.title (
Optional
[str
]) – 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 (
Optional
[OnCloseHandler
]) – The initialon_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
[TypeVar
(ImageT
)]) – Format to provide. Defaults toImage
; also supportsPIL.Image.Image
if Pillow is installed- Return type:
TypeVar
(ImageT
)- Returns:
An image containing the window content, in the format requested.
- 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 forclosed
which can be used to check if the window was closed.- Return type:
- 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 (
str
) – The title of the dialog window.message (
str
) – A message describing the action to be confirmed.on_result (
Optional
[DialogResultHandler
[bool
]]) – A callback that will be invoked when the user selects an option on the dialog.
- Return type:
Dialog
- Returns:
An awaitable Dialog object. The Dialog object returns
True
when the “OK” button is pressed,False
when the “Cancel” button is pressed.
- 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 (
Optional
[DialogResultHandler
[None
]]) – A callback that will be invoked when the user selects an option on the dialog.
- Return type:
Dialog
- Returns:
An awaitable Dialog object. The Dialog object returns
None
when the user presses the “OK” button.
- 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:
- 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 (
Optional
[DialogResultHandler
[None
]]) – A callback that will be invoked when the user selects an option on the dialog.
- Return type:
Dialog
- Returns:
An awaitable Dialog object. The Dialog object returns
None
when the user presses the ‘OK’ button.
- property on_close: OnCloseHandler#
The handler to invoke if the user attempts to close the window.
- open_file_dialog(title, initial_directory=None, file_types=None, multiple_select=False, on_result=None, multiselect=None)#
Prompt the user to select a file (or files) to open.
This dialog is not currently supported on Android or iOS.
- Parameters:
title (
str
) – The title of the dialog windowinitial_directory (
UnionType
[Path
,str
,None
]) – The initial folder in which to open the dialog. IfNone
, use the default location provided by the operating system (which will often be the last used location)file_types (
Optional
[list
[str
]]) – The allowed filename extensions, without leading dots. If not provided, all files will be shown.multiple_select (
bool
) – If True, the user will be able to select multiple files; if False, the selection will be restricted to a single file.on_result (
Optional
[DialogResultHandler
[UnionType
[list
[Path
],Path
,None
]]]) – A callback that will be invoked when the user selects an option on the dialog.multiselect – DEPRECATED Use
multiple_select
.
- Return type:
Dialog
- Returns:
An awaitable Dialog object. The Dialog object returns a list of
Path
objects ifmultiple_select
isTrue
, or a singlePath
otherwise. ReturnsNone
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 (
Optional
[DialogResultHandler
[bool
]]) – A callback that will be invoked when the user selects an option on the dialog.
- Return type:
Dialog
- Returns:
An awaitable Dialog object. The Dialog object returns
True
when the “Yes” button is pressed,False
when the “No” button is pressed.
- 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 windowfile_types (
Optional
[list
[str
]]) – The allowed filename extensions, without leading dots. If not provided, any extension will be allowed.on_result (
Optional
[DialogResultHandler
[Optional
[Path
]]]) – A callback that will be invoked when the user selects an option on the dialog.
- Return type:
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, multiple_select=False, on_result=None, multiselect=None)#
Prompt the user to select a directory (or directories).
This dialog is not currently supported on Android or iOS.
- Parameters:
title (
str
) – The title of the dialog windowinitial_directory (
UnionType
[Path
,str
,None
]) – The initial folder in which to open the dialog. IfNone
, use the default location provided by the operating system (which will often be “last used location”)multiple_select (
bool
) – 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 (
Optional
[DialogResultHandler
[UnionType
[list
[Path
],Path
,None
]]]) – A callback that will be invoked when the user selects an option on the dialog.multiselect – DEPRECATED Use
multiple_select
.
- Return type:
Dialog
- Returns:
An awaitable Dialog object. The Dialog object returns a list of
Path
objects ifmultiple_select
isTrue
, or a singlePath
otherwise. ReturnsNone
if the open operation is cancelled by the user.
- show()#
Show the window. If the window is already visible, this method has no effect.
- Return type:
- property size: tuple[int, int]#
Size of the window, as a tuple of
(width, height)
, in CSS pixels.
- stack_trace_dialog(title, message, content, retry=False, on_result=None)#
Open a dialog to display a large block of text, such as a stack trace.
- Parameters:
title (
str
) – The title of the dialog window.message (
str
) – Contextual information about the source of the stack trace.content (
str
) – The stack trace, pre-formatted as a multi-line string.retry (
bool
) – 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 (
Optional
[DialogResultHandler
[Optional
[bool
]]]) – A callback that will be invoked when the user selects an option on the dialog.
- Return type:
Dialog
- Returns:
An awaitable Dialog object. If
retry
is true, the Dialog object returnsTrue
when the user selects “Retry”, andFalse
when they select “Quit”. Ifretry
is false, the Dialog object returnsNone
.
- 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.
- protocol toga.window.OnCloseHandler#
-
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.