class Menu
From the point of view of the PyGUI API, a Menu is a collection of commands
that the user can invoke. The manner in which these commands are made available
to the user is platform-dependent, but typically a Menu instance will correspond
to a pull-down menu in a menu bar.
At any given moment, two sets of menus are available to the user, a set
of application-wide menus determined by the menus attribute
of the application object, and a set of window-specific menus determined
by the menus attribute of the currently active window.
A menu consists of a sequence of menu items, each of which
has the following characteristics:
- A label
- An optional keyboard equivalent
- An optional check mark
- An enabled/disabled status
- An internal command name for binding the menu item to an
action
A menu item can stand alone, or it can be part of an indexed group of items which share the same command name and are distinguished by an integer
index. Examples of uses for indexed groups include a list of window titles
in a "Windows" menu, or a list of font names in a "Font" menu.
A menu can also contain separators for dividing items into visual groupings.
The label, keyboard equivalent and command name of a stand-alone menu item
are established when the menu is created and cannot be changed thereafter,
other than by discarding the whole Menu instance and creating a new one.
In contrast, the enabled/disabled status and check mark of each item, and
the contents of indexed groups, is established dynamically during the setup
phase of menu command processing. See Menu
Setup for more information.
When a menu item is invoked by the user, its associated command name is
sent as a message up the message handling path starting from the current
target (see Event Handling). If the item
is part of an indexed group, its index is passed as a parameter of the message.
Properties
- title
- Read-only. Title of the menu, to appear in the menu bar.
Constructor
- Menu(title, item_specs)
- Creates a Menu with the given title and the specified items. The item_specs is a sequence of item specifications, each of which is one of the following:
-
- A MenuItem instance
- The string '-' (hyphen) representing a separator.
- A tuple (item_descriptor, command_name) representing a stand-alone menu item.
- A tuple ([item_descriptor, ...], command_name) representing an indexed group of
menu items.
An item descriptor is a string specifying the item's label, optionally
ending with '/' (a slash) followed by a keyboard equivalent.
The keyboard equivalent consists of a basic command character, optionally
preceded by one or more characters representing additional modifiers beyond
the platform's standard menu-command modifier key.
- The basic command character should be either an uppercase letter,
a digit, or one of the following characters: `-=[]\;',./
- An additional modifier character is one of the following:
-
- ^ (caret), representing the shift key.
- @ (at-sign), representing a platform-dependent modifier
key. On the Macintosh it is the Option key; its meaning on other platforms
is yet to be determined.
Properties
- special
- If true, then this is a menu that, by platform conventions,
should appear after other (non-special) menus in the menu bar. You
should probably not change this property yourself; it is used by the
framework code to achieve proper ordering of the standard menus.
Methods
- append(item)
- Adds an item to the end of the menu. The item should be an item specification as described above.
- extend(items)
- Adds items to the end of the menu. The items should be a sequence of item specifications as described above.
- item_with_command(command_name)
- Returns the MenuItem having the given command name, or None if there is no such item.
---