Window#
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
ofWidget
) – A list of widgets to add to a toolbarresizeable (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 ifmultiselect
isTrue
, or a singlePath
otherwise. ReturnsNone
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 ifmultiselect
isTrue
, or a singlePath
otherwise. ReturnsNone
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, andFalse
otherwise; if retry is not enabled, the dialog object returnsNone
.
- 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 visible#