Command#

A representation of app functionality that the user can invoke from menus or toolbars.

Availability (Key)#

macOS

GTK

Windows

iOS

Android

Web

Terminal

●

●

●

●

Usage#

Aside from event handlers on widgets, most GUI toolkits also provide other ways for the user to give instructions to an app. In Toga, these UI patterns are supported by the Command class.

A command encapsulates a piece of functionality that the user can invoke - no matter how they invoke it. It doesn’t matter if they select a menu item, press a button on a toolbar, or use a key combination - the functionality is wrapped up in a Command.

Commands are added to an app using the properties toga.App.commands and toga.Window.toolbar. Toga then takes control of ensuring that the command is exposed to the user in a way that they can access. On desktop platforms, this may result in a command being added to a menu.

Commands can be organized into a Group of similar commands. Groups are hierarchical, so a group can contain a sub-group, which can contain a sub-group, and so on. Inside a group, commands can be organized into sections.

For example:

import toga

def callback(sender, **kwargs):
    print("Command activated")

stuff_group = Group('Stuff', order=40)

cmd1 = toga.Command(
    callback,
    label='Example command',
    tooltip='Tells you when it has been activated',
    shortcut=toga.Key.MOD_1 + 'k',
    icon='icons/pretty.png',
    group=stuff_group,
    section=0
)
cmd2 = toga.Command(
    ...
)
...

app.commands.add(cmd1, cmd4, cmd3)
app.main_window.toolbar.add(cmd2, cmd3)

This code defines a command cmd1 that will be placed in the first section of the “Stuff” group. It can be activated by pressing CTRL-k (or CMD-K on a Mac).

The definitions for cmd2, cmd3, and cmd4 have been omitted, but would follow a similar pattern.

It doesn’t matter what order you add commands to the app - the group, section and order will be used to display the commands in the right order.

If a command is added to a toolbar, it will automatically be added to the app as well. It isn’t possible to have functionality exposed on a toolbar that isn’t also exposed by the app. So, cmd2 will be added to the app, even though it wasn’t explicitly added to the app commands.

Reference#

class toga.Command(action, text, *, shortcut=None, tooltip=None, icon=None, group=Group.COMMANDS, section=0, order=0, enabled=True)#

Create a new Command.

Commands may not use all the arguments - for example, on some platforms, menus will contain icons; on other platforms they won’t.

Parameters:

  • action (ActionHandler | None) – A handler to invoke when the command is activated. If this is None, the command will be disabled.

  • text (str) – A label for the command.

  • shortcut (str | Key | None) – A key combination that can be used to invoke the command.

  • tooltip (str | None) – A short description of what the command will do.

  • icon (IconContent | None) – The icon content that can be used to decorate the command if the platform requires.

  • group (Group) – The group to which this command belongs.

  • section (int) – The section where the command should appear within its group.

  • order (int) – The position where the command should appear within its section. If multiple items have the same group, section and order, they will be sorted alphabetically by their text.

  • enabled (bool) – Is the Command currently enabled?

property enabled: bool#

Is the command currently enabled?

property icon: Icon | None#

The Icon for the command.

Can be specified as any valid icon content.

class toga.Group(text, *, parent=None, section=0, order=0)#

An collection of commands to display together.

Parameters:

  • text (str) – A label for the group.

  • parent (Group | None) – The parent of this group; use None to make a root group.

  • section (int) – The section where the group should appear within its parent. A section cannot be specified unless a parent is also specified.

  • order (int) – The position where the group should appear within its section. If multiple items have the same group, section and order, they will be sorted alphabetically by their text.

APP = <Group text='*' order=0>#

Application-level commands

COMMANDS = <Group text='Commands' order=30>#

Default group for user-provided commands

EDIT = <Group text='Edit' order=10>#

Editing commands

FILE = <Group text='File' order=1>#

File commands

HELP = <Group text='Help' order=100>#

Help commands

VIEW = <Group text='View' order=20>#

Content appearance commands

WINDOW = <Group text='Window' order=90>#

Window management commands

is_child_of(parent)#

Is this group a child of the provided group, directly or indirectly?

Parameters:

parent (Group | None) – The potential parent to check

Returns:

True if this group is a child of the provided parent.

Return type:

bool

is_parent_of(child)#

Is this group a parent of the provided group, directly or indirectly?

Parameters:

child (Group | None) – The potential child to check

Returns:

True if this group is a parent of the provided child.

Return type:

bool

property parent: Group | None#

The parent of this group; returns None if the group is a root group.

property root: Group#

The root group for this group.

This will be self if the group is a root group.

protocol toga.command.ActionHandler#

typing.Protocol.

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

__call__(command, **kwargs)#

A handler that will be invoked when a Command is invoked.

Parameters:

  • command (Command) – The command that triggered the action.

  • kwargs – Ensures compatibility with additional arguments introduced in future versions.

Return type:

bool