A representation of app functionality that the user can invoke from menus or toolbars.
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
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.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.
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='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
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.
- 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.
str) – A label for the command.
Group) – The group to which this command belongs.
int) – The section where the command should appear within its group.
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.
bool) – Is the Command currently enabled?
- class toga.Group(text, *, parent=None, section=0, order=0)#
An collection of commands to display together.
str) – A label for the group.
int) – The section where the group should appear within its parent. A section cannot be specified unless a parent is also specified.
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>#
- COMMANDS = <Group text='Commands' order=30>#
Default group for user-provided commands
- EDIT = <Group text='Edit' order=10>#
- FILE = <Group text='File' order=1>#
- HELP = <Group text='Help' order=100>#
- VIEW = <Group text='View' order=20>#
Content appearance commands
- WINDOW = <Group text='Window' order=90>#
Window management commands
Is this group a child of the provided group, directly or indirectly?
Is this group a parent of the provided group, directly or indirectly?
- protocol toga.command.ActionHandler#
Classes that implement this protocol must have the following methods / attributes: