App#

The top-level representation of an application.

Availability (Key)#
macOS	GTK	Windows	iOS	Android	Web	Terminal
●	●	●	●	●	○	○

Usage#

The App class is the top level representation of all application activity. It is a singleton object - any given process can only have a single App. That application may manage multiple windows, but it is guaranteed to have at least one window (called the main_window); when the App’s main_window is closed, the application will exit.

The application is started by calling main_loop(). This will invoke the startup() method of the app.

import toga

app = toga.App("Simplest App", "com.example.simplest")
app.main_loop()

You can populate an app’s main window by passing a callable as the startup argument to the toga.App constructor. This startup method must return the content that will be added to the main window of the app.

import toga

def create_content(app):
    return toga.Box(children=[toga.Label("Hello!")])

app = toga.App("Simple App", "com.example.simple", startup=create_content)
app.main_loop()

This approach to app construction is most useful with simple apps. For most complex apps, you should subclass toga.App, and provide an implementation of startup(). This implementation must create and assign a main_window for the app.

import toga

class MyApp(toga.App):
    def startup(self):
        self.main_window = toga.MainWindow()
        self.main_window.content = toga.Box(children=[toga.Label("Hello!")])
        self.main_window.show()

if __name__ == '__main__':
    app = MyApp("Realistic App", "org.beeware.realistic")
    app.main_loop()

Every app must have a formal name (a human readable name), and an app ID (a machine-readable identifier - usually a reversed domain name). In the examples above, these are provided as constructor arguments. However, you can also provide these details, along with many of the other constructor arguments, as packaging metadata in a format compatible with importlib.metadata. If you deploy your app with Briefcase, this will be done automatically.

Notes#

Apps executed under Wayland on Linux environment may not show the app’s formal name correctly. Wayland considers many aspects of app operation to be the domain of the windowing environment, not the app; as a result, some API requests will be ignored under a Wayland environment. Correctly displaying the app’s formal name requires the use of a desktop metadata that Wayland can read. Packaging your app with Briefcase is one way to produce this metadata.

Reference#

class toga.App(formal_name=None, app_id=None, app_name=None, *, icon=None, author=None, version=None, home_page=None, description=None, startup=None, on_exit=None, id=None, windows=None)#

Create a new App instance.

Once the app has been created, you should invoke the main_loop() method, which will start the event loop of your App.

Parameters:

formal_name (Optional[str]) – The human-readable name of the app. If not provided, the metadata key Formal-Name must be present.
app_id (Optional[str]) – The unique application identifier. This will usually be a reversed domain name, e.g. org.beeware.myapp. If not provided, the metadata key App-ID must be present.
app_name (Optional[str]) –
The name of the distribution used to load metadata with importlib.metadata. If not provided, the following will be tried in order:
1. If the __main__ module is contained in a package, that package’s name will be used.
2. If the app_id argument was provided, its last segment will be used. For example, an app_id of com.example.my-app would yield a distribution name of my-app.
3. As a last resort, the name toga.
icon (UnionType[Icon, str, None]) – The Icon for the app. If not provided, Toga will attempt to load an icon from resources/app_name, where app_name is defined above. If no resource matching this name can be found, a warning will be printed, and the app will fall back to a default icon.
author (Optional[str]) – The person or organization to be credited as the author of the app. If not provided, the metadata key Author will be used.
version (Optional[str]) – The version number of the app. If not provided, the metadata key Version will be used.
home_page (Optional[str]) – The URL of a web page for the app. Used in auto-generated help menu items. If not provided, the metadata key Home-page will be used.
description (Optional[str]) – A brief (one line) description of the app. If not provided, the metadata key Summary will be used.
startup (Optional[AppStartupMethod]) – A callable to run before starting the app.
on_exit (Optional[OnExitHandler]) – The initial on_exit handler.
id – DEPRECATED - This argument will be ignored. If you need a machine-friendly identifier, use app_id.
windows – DEPRECATED – Windows are now automatically added to the current app. Passing this argument will cause an exception.

about()#

Display the About dialog for the app.

Default implementation shows a platform-appropriate about dialog using app metadata. Override if you want to display a custom About dialog.

Return type:: None

add_background_task(handler)#

Schedule a task to run in the background.

Schedules a coroutine or a generator to run in the background. Control will be returned to the event loop during await or yield statements, respectively. Use this to run background tasks without blocking the GUI. If a regular callable is passed, it will be called as is and will block the GUI until the call returns.

Parameters:: handler (BackgroundTask) – A coroutine, generator or callable.
Return type:: None

property app_id: str#: The unique application identifier (read-only). This will usually be a reversed domain name, e.g. org.beeware.myapp.

property app_name: str#: The name of the distribution used to load metadata with importlib.metadata (read-only).

property author: str | None#: The person or organization to be credited as the author of the app (read-only).

beep()#

Play the default system notification sound.

Return type:: None

property commands: MutableSet[Command]#: The commands available in the app.

property current_window: Window | None#: Return the currently active window.

property description: str | None#: A brief (one line) description of the app (read-only).

exit()#

Exit the application gracefully.

This does not invoke the on_exit handler; the app will be immediately and unconditionally closed.

Return type:: None

exit_full_screen()#

Exit full screen mode.

Return type:: None

property formal_name: str#: The human-readable name of the app (read-only).

hide_cursor()#

Hide cursor from view.

Return type:: None

property home_page: str | None#: The URL of a web page for the app (read-only). Used in auto-generated help menu items.

property icon: Icon#

The Icon for the app.

When setting the icon, you can provide either an Icon instance, or a path that will be passed to the Icon constructor.

property id: str#: DEPRECATED – Use app_id.

property is_full_screen: bool#: Is the app currently in full screen mode?

property loop: AbstractEventLoop#: The event loop of the app’s main thread (read-only).

main_loop()#

Start the application.

On desktop platforms, this method will block until the application has exited. On mobile and web platforms, it returns immediately.

Return type:: None

property main_window: MainWindow#: The main window for the app.

property name: str#: DEPRECATED – Use formal_name.

property on_exit: OnExitHandler#: The handler to invoke if the user attempts to exit the app.

property paths: Paths#

Paths for platform-appropriate locations on the user’s file system.

Some platforms do not allow access to any file system location other than these paths. Even when arbitrary file access is allowed, there are preferred locations for each type of content.

set_full_screen(*windows)#

Make one or more windows full screen.

Full screen is not the same as “maximized”; full screen mode is when all window borders and other window decorations are no longer visible.

Parameters:: windows (Window) – The list of windows to go full screen, in order of allocation to screens. If the number of windows exceeds the number of available displays, those windows will not be visible. If no windows are specified, the app will exit full screen mode.
Return type:: None

show_cursor()#

Make the cursor visible.

Return type:: None

startup()#

Create and show the main window for the application.

Subclasses can override this method to define customized startup behavior; however, any override must ensure the main_window has been assigned before it returns.

Return type:: None

property version: str | None#: The version number of the app (read-only).

visit_homepage()#

Open the application’s home_page in the default browser.

If the home_page is None, this is a no-op.

Return type:: None

property widgets: Mapping[str, Widget]#

The widgets managed by the app, over all windows.

Can be used to look up widgets by ID over the entire app (e.g., app.widgets["my_id"]).

property windows: Collection[Window]#: The windows managed by the app. Windows are automatically added to the app when they are created, and removed when they are closed.

protocol toga.app.AppStartupMethod#

typing.Protocol.

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

__call__(app, **kwargs)#

The startup method of the app.

Called during app startup to set the initial main window content.

Parameters:

app (App) – The app instance that is starting.
kwargs (Any) – Ensures compatibility with additional arguments introduced in future versions.

Return type:

Widget

Returns:

The widget to use as the main window content.

protocol toga.app.BackgroundTask#

typing.Protocol.

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

__call__(app, **kwargs)#

Code that should be executed as a background task.

Parameters:

app (App) – The app that is handling the background task.
kwargs (Any) – Ensures compatibility with additional arguments introduced in future versions.

Return type:

None

protocol toga.app.OnExitHandler#

typing.Protocol.

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

__call__(app, **kwargs)#

A handler to invoke when the app is about to exit.

The return value of this callback controls whether the app is allowed to exit. This can be used to prevent the app exiting with unsaved changes, etc.

Parameters:

app (App) – The app instance that is exiting.
kwargs (Any) – Ensures compatibility with additional arguments introduced in future versions.

Return type:

bool

Returns:

True if the app is allowed to exit; False if the app is not allowed to exit.