Application

macOS

GTK+

Windows

iOS

Android

Django

y

y

y

y

y

y

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 initialised. 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 autogenerated 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 toga.App.

  • windows – An iterable with objects of toga.Window that will be the app’s secondary windows.

  • factory – A python module that is capable to return a implementation of this class with the same name. (optional & normally not needed)

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 targetting 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.

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 numberof 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.