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
  1. Menu items are returned by all adding methods
    menu_item1 = my_menu.append(‘Do something’, ‘Help text’)
    evt_menu menu_item1, :on_do_something
  1. Use a menu item with a specialid
    my_menu.append(Wx::ID_OPEN, ‘&Open file’, ‘Open a file’)
  2. Handle this menu event, specifying by id
    evt_menu Wx::ID_OPEN, on_open_file

See also

MenuBar, Window#popup_menu, Event handling overview, FileHistory

Methods

Menu.new(%(arg-type)String% title = "", Integer style = 0)

Constructs a Menu object.

Parameters

MenuItem append(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)Integer% id, Boolean check)

Checks or unchecks the menu item.

Parameters

See also

Menu#is_checked

delete(%(arg-type)Integer% id) delete(%(arg-type)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(%(arg-type)Integer% id) destroy(%(arg-type)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(%(arg-type)Integer% id, Boolean enable)

Enables or disables (greys out) a menu item.

Parameters

See also

Menu#is_enabled

Integer find_item(%(arg-type)String% itemString)

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.

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(%(arg-type)Integer% position)

Returns the MenuItem at the given position in the menu.

String get_help_string(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)Integer% pos, MenuItem item) MenuItem insert(%(arg-type)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
getmenuitemcount is the same
as appending it.

See also

Menu#append, Menu#prepend

MenuItem insert_check_item(%(arg-type)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(%(arg-type)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(%(arg-type)Integer% pos)

Inserts a separator at the given position.

See also

Menu#insert, Menu#append_separator

Boolean is_checked(%(arg-type)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(%(arg-type)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(%(arg-type)MenuItem% item) MenuItem prepend(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)Integer% id) MenuItem remove(%(arg-type)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(%(arg-type)Integer% id, String helpString)

Sets an item’s help string.

Parameters

See also

Menu#get_help_string

set_label(%(arg-type)Integer% id, String label)

Sets the label of a menu item.

Parameters

See also

Menu#append, Menu#get_label

set_title(%(arg-type)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(%(arg-type)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 2023-06-09 00:45:36 +0000]