# 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.