Commands, Menus and Toolbars¶
A GUI requires more than just widgets laid out in a user interface - you’ll
also want to allow the user to actually do something. In Toga, you do this
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.
When a command is added to an application, Toga takes control of ensuring that the command is exposed to the user in a way that they can access it. On desktop platforms, this may result in a command being added to a menu.
You can also choose to add a command (or commands) to a toolbar on a specific window.
When you specify a
Command, you provide some additional metadata to help
classify and organize the commands in your application:
- An action - a function to invoke when the command is activated.
- A label - a name for the command to.
- A tooltip - a short description of what the command will do
- A shortcut - (optional) A key combination that can be used to invoke the command.
- An icon - (optional) A path to an icon resource to decorate the command.
- A group - (optional) a
Groupobject describing a collection of similar commands. If no group is specified, a default “Command” group will be used.
- A section - (optional) an integer providing a sub-grouping. If no section is specified, the command will be allocated to section 0 within the group.
- An order - (optional) an integer indicating where a command falls within a section. If a
Commanddoesn’t have an order, it will be sorted alphabetically by label within its section.
Commands may not use all the metadata - for example, on some platforms, menus will contain icons; on other platforms they won’t. Toga will use the metadata if it is provided, but ignore it (or substitute an appropriate default) if it isn’t.
Commands can be enabled and disabled; if you disable a command, it will automatically disable any toolbar or menu item where the command appears.
Toga provides a number of ready-to-use groups:
Group.APP- Application level control
Group.FILE- File commands
Group.EDIT- Editing commands
Group.VIEW- Commands to alter the appearance of content
Group.COMMANDS- A Default
Group.WINDOW- Commands for managing different windows in the app
Group.HELP- Help content
You can also define custom groups.
The following is an example of using menus and commands:
import toga def callback(sender): print("Command activated") def build(app): ... 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 put 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.