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.
MenuBar, Window#popup_menu, Event handling overview, FileHistory
Constructs a Menu object.
MENU_TEAROFF
, the menu will be detachable (GTK only).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.
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.
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_RADIO
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) |
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
Adds a checkable item to the end of the menu.
Menu#append, Menu#insert_check_item
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
Adds a separator to the end of the menu.
Menu#append, Menu#insert_separator
Inserts a break in a menu, causing the next appended item to appear in a new column.
Checks or unchecks the menu 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
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
Enables or disables (greys out) a menu item.
Finds the menu item id for a menu item string.
MenuItem find_item(%(arg-type)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.
Returns the MenuItem at the given position in the menu.
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
Returns the menu item label for the item identified by id. An empty
string is returned if the item was not found.
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.
Returns the number of items in the menu.
Returns the list of items in the menu. MenuItemList is a pseudo-template
list class containing MenuItem pointers.
Returns the title of the menu.
This is relevant only to popup menus, use
MenuBar#get_label_top for the menus in the
menubar.
Inserts the given item before the position pos_. Inserting the item
at position get_menu_item_countgetmenuitemcount is the same
as appending it.
Inserts a checkable item at the given position.
Menu#insert, Menu#append_check_item
Inserts a radio item at the given position.
Menu#insert, Menu#append_radio_item
Inserts a separator at the given position.
Menu#insert, Menu#append_separator
Determines whether a menu item is checked.
true if the menu item is checked, false otherwise.
Determines whether a menu item is enabled.
true if the menu item is enabled, false otherwise.
Inserts the given item at position $0$, i.e. before all the other
existing items.
Inserts a checkable item at position $0$.
Menu#prepend, Menu#append_check_item
Inserts a radio item at position $0$.
Menu#prepend, Menu#append_radio_item
Inserts a separator at position $0$.
Menu#prepend, Menu#append_separator
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.
Sets an item’s help string.
Sets the label of a menu item.
Sets the title of the menu.
This is relevant only to popup menus, use
MenuBar#set_label_top for the menus in the
menubar.
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 2023-06-09 00:45:36 +0000]