Application Back to top

Availability (Key)
macOS GTK Windows iOS Android Web Terminal

○ ○ ○ ○ ○ ○ ○

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(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=(), on_exit=None, factory=None)
Back to top
An App is the top level of any GUI program.

The App is the manager of all the other aspects of execution. An app will usually have a main
window; this window will hold the widgets with which the user will interact.

When you create an App you need to provide 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 constructs the initial user interface. If a startup function is
not provided as an argument, you must subclass the App class and define a startup() method.

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 start the event loop
of your App.

PARAMETERS:
• formal_name ( Optional [ str ]) – The formal name of the application. Will be derived from
packaging metadata if not provided.
• app_id ( Optional [ str ]) – 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 ( Optional [ str ]) – 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 ( Optional [ str ]) – The DOM identifier for the app (optional)
• icon ( UnionType [ Icon , str , None ]) – Identifier for the application’s icon.
• author ( Optional [ str ]) – The person or organization to be credited as the author of the
application. Will be derived from application metadata if not provided.
• version ( Optional [ str ]) – The version number of the app. Will be derived from packaging
metadata if not provided.
• home_page ( Optional [ str ]) – 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 ( Optional [ str ]) – A brief (one line) description of the app. Will be derived from
packaging metadata if not provided.
• startup ( Optional [ AppStartupMethod ]) – The callback method before starting the app, typically
to add the components. Must be a callable that expects a single argument of App .
• windows ( Iterable [ Window ]) – 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.

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

app = None
property app_id: str

The identifier for the app.

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

property app_name: str

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

property author: str

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

beep()

Play the default system notification sound.

RETURN TYPE:
None

property current_window

Return the currently active content window.

property description: str

A brief description of the app.

exit()

Quit the application gracefully.

RETURN TYPE:
None

exit_full_screen()

Exit full screen mode.

RETURN TYPE:
None

property formal_name: str

The formal name of the app.

hide_cursor()

Hide cursor from view.

RETURN TYPE:
None

property home_page: str

The URL of a web page for the app.

property icon: Icon

The Icon for the app.

property id: str

The DOM identifier for the app.

This id can be used to target CSS directives.

property is_full_screen: bool

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.

RETURN TYPE:
None

property main_window: MainWindow

The main window for the app.

property module_name: str | None

The module name for the app.

Back to top
property name: str

The formal name of the app.

property on_exit: OnExitHandler

The handler to invoke before the application exits.

property paths: 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.

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()

Show cursor.

RETURN TYPE:
None

startup()

Create and show the main window for the application.

RETURN TYPE:
None

property version: str

The version number of the app.

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.

RETURN TYPE:
None

property widgets: WidgetRegistry

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"] ).
 protocol toga.app.AppStartupMethod

typing.Protocol .

Back to top
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.

Note

**kwargs ensures compatibility with additional arguments introduced in future versions.

PARAMETERS:
app ( App ) – The app instance that is starting.

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.

Note

**kwargs ensures compatibility with additional arguments introduced in future versions.

Copyright © 2013, Russell Keith-Magee

PARAMETERS:
Made with Sphinx and @pradyunsg's Furo
app ( App ) – The app that is handling the background task.

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.

Note

**kwargs ensures compatibility with additional arguments introduced in future versions.

PARAMETERS:
app ( App ) – The app instance that is exiting.

RETURN TYPE:
bool

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