Menu Setup
During the setup phase of menu command handling, the setup_menus
method of each component along the message handling path is called with a
menu state object. The setup_menus method uses the menu state
object to enable or disable menu commands, add or remove check marks, and
establish the contents of menu item groups.
Each setup phase begins with all menu items disabled and all check marks
removed, so it is normally only necessary to enable items and add check marks,
not disable or remove them. However, on occasion a component may want to
disable an item or remove a check mark that was enabled or added by a component
higher up in the message handling hierarchy. It can do this because the setup_menus
methods are called from the top of the message handling hierarchy to the
bottom, giving more specific handlers the chance to override menu setup decisions
made by more general ones.
Menu state objects
A menu state object consists of a collection of command state and
command group objects representing all the menu commands present in
all the currently available menus, organised by their command names.
An item can be selected from the menu state object by using the command name
as either an attribute name or an index. For example, given a menu state
object m, the state object for the command 'foo_cmd' can
be referred to as either
m.foo_cmd
or
m['foo_cmd']
Note that it is not an error to reference a non-existent command. Referring
to a command that is not currently present in the available menus returns
a dummy command state object, manipulation of which has no effect.
Command state objects
A command state object represents the state of a single menu item.
Properties
- enabled
- True if the item is to be selectable by the user.
- checked
- True if there is to be a distinguishing mark displayed beside the
menu item. The precise appearance of this is platform-dependent.
Command group objects
A command group object is a sequence object representing an indexed group
of menu items. It allows the contents of the group to be established, and
provides access to the command state objects of the individual items. It
also allows the enabled and checked status of all the items to be changed
at once.
Properties
- enabled
- checked
- Write-only. Assigning to these properties changes the corresponding
properties of all the items in the group.
Operators
- group[index]
- Read-only. Returns a command state object for the item with
the specified index.
Methods
- set_items(item_list)
- Replaces the contents of the group with a set of menu items constructed
from the item_list. Each member of the item_list should be
a "text/key" string as accepted by the Menu class
constructor.