wxRuby Documentation Home

Wx::Menu

A menu is a pull-down or pop-up list of items. The Wx::Menu class may be used to construct either menu bars (associated with a Frame via its Menubar ) or popup menus. Items are represented as text, and some platforms, they may also have icons. One item is selected by clicking on it, or by using a key shortcut, to start an application action. Clicking elsewhere dismisses the menu.

A menu item has an integer ID associated with it is used to identify it when it is clicked, and to access and change the menu item after it has been created (for example, disabling or enabling items in response to particular application states). In common with other parts of the wxRuby API, it is not always necessary to give explicit ids; it can omitted, and wxRuby will supply a reasonable, unique default. These can be used to set up event handling for Menus.

Special Menu Ids

There are cases where it is desirable to explicitly set the id to one of the special constants built into wxRuby, in order to get better native appearance and behaviour across different window systems.

Most importantly, Wx::ID_ABOUT and Wx::ID_EXIT are predefined and have special meaning: “Display an About dialog” and “Exit the application”. If these ids are used, the menu items will be taken out of the normal menus under MacOS X and will be inserted into the ‘system’ (Apple) menu, following the appropriate MacOS X interface guideline. In addition, they will be given the standard label (‘Quit’, on OS X, ‘Exit’, on GTK and Windows).

Secondly, predefined ids corresponding to a set of common application actions are also available, such as Wx::ID_SAVE, Wx::ID_CUT and Wx::ID_PROPERTIES. If these are used as the ids for the relevant items in Frame menus, they will be displayed with the GTK-theme supplied system standard icon.

See also, the list of standard ids.

Types of menu item

Menu items may be either normal items, check items or radio items. Normal items don’t have any special properties. Check items have a boolean flag associated to them and they show a checkmark in the menu when the flag is set. Widgets automatically toggles the flag value when the item is clicked and its value may be retrieved using either is_checked method of Menu or MenuBar itself or by using Event#is_checked when you get the menu notification for the item in question.

The radio items are similar to the check items except that all the other items in the same radio group are unchecked when a radio item is checked. The radio group is formed by a contiguous range of radio items, i.e. it starts at the first item of this kind and ends with the first item of a different kind (or the end of the menu). Notice that because the radio groups are defined in terms of the item positions inserting or removing the items in the menu containing the radio items risks to not work correctly. Finally note that radio items are not supported under Motif.

Derived from

EvtHandler

Object

Event handling

The event of the user selecting an item from a menu can be captured by the evt_menu handler. This is used whether the Menu is part of a Frame’s MenuBar, or whether it is a standalone pop-up menu. This event handler receives events of type CommandEvent.

As with other CommandEvents , the event “bubbles” upwards through the containing windows, so the event handlers can be set up in the containing frame. And, as with other CommandEvents, evt_menu must be told which MenuItem’s events it should listen for. It can be passed either a MenuItem object, or the integer id of a menu item.

Note that there are also events fired when a menu in a menubar is opened up by the user, of class MenuEvent. However, these are rarely required in practice.

Event Handling Example

my_menu = Wx::Menu.new
menu_item1 = my_menu.append('Do something', 'Help text')
evt_menu menu_item1, :on_do_something
my_menu.append(Wx::ID_OPEN, '&Open file', 'Open a file')
 # Handle this menu event, specifying by id
evt_menu Wx::ID_OPEN, on_open_file
# Use a menu item with a specialid

See also

MenuBar, Window#popup_menu, Event handling overview, FileHistory

Methods

Menu.new(String title = "",  Integer style = 0)

Constructs a Menu object.

Parameters

MenuItem append(Integer id = Wx::ID_ANY,
                                 String item = "", 
                                 String helpString = "", 
                                 ItemKind kind = Wx::ITEM_NORMAL)

Adds a string item to the end of the menu. Note that the only required item is the string label for the menu item; if the id is omitted, wxRuby will supply a reasonable default.

MenuItem append_item(MenuItem menuItem)

Adds a MenuItem object. This is the most generic variant of Append() method because it may be used for both items (including separators) and submenus and because you can also specify various extra properties of a menu item this way, such as bitmaps and fonts.

MenuItem append_menu(Integer id = Wx::ID_ANY, 
                                       String item, 
                                       Menu subMenu, 
                                       String helpString = "")

Adds a pull-right submenu to the end of the menu. Append the submenu to the parent menu after you have added your menu items, or accelerators may not be registered properly.

Parameters

Remarks

This command can be used after the menu has been shown, as well as on initial creation of a menu or menubar.

The item string for the normal menu items (not submenus or separators) may include the accelerator which can be used to activate the menu item from keyboard. The accelerator string follows the item label and is separated from it by a TAB character ”\t”. Its general syntax is any combination of CTRL, ALT and SHIFT strings (case doesn’t matter) separated by either '-' or '+' characters and followed by the accelerator itself. The accelerator may be any alphanumeric character, any function key (from F1 to F12) or one of the special characters listed in the table below (again, case doesn’t matter):

DEL or DELETE Delete key
INS or INSERT Insert key
ENTER or RETURN Enter key
PGUP PageUp key
PGDN PageDown key
LEFT Left cursor arrow key
RIGHT Right cursor arrow key
UP Up cursor arrow key
DOWN Down cursor arrow key
HOME Home key
END End key
SPACE Space
TAB Tab key
ESC or ESCAPE Escape key (Windows only)

See also

Menu#append_separator, Menu#append_check_item, Menu#append_radio_item, Menu#insert, Menu#set_label, Menu#get_help_string, Menu#set_help_string, MenuItem

MenuItem append_check_item(Integer id = Wx::ID_ANY,  
                                             String item, 
                                             String helpString = "")

Adds a checkable item to the end of the menu.

See also

Menu#append, Menu#insert_check_item

MenuItem append_radio_item(Integer id = Wx::ID_ANY,  
                                             String item, 
                                             String helpString = "")

Adds a radio item to the end of the menu. All consequent radio items form a group and when an item in the group is checked, all the others are automatically unchecked.

Currently only implemented under Windows and GTK

See also

Menu#append, Menu#insert_radio_item

MenuItem append_separator()

Adds a separator to the end of the menu.

See also

Menu#append, Menu#insert_separator

break()

Inserts a break in a menu, causing the next appended item to appear in a new column.

check(Integer id,  Boolean check)

Checks or unchecks the menu item.

Parameters

See also

Menu#is_checked

delete(Integer id)
delete(MenuItem item)

Deletes the menu item from the menu. If the item is a submenu, it will not be deleted. Use Destroy if you want to delete a submenu.

Parameters

See also

Menu#find_item, Menu#destroy, Menu#remove

destroy(Integer id)
destroy(MenuItem item)

Deletes the menu item from the menu. If the item is a submenu, it will be deleted. Use Remove if you want to keep the submenu (for example, to reuse it later).

Parameters

See also

Menu#find_item, Menu#deletes, Menu#remove

enable(Integer id,  Boolean enable)

Enables or disables (greys out) a menu item.

Parameters

See also

Menu#is_enabled

Integer find_item(String itemString)

Finds the menu item id for a menu item string.

MenuItem find_item(Integer id,  Menu menu = nil)

Finds the menu item object associated with the given menu item identifier and, optionally, the (sub)menu it belongs to.

Parameters

Return value

First form: menu item identifier, or NOT_FOUND if none is found.

Second form: returns the MenuItem object, or NULL if it is not found.

Remarks

Any special menu codes are stripped out of source and target strings before matching.

MenuItem find_item_by_position(Integer position)

Returns the MenuItem at the given position in the menu.

String get_help_string(Integer id)

Returns the help string associated with a menu item.

Parameters

Return value

The help string, or the empty string if there is no help string or the item was not found.

See also

Menu#set_help_string, Menu#append

String get_label(Integer id)

Returns the menu item label for the item identified by id. An empty string is returned if the item was not found.

String get_label_text(Integer id)

Returns a menu item label, without any of the original mnemonics and accelerators. An empty string is returned if the item was not found.

Parameters

Return value

The item label, or the empty string if the item was not found.

See also

Menu#set_label

Integer get_menu_item_count()

Returns the number of items in the menu.

Array get_menu_items()

Returns the list of items in the menu. MenuItemList is a pseudo-template list class containing MenuItem pointers.

String get_title()

Returns the title of the menu.

Remarks

This is relevant only to popup menus, use MenuBar#get_label_top for the menus in the menubar.

See also

Menu#set_title

MenuItem insert(Integer pos,  
                                  MenuItem item)
MenuItem insert(Integer pos,  
                                  Integer id = Wx::ID_ANY, 
                                  String item, 
                                  String helpString = "", 
                                  ItemKind kind = ITEM_NORMAL)

Inserts the given item before the position pos. Inserting the item at position get_menu_item_count is the same as appending it.

See also

Menu#append, Menu#prepend

MenuItem insert_check_item(Integer pos,  
                                             Integer id = Wx::ID_ANY, 
                                             String item, 
                                             String helpString = "")

Inserts a checkable item at the given position.

See also

Menu#insert, Menu#append_check_item

MenuItem insert_radio_item(Integer pos,  
                                             Integer id = Wx::ID_ANY, 
                                             String item, 
                                             String helpString = "")

Inserts a radio item at the given position.

See also

Menu#insert, Menu#append_radio_item

MenuItem insert_separator(Integer pos)

Inserts a separator at the given position.

See also

Menu#insert, Menu#append_separator

Boolean is_checked(Integer id)

Determines whether a menu item is checked.

Parameters

Return value

true if the menu item is checked, false otherwise.

See also

Menu#check

Boolean is_enabled(Integer id)

Determines whether a menu item is enabled.

Parameters

Return value

true if the menu item is enabled, false otherwise.

See also

Menu#enable

MenuItem prepend(MenuItem item)
MenuItem prepend(Integer id = Wx::ID_ANY,  
                                   String item, 
                                   String helpString = "", 
                                   ItemKind kind = ITEM_NORMAL)

Inserts the given item at position $0$, i.e. before all the other existing items.

See also

Menu#append, Menu#insert

MenuItem prepend_check_item(Integer id = Wx::ID_ANY,  
                                              String item,
                                              String helpString = "")

Inserts a checkable item at position $0$.

See also

Menu#prepend, Menu#append_check_item

MenuItem prepend_radio_item(Integer id = Wx::ID_ANY, 
                                              String item, 
                                              String helpString = "")

Inserts a radio item at position $0$.

See also

Menu#prepend, Menu#append_radio_item

MenuItem prepend_separator()

Inserts a separator at position $0$.

See also

Menu#prepend, Menu#append_separator

MenuItem remove(Integer id)
MenuItem remove(MenuItem item)

Removes the menu item from the menu but doesn’t delete the associated C++ object. This allows to reuse the same item later by adding it back to the menu (especially useful with submenus).

Parameters

Return value

The item which was detached from the menu.

set_help_string(Integer id,  String helpString)

Sets an item’s help string.

Parameters

See also

Menu#get_help_string

set_label(Integer id,  String label)

Sets the label of a menu item.

Parameters

See also

Menu#append, Menu#get_label

set_title(String title)

Sets the title of the menu.

Parameters

Remarks

This is relevant only to popup menus, use MenuBar#set_label_top for the menus in the menubar.

See also

Menu#get_title

update_ui(EvtHandler source = nil)

Sends events to source (or owning window if NULL) to update the menu UI. This is called just before the menu is popped up with Window#popup_menu, but the application may call it at other times if required.

See also

UpdateUIEvent

[This page automatically generated from the Textile source at Wed Sep 09 02:21:17 +0100 2009]