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
- Menu#append
- Menu#append_item
- Menu#append_menu
- Menu#append_check_item
- Menu#append_radio_item
- Menu#append_separator
- Menu#break
- Menu#check
- Menu#delete
- Menu#destroy
- Menu#enable
- Menu#find_item
- Menu#find_item_by_position
- Menu#get_help_string
- Menu#get_label
- Menu#get_label_text
- Menu#get_menu_item_count
- Menu#get_menu_items
- Menu#get_title
- Menu#insert
- Menu#insert_check_item
- Menu#insert_radio_item
- Menu#insert_separator
- Menu#is_checked
- Menu#is_enabled
- Menu#prepend
- Menu#prepend_check_item
- Menu#prepend_radio_item
- Menu#prepend_separator
- Menu#remove
- Menu#set_help_string
- Menu#set_label
- Menu#set_title
- Menu#update_ui

### Menu.new

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

Constructs a Menu object.

#### Parameters

- title A title for the popup menu: the empty string denotes no title.
- style If set to `MENU_TEAROFF`, the menu will be detachable (GTK only).

### Menu#append

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.

### Menu#append_item

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.

### Menu#append_menu

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

- id The menu command identifier.
- item The string to appear on the menu item.
- menu Pull-right submenu.
- kind May be `ITEM_SEPARATOR`, `ITEM_NORMAL`, `ITEM_CHECK` or `ITEM_RADIO`
- helpString An optional help string associated with the item. By
  default, the handler for the EVT_MENU_HIGHLIGHT event displays this
  string in the status line.
- menuItem A menuitem object. It will be owned by the Menu object
  after this function is called, so do not delete it yourself.

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

### Menu#append_check_item

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

### Menu#append_radio_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

### Menu#append_separator

MenuItem append_separator()

Adds a separator to the end of the menu.

#### See also

Menu#append, Menu#insert_separator

### Menu#break

break()

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

### Menu#check

check(%(arg-type)Integer% id, Boolean check)

Checks or unchecks the menu item.

#### Parameters

- id The menu item identifier.
- check If true, the item will be checked, otherwise it will be unchecked.

#### See also

Menu#is_checked

### Menu#delete

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

- id Id of the menu item to be deleted.
- item Menu item to be deleted.

#### See also

Menu#find_item, Menu#destroy, Menu#remove

### Menu#destroy

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

- id Id of the menu item to be deleted.
- item Menu item to be deleted.

#### See also

Menu#find_item, Menu#deletes, Menu#remove

### Menu#enable

enable(%(arg-type)Integer% id, Boolean enable)

Enables or disables (greys out) a menu item.

#### Parameters

- id The menu item identifier.
- enable true to enable the menu item, false to disable it.

#### See also

Menu#is_enabled

### Menu#find_item

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

- itemString Menu item string to find.
- id Menu item identifier.
- menu If the pointer is not NULL, it will be filled with the item’s
  parent menu (if the item was found)

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

### Menu#find_item_by_position

MenuItem find_item_by_position(%(arg-type)Integer% position)

Returns the MenuItem at the given position in the menu.

### Menu#get_help_string

String get_help_string(%(arg-type)Integer% id)

Returns the help string associated with a menu item.

#### Parameters

- id The menu item identifier.

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

### Menu#get_label

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.

### Menu#get_label_text

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

- id The menu item identifier.

#### Return value

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

#### See also

Menu#set_label

### Menu#get_menu_item_count

Integer get_menu_item_count()

Returns the number of items in the menu.

### Menu#get_menu_items

Array get_menu_items()

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

### Menu#get_title

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

### Menu#insert

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_countgetmenuitemcount is the same
as appending it.

#### See also

Menu#append, Menu#prepend

### Menu#insert_check_item

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

### Menu#insert_radio_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

### Menu#insert_separator

MenuItem insert_separator(%(arg-type)Integer% pos)

Inserts a separator at the given position.

#### See also

Menu#insert, Menu#append_separator

### Menu#is_checked

Boolean is_checked(%(arg-type)Integer% id)

Determines whether a menu item is checked.

#### Parameters

- id The menu item identifier.

#### Return value

true if the menu item is checked, false otherwise.

#### See also

Menu#check

### Menu#is_enabled

Boolean is_enabled(%(arg-type)Integer% id)

Determines whether a menu item is enabled.

#### Parameters

- id The menu item identifier.

#### Return value

true if the menu item is enabled, false otherwise.

#### See also

Menu#enable

### Menu#prepend

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

### Menu#prepend_check_item

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

### Menu#prepend_radio_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

### Menu#prepend_separator

MenuItem prepend_separator()

Inserts a separator at position $0$.

#### See also

Menu#prepend, Menu#append_separator

### Menu#remove

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

- id The identifier of the menu item to remove.
- item The menu item to remove.

#### Return value

The item which was detached from the menu.

### Menu#set_help_string

set_help_string(%(arg-type)Integer% id, String helpString)

Sets an item’s help string.

#### Parameters

- id The menu item identifier.
- helpString The help string to set.

#### See also

Menu#get_help_string

### Menu#set_label

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

Sets the label of a menu item.

#### Parameters

- id The menu item identifier.
- label The menu item label to set.

#### See also

Menu#append, Menu#get_label

### Menu#set_title

set_title(%(arg-type)String% title)

Sets the title of the menu.

#### Parameters

- title The title to set.

#### Remarks

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

#### See also

Menu#get_title

### Menu#update_ui

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]