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.
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.
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.
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.
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_fileMenuBar, Window#popup_menu, Event handling overview, FileHistory
Menu.new(String title = "", Integer style = 0)Constructs a Menu object.
MENU_TEAROFF, the menu will be detachable (GTK only).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.
ITEM_SEPARATOR, ITEM_NORMAL, ITEM_CHECK or ITEM_RADIOThis 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) |
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.
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
Menu#append, Menu#insert_radio_item
MenuItem append_separator()Adds a separator to the end of the menu.
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.
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.
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).
Menu#find_item, Menu#deletes, Menu#remove
enable(Integer id, Boolean enable)Enables or disables (greys out) a menu item.
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.
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.
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.
The help string, or the empty string if there is no help string or the item was not found.
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.
The item label, or the empty string if the item was not found.
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.
This is relevant only to popup menus, use MenuBar#get_label_top for the menus in the menubar.
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.
MenuItem insert_check_item(Integer pos,
Integer id = Wx::ID_ANY,
String item,
String helpString = "")Inserts a checkable item at the given position.
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.
Menu#insert, Menu#append_radio_item
MenuItem insert_separator(Integer pos)Inserts a separator at the given position.
Menu#insert, Menu#append_separator
Boolean is_checked(Integer id)Determines whether a menu item is checked.
true if the menu item is checked, false otherwise.
Boolean is_enabled(Integer id)Determines whether a menu item is enabled.
true if the menu item is enabled, false otherwise.
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.
MenuItem prepend_check_item(Integer id = Wx::ID_ANY,
String item,
String helpString = "")Inserts a checkable item at position $0$.
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$.
Menu#prepend, Menu#append_radio_item
MenuItem prepend_separator()Inserts a separator at position $0$.
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).
The item which was detached from the menu.
set_help_string(Integer id, String helpString)Sets an item’s help string.
set_label(Integer id, String label)Sets the label of a menu item.
set_title(String title)Sets the title of the menu.
This is relevant only to popup menus, use MenuBar#set_label_top for the menus in the menubar.
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.
[This page automatically generated from the Textile source at Thu May 01 00:50:41 +0100 2008]