Application#

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

The app is the main entry point and container for the Toga GUI.

Usage#

The app class is used by instantiating with a name, namespace and callback to a startup delegate which takes 1 argument of the app instance.

To start a UI loop, call app.main_loop()

import toga


def build(app):
    # build UI
    pass


if __name__ == '__main__':
    app = toga.App('First App', 'org.beeware.helloworld', startup=build)
    app.main_loop()

Alternatively, you can subclass App and implement the startup method

import toga


class MyApp(toga.App):
    def startup(self):
        # build UI
        pass


if __name__ == '__main__':
    app = MyApp('First App', 'org.beeware.helloworld')
    app.main_loop()

Reference#

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

The App is the top level of any GUI program. It is the manager of all the other bits of the GUI app: the main window and events that window generates like user input.

When you create an App you need to provide it a name, an id for uniqueness (by convention, the identifier is a reversed domain name.) and an optional startup function which should run once the App has initialized. The startup function typically constructs some initial user interface.

If the name and app_id are not provided, the application will attempt to find application metadata. This process will determine the module in which the App class is defined, and look for a .dist-info file matching that name.

Once the app is created you should invoke the main_loop() method, which will hand over execution of your program to Toga to make the App interface do its thing.

The absolute minimum App would be:

>>> app = toga.App(formal_name='Empty App', app_id='org.beeware.empty')
>>> app.main_loop()

Parameters:

formal_name – The formal name of the application. Will be derived from packaging metadata if not provided.
app_id – The unique application identifier. This will usually be a reversed domain name, e.g. org.beeware.myapp. Will be derived from packaging metadata if not provided.
app_name – The name of the Python module containing the app. Will be derived from the module defining the instance of the App class if not provided.
id – The DOM identifier for the app (optional)
icon – Identifier for the application’s icon.
author – The person or organization to be credited as the author of the application. Will be derived from application metadata if not provided.
version – The version number of the app. Will be derived from packaging metadata if not provided.
home_page – A URL for a home page for the app. Used in auto-generated help menu items. Will be derived from packaging metadata if not provided.
description – A brief (one line) description of the app. Will be derived from packaging metadata if not provided.
startup – The callback method before starting the app, typically to add the components. Must be a callable that expects a single argument of App.
windows – An iterable with objects of Window that will be the app’s secondary windows.

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.

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 – A coroutine, generator or callable.

app = None#

property app_id#

The identifier for the app.

This is a reversed domain name, often used for targeting resources, etc.

Returns:: The identifier as a str.

property app_name#

The machine-readable, PEP508-compliant name of the app.

Returns:: The machine-readable app name, as a str.

property author#

The author of the app. This may be an organization name.

Returns:: The author of the app, as a str.

property current_window#: Return the currently active content window.

property description#

A brief description of the app.

Returns:: A brief description of the app, as a str.

exit()#: Quit the application gracefully.

exit_full_screen()#: Exit full screen mode.

property formal_name#

The formal name of the app.

Returns:: The formal name of the app, as a str.

hide_cursor()#: Hide cursor from view.

property home_page#

The URL of a web page for the app.

Returns:: The URL of the app’s home page, as a str.

property icon#

The Icon for the app.

Returns:: A toga.Icon instance for the app’s icon.

property id#

The DOM identifier for the app.

This id can be used to target CSS directives.

Returns:: A DOM identifier for the app.

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

main_loop()#

Invoke the application to handle user input.

This method typically only returns once the application is exiting.

property main_window#

The main window for the app.

Returns:: The main Window of the app.

property module_name#

The module name for the app.

Returns:: The module name for the app, as a str.

property name#

The formal name of the app.

Returns:: The formal name of the app, as a str.

property on_exit#

The handler to invoke before the application exits.

Returns:: The function callable that is called on application exit.

property paths#

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

Some platforms do not allow arbitrary file access to any location on disk; even when arbitrary file system access is allowed, there are “preferred” locations for some types of content.

The paths object has a set of sub-properties that return pathlib.Path instances of platform-appropriate paths on the file system.

PROPERTIES:

app – The directory containing the app’s __main__ module. This location should be considered read-only, and only used to retrieve app-specific resources (e.g., resource files bundled with the app).
data – Platform-appropriate location for user data (e.g., user settings)
cache – Platform-appropriate location for temporary files. It should be assumed that the operating system will purge the contents of this directory without warning if it needs to recover disk space.
logs – Platform-appropriate location for log files for this app.
toga – The path of the toga core module. This location should be considered read-only.

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 chrome is no longer visible.

Parameters:: windows – 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.

show_cursor()#: Show cursor.

startup()#: Create and show the main window for the application.

property version#

The version number of the app.

Returns:: The version number of the app, as a str.

visit_homepage()#

Open the application’s homepage in the default browser.

If the application metadata doesn’t define a homepage, this is a no-op.

property widgets#

The widgets collection of the entire app.

Can be used to lookup widgets over the entire app through widget id or manually iterating through it. Example: app.widgets["my_id"]

Returns:: The reference to the widgets collection of the entire app.