Command#
A representation of app functionality that the user can invoke from menus or toolbars.
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 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?
- is_parent_of(child)#
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: