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