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
using Commands
.
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.
Defining Commands#
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
Group
object 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
Command
doesn’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.
Groups#
Toga provides a number of ready-to-use groups:
Group.APP
- Application level controlGroup.FILE
- File commandsGroup.EDIT
- Editing commandsGroup.VIEW
- Commands to alter the appearance of contentGroup.COMMANDS
- A DefaultGroup.WINDOW
- Commands for managing different windows in the appGroup.HELP
- Help content
You can also define custom groups.
Example#
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 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 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.