wxMenu(3)

📦

version 29.0.6 · 3 versions

💖 NAME 💖

wxMenu — bestie, picture a popup (or pull-down) list of items, yeah? One of them may get picked before the menu goes away (and clicking anywhere else dismisses the whole thing, no escape hatch). That's literally the whole concept. ✨

Oh and just so we're oriented: this is the page for wxMenu(3), the Erlang module definition. Hi. Welcome. 🫶

🌸 DESCRIPTION 🌸

Menus are your go-to for building either menu bars or popup menus. Both. Iconic.

Every menu item has an integer ID attached to it, and that ID is how you identify which thing got selected, or how you change the menu item in some way. And then there's the special little guy: an item with the identifier wxID_SEPARATOR is a separator item — it has no associated command at all, it just makes a separator line show up in the menu. It's giving decoration. It's giving ✨aesthetic✨.

Note, and this one matters: wxID_ABOUT and wxID_EXIT are predefined by wxWidgets and they have a special meaning, because entries using these IDs get taken out of the normal menus under macOS and get inserted into the system menu instead (following the appropriate macOS interface guideline). So don't be shook when they migrate. 🦋

Menu items can be one of three flavors: normal items, check items, or radio items.

Normal items — no special properties whatsoever. Just a little guy doing his job. 💅
Check items — these have a boolean flag associated with them, and they show a checkmark in the menu when the flag is set. wxWidgets automatically toggles that flag value when the item gets clicked. You can grab the value using either the isChecked/2 method of wxMenu or wxMenuBar itself, or by using wxEvent::IsChecked when you get the menu notification for the item in question. Options, options. 😌
Radio items — same energy as check items, except that when a radio item gets checked, all the other items in the same radio group get unchecked. The radio group is formed by a contiguous range of radio items — 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, whichever comes first).

Real talk warning: because radio groups are defined in terms of item positions, inserting or removing items in a menu that contains radio items risks not working correctly. 😭 Position-based grouping is fragile like that. Be careful.

🧚 Allocation strategy 🧚

All menus must be created on the heap. Periodt. Why? Because every menu attached to a menubar or to another menu will be deleted by its parent when that parent is deleted. That's the rule.

The only exception to this rule is popup menus — i.e. menus used with wxWindow:popupMenu/4 — because wxWidgets does not destroy them, specifically so you can reuse the same menu more than once. 💖

But listen, because this part trips people up: that exception applies only to the menus themselves and not to any submenus of popup menus. Those submenus are still destroyed by wxWidgets as usual, so they must be heap-allocated. No cap.

And since the frame menubar is deleted by the frame itself, it means that normally all menus you use get deleted automatically. Convenient. Slay. 👑

🎀 Event handling 🎀

Event handlers for the commands generated by menu items can be connected directly to the menu object itself using wxEvtHandler::Bind() — and heads up, that one is not implemented in wx. 🙈

If this menu is a submenu of another one, the events from its items can also be processed in the parent menu, and so on, recursively. It bubbles. It's giving generational trauma but for events. 🦋

If the menu is part of a menu bar, then events can also be handled in the wxMenuBar object.

And finally — because apparently we needed more options — menu events can also be handled in the associated window, which is either:

the wxFrame associated with the menu bar this menu belongs to, or
the window for which wxWindow:popupMenu/4 was called, for the popup menus.

See overview_events_bind for how to bind event handlers to the various objects. Go read it, it's important, I'm not even joking. 📚

See:

wxMenuBar
wxWindow:popupMenu/4
Overview events

This class is derived, and can use functions, from:

wxEvtHandler

wxWidgets docs: wxMenu

⭐ DATA TYPES ⭐

wxMenu() :: wx:wx_object().

🔥 FUNCTIONS 🔥

💜 `'Destroy'(This, Id) -> boolean()` / `'Destroy'(This, Item) -> boolean()`

'Destroy'(This, Id) -> boolean()
                   when This :: wxMenu(), Id :: integer();
               (This, Item) -> boolean()
                   when
                       This :: wxMenu(),
                       Item :: wxMenuItem:wxMenuItem().

Deletes the menu item from the menu. 💀

And if that item happens to be a submenu, it will be deleted. Like, actually gone. If you want to keep the submenu (say, to reuse it later — very main character of you), use remove/2 instead.

See:

findItem/2
delete/2
remove/2

💖 `append(This, MenuItem) -> wxMenuItem:wxMenuItem()`

append(This, MenuItem) -> wxMenuItem:wxMenuItem()
                when
                    This :: wxMenu(),
                    MenuItem :: wxMenuItem:wxMenuItem().

Adds a menu item object. 🫶

This is the most generic variant of the append/5 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. Fancy.

Remark: See the remarks for the other append/5 overloads.

See:

appendSeparator/1
appendCheckItem/4
appendRadioItem/4
insert/6
setLabel/3
getHelpString/2
setHelpString/3
wxMenuItem

✨ `append(This, Id, Item, SubMenu)` overloads

append(This, Id, Item, SubMenu) -> wxMenuItem:wxMenuItem()
                when
                    This :: wxMenu(),
                    Id :: integer(),
                    Item :: unicode:chardata(),
                    SubMenu :: wxMenu();
            (This, Id, Item, [Option]) -> wxMenuItem:wxMenuItem()
                when
                    This :: wxMenu(),
                    Id :: integer(),
                    Item :: unicode:chardata(),
                    Option ::
                        {help, unicode:chardata()} |
                        {kind, wx:wx_enum()}.

Adds a menu item. ✨

Example: or even better for stock menu items (see wxMenuItem:new/1):

Remark: This command can be used after the menu has been shown, as well as on initial creation of a menu or menubar. So yes, you can live-edit. 💅

See:

appendSeparator/1
appendCheckItem/4
appendRadioItem/4
insert/6
setLabel/3
getHelpString/2
setHelpString/3
wxMenuItem

🌸 `append(This, Id, Item, SubMenu, [Option]) -> wxMenuItem:wxMenuItem()`

append(This, Id, Item, SubMenu, [Option]) ->
                wxMenuItem:wxMenuItem()
                when
                    This :: wxMenu(),
                    Id :: integer(),
                    Item :: unicode:chardata(),
                    SubMenu :: wxMenu(),
                    Option :: {help, unicode:chardata()}.

Adds a submenu.

Deprecated: bestie, this one is deprecated. Use AppendSubMenu() — which is not implemented in wx — instead. 😭

See:

appendSeparator/1
appendCheckItem/4
appendRadioItem/4
insert/6
setLabel/3
getHelpString/2
setHelpString/3
wxMenuItem

🎀 `appendCheckItem(This, Id, Item, [Option]) -> wxMenuItem:wxMenuItem()`

appendCheckItem(This, Id, Item, [Option]) ->
                            wxMenuItem:wxMenuItem()
                            when
                                This :: wxMenu(),
                                Id :: integer(),
                                Item :: unicode:chardata(),
                                Option :: {help, unicode:chardata()}.

Adds a checkable item to the end of the menu. ✅

See:

append/5
insertCheckItem/5

🦋 `appendRadioItem(This, Id, Item, [Option]) -> wxMenuItem:wxMenuItem()`

appendRadioItem(This, Id, Item, [Option]) ->
                            wxMenuItem:wxMenuItem()
                            when
                                This :: wxMenu(),
                                Id :: integer(),
                                Item :: unicode:chardata(),
                                Option :: {help, unicode:chardata()}.

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. One wins, everyone else sits down.

Note: Radio items are not supported under wxMotif. Sorry bestie. 💀

See:

append/5
insertRadioItem/5

⭐ `appendSeparator(This) -> wxMenuItem:wxMenuItem()`

appendSeparator(This) -> wxMenuItem:wxMenuItem()
                            when This :: wxMenu().

Adds a separator to the end of the menu. A little line. A little moment of silence. ✨

See:

append/5
insertSeparator/2

🌈 `break(This) -> ok`

break(This) -> ok when This :: wxMenu().

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

Lowkey important: this function only actually inserts a break in wxMSW and does nothing under the other platforms. So on everything else it's just… vibes. 🫠

💅 `check(This, Id, Check) -> ok`

check(This, Id, Check) -> ok
               when
                   This :: wxMenu(), Id :: integer(), Check :: boolean().

Checks or unchecks the menu item. Toggle it, bestie. ☑️

See: isChecked/2

💀 `delete(This, Id) -> boolean()` / `delete(This, Item) -> boolean()`

delete(This, Id) -> boolean()
                when This :: wxMenu(), Id :: integer();
            (This, Item) -> boolean()
                when This :: wxMenu(), Item :: wxMenuItem:wxMenuItem().

Deletes the menu item from the menu.

BUT — and this is the plot twist — if the item is a submenu, it will not be deleted. 🙈 If you actually want a submenu gone gone, use 'Destroy'/2. Different functions, different consequences.

See:

findItem/2
'Destroy'/2
remove/2

🧚 `destroy(This :: wxMenu()) -> ok`

destroy(This :: wxMenu()) -> ok.

Destroys the object. Bye. 👋💖

👑 `enable(This, Id, Enable) -> ok`

enable(This, Id, Enable) -> ok
                when
                    This :: wxMenu(),
                    Id :: integer(),
                    Enable :: boolean().

Enables or disables (greys out) a menu item. Greyed out is the visual equivalent of "not right now, sweetie". 🩶

See: isEnabled/2

🔍 `findItem(This, Id) -> wxMenuItem:wxMenuItem()` / `findItem(This, ItemString) -> integer()`

findItem(This, Id) -> wxMenuItem:wxMenuItem()
                  when This :: wxMenu(), Id :: integer();
              (This, ItemString) -> integer()
                  when
                      This :: wxMenu(),
                      ItemString :: unicode:chardata().

Finds the menu id for a menu item string.

Return: Menu item identifier, or wxNOT_FOUND if none is found. 😭

Remark: Any special menu codes are stripped out of source and target strings before matching. So don't come for it about the ampersands. 💅

📍 `findItemByPosition(This, Position) -> wxMenuItem:wxMenuItem()`

findItemByPosition(This, Position) -> wxMenuItem:wxMenuItem()
                            when This :: wxMenu(), Position :: integer().

Returns the wxMenuItem given a position in the menu. Give it a number, get back a whole item. 🎁

💬 `getHelpString(This, Id) -> unicode:charlist()`

getHelpString(This, Id) -> unicode:charlist()
                       when This :: wxMenu(), Id :: integer().

Returns the help string associated with a menu item.

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

See:

setHelpString/3
append/5

🏷️ `getLabel(This, Id) -> unicode:charlist()`

getLabel(This, Id) -> unicode:charlist()
                  when This :: wxMenu(), Id :: integer().

Returns a menu item label. 🫶

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

See: setLabel/3

okay bestie, that's the end of this part — there's more coming, don't go anywhere 💖

✨ `getMenuItemCount/1` ✨

getMenuItemCount(This) -> integer() when This :: wxMenu().

Returns the number of items in the menu. That’s it, that’s the count. 💅

🦋 `getMenuItems/1` 🦋

getMenuItems(This) -> [wxMenuItem:wxMenuItem()]
                      when This :: wxMenu().

No description in the original, just the type. We love a mysterious queen. 💖

🌸 `getTitle/1` 🌸

getTitle(This) -> unicode:charlist() when This :: wxMenu().

Returns the title of the menu.

See: setTitle/2

💅 `insert` 💅

First overload:

insert(This, Pos, Id) -> wxMenuItem:wxMenuItem()
                when This :: wxMenu(), Pos :: integer(), Id :: integer();
            (This, Pos, MenuItem) -> wxMenuItem:wxMenuItem()
                when
                    This :: wxMenu(),
                    Pos :: integer(),
                    MenuItem :: wxMenuItem:wxMenuItem().

Inserts the given item before the position pos.

Inserting the item at position getMenuItemCount/1 is the same as appending it.

See:

append/5
prepend/5

Second overload:

insert(This, Pos, Id, [Option]) -> wxMenuItem:wxMenuItem()
                when
                    This :: wxMenu(),
                    Pos :: integer(),
                    Id :: integer(),
                    Option ::
                        {text, unicode:chardata()} |
                        {help, unicode:chardata()} |
                        {kind, wx:wx_enum()}.

Inserts the given item before the position pos.

Inserting the item at position getMenuItemCount/1 is the same as appending it.

See:

append/5
prepend/5

Third overload:

insert(This, Pos, Id, Text, Submenu, [Option]) ->
                wxMenuItem:wxMenuItem()
                when
                    This :: wxMenu(),
                    Pos :: integer(),
                    Id :: integer(),
                    Text :: unicode:chardata(),
                    Submenu :: wxMenu(),
                    Option :: {help, unicode:chardata()}.

Inserts the given submenu before the position pos.

text is the text shown in the menu for it and help is the help string shown in the status bar when the submenu item is selected.

See: prepend/5

🎀 `insertCheckItem` 🎀

insertCheckItem(This, Pos, Id, Item, [Option]) ->
                            wxMenuItem:wxMenuItem()
                            when
                                This :: wxMenu(),
                                Pos :: integer(),
                                Id :: integer(),
                                Item :: unicode:chardata(),
                                Option :: {help, unicode:chardata()}.

Inserts a checkable item at the given position.

See:

insert/6
appendCheckItem/4

🌈 `insertRadioItem` 🌈

insertRadioItem(This, Pos, Id, Item, [Option]) ->
                            wxMenuItem:wxMenuItem()
                            when
                                This :: wxMenu(),
                                Pos :: integer(),
                                Id :: integer(),
                                Item :: unicode:chardata(),
                                Option :: {help, unicode:chardata()}.

Inserts a radio item at the given position.

See:

insert/6
appendRadioItem/4

⭐ `insertSeparator` ⭐

insertSeparator(This, Pos) -> wxMenuItem:wxMenuItem()
                            when This :: wxMenu(), Pos :: integer().

Inserts a separator at the given position.

See:

insert/6
appendSeparator/1

🍓 `isChecked` 🍓

isChecked(This, Id) -> boolean()
                      when This :: wxMenu(), Id :: integer().

Determines whether a menu item is checked.

Return: true if the menu item is checked, false otherwise.

See: check/3

🧚 `isEnabled` 🧚

isEnabled(This, Id) -> boolean()
                      when This :: wxMenu(), Id :: integer().

Determines whether a menu item is enabled.

Return: true if the menu item is enabled, false otherwise.

See: enable/3

💫 `new` 💫

new() -> wxMenu().

Constructs a wxMenu object.

new([Option]) -> wxMenu() when Option :: {style, integer()}.

Constructs a wxMenu object.

new(Title, [Option]) -> wxMenu()
                when
                    Title :: unicode:chardata(),
                    Option :: {style, integer()}.

Constructs a wxMenu object with a title.

👑 `prepend` 👑

First overload:

prepend(This, Id) -> wxMenuItem:wxMenuItem()
                    when This :: wxMenu(), Id :: integer();
                (This, Item) -> wxMenuItem:wxMenuItem()
                    when This :: wxMenu(), Item :: wxMenuItem:wxMenuItem().

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

See:

append/5
insert/6

Second overload:

prepend(This, Id, [Option]) -> wxMenuItem:wxMenuItem()
                    when
                        This :: wxMenu(),
                        Id :: integer(),
                        Option ::
                            {text, unicode:chardata()} |
                            {help, unicode:chardata()} |
                            {kind, wx:wx_enum()}.

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

See:

append/5
insert/6

Third overload:

prepend(This, Id, Text, Submenu, [Option]) ->
                    wxMenuItem:wxMenuItem()
                    when
                        This :: wxMenu(),
                        Id :: integer(),
                        Text :: unicode:chardata(),
                        Submenu :: wxMenu(),
                        Option :: {help, unicode:chardata()}.

Inserts the given submenu at position 0.

See: insert/6

💖 `prependCheckItem` 💖

prependCheckItem(This, Id, Item, [Option]) ->
                             wxMenuItem:wxMenuItem()
                             when
                                 This :: wxMenu(),
                                 Id :: integer(),
                                 Item :: unicode:chardata(),
                                 Option :: {help, unicode:chardata()}.

Inserts a checkable item at position 0.

See:

prepend/5
appendCheckItem/4

🦋 `prependRadioItem` 🦋

prependRadioItem(This, Id, Item, [Option]) ->
                             wxMenuItem:wxMenuItem()
                             when
                                 This :: wxMenu(),
                                 Id :: integer(),
                                 Item :: unicode:chardata(),
                                 Option :: {help, unicode:chardata()}.

Inserts a radio item at position 0.

See:

prepend/5
appendRadioItem/4

🎀 `prependSeparator` 🎀

prependSeparator(This) -> wxMenuItem:wxMenuItem()
                             when This :: wxMenu().

Inserts a separator at position 0.

See:

prepend/5
appendSeparator/1

💅 `remove` 💅

remove(This, Id) -> wxMenuItem:wxMenuItem()
                   when This :: wxMenu(), Id :: integer();
               (This, Item) -> wxMenuItem:wxMenuItem()
                   when This :: wxMenu(), Item :: wxMenuItem:wxMenuItem().

Removes the menu item from the menu but doesn't delete the associated C++ object.

This allows you to reuse the same item later by adding it back to the menu (especially useful with submenus).

Return: A pointer to the item which was detached from the menu.

🌸 `setHelpString` 🌸

setHelpString(This, Id, HelpString) -> ok
                          when
                              This :: wxMenu(),
                              Id :: integer(),
                              HelpString :: unicode:chardata().

Sets an item's help string.

See: getHelpString/2

⭐ `setLabel` ⭐

setLabel(This, Id, Label) -> ok
                     when
                         This :: wxMenu(),
                         Id :: integer(),
                         Label :: unicode:chardata().

Sets the label of a menu item.

See:

append/5
getLabel/2

👑 `setTitle` 👑

setTitle(This, Title) -> ok
                     when This :: wxMenu(), Title :: unicode:chardata().

Sets the title of the menu.

Remark: Notice that you can only call this method directly for the popup menus, to change the title of a menu that is part of a menu bar you need to use wxMenuBar:setLabelTop/3.

See: getTitle/1

And that's a wrap on the wxMenu(3) page, bestie! 💖 This lil masterpiece was brought to you by Ericsson AB, version wx 2.6, and it's the wxMenu(3) page. Go slay your menus. Mwah! 💋✨

📦 where this page comes from

ubuntu stonking: erlang-doc 1:29.0.6+dfsg-1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

wxMenu(3)

💖 NAME 💖

🌸 DESCRIPTION 🌸

🧚 Allocation strategy 🧚

🎀 Event handling 🎀

⭐ DATA TYPES ⭐

🔥 FUNCTIONS 🔥

💜 'Destroy'(This, Id) -> boolean() / 'Destroy'(This, Item) -> boolean()

💖 append(This, MenuItem) -> wxMenuItem:wxMenuItem()

✨ append(This, Id, Item, SubMenu) overloads

🌸 append(This, Id, Item, SubMenu, [Option]) -> wxMenuItem:wxMenuItem()

🎀 appendCheckItem(This, Id, Item, [Option]) -> wxMenuItem:wxMenuItem()

🦋 appendRadioItem(This, Id, Item, [Option]) -> wxMenuItem:wxMenuItem()

⭐ appendSeparator(This) -> wxMenuItem:wxMenuItem()

🌈 break(This) -> ok

💅 check(This, Id, Check) -> ok

💀 delete(This, Id) -> boolean() / delete(This, Item) -> boolean()

🧚 destroy(This :: wxMenu()) -> ok

👑 enable(This, Id, Enable) -> ok

🔍 findItem(This, Id) -> wxMenuItem:wxMenuItem() / findItem(This, ItemString) -> integer()

📍 findItemByPosition(This, Position) -> wxMenuItem:wxMenuItem()

💬 getHelpString(This, Id) -> unicode:charlist()

🏷️ getLabel(This, Id) -> unicode:charlist()

✨ getMenuItemCount/1 ✨

🦋 getMenuItems/1 🦋

🌸 getTitle/1 🌸

💅 insert 💅

🎀 insertCheckItem 🎀

🌈 insertRadioItem 🌈

⭐ insertSeparator ⭐

🍓 isChecked 🍓

🧚 isEnabled 🧚

💫 new 💫

👑 prepend 👑

💖 prependCheckItem 💖

🦋 prependRadioItem 🦋

🎀 prependSeparator 🎀

💅 remove 💅

🌸 setHelpString 🌸

⭐ setLabel ⭐

👑 setTitle 👑

💜 `'Destroy'(This, Id) -> boolean()` / `'Destroy'(This, Item) -> boolean()`

💖 `append(This, MenuItem) -> wxMenuItem:wxMenuItem()`

✨ `append(This, Id, Item, SubMenu)` overloads

🌸 `append(This, Id, Item, SubMenu, [Option]) -> wxMenuItem:wxMenuItem()`

🎀 `appendCheckItem(This, Id, Item, [Option]) -> wxMenuItem:wxMenuItem()`

🦋 `appendRadioItem(This, Id, Item, [Option]) -> wxMenuItem:wxMenuItem()`

⭐ `appendSeparator(This) -> wxMenuItem:wxMenuItem()`

🌈 `break(This) -> ok`

💅 `check(This, Id, Check) -> ok`

💀 `delete(This, Id) -> boolean()` / `delete(This, Item) -> boolean()`

🧚 `destroy(This :: wxMenu()) -> ok`

👑 `enable(This, Id, Enable) -> ok`

🔍 `findItem(This, Id) -> wxMenuItem:wxMenuItem()` / `findItem(This, ItemString) -> integer()`

📍 `findItemByPosition(This, Position) -> wxMenuItem:wxMenuItem()`

💬 `getHelpString(This, Id) -> unicode:charlist()`

🏷️ `getLabel(This, Id) -> unicode:charlist()`

✨ `getMenuItemCount/1` ✨

🦋 `getMenuItems/1` 🦋

🌸 `getTitle/1` 🌸

💅 `insert` 💅

🎀 `insertCheckItem` 🎀

🌈 `insertRadioItem` 🌈

⭐ `insertSeparator` ⭐

🍓 `isChecked` 🍓

🧚 `isEnabled` 🧚

💫 `new` 💫

👑 `prepend` 👑

💖 `prependCheckItem` 💖

🦋 `prependRadioItem` 🦋

🎀 `prependSeparator` 🎀

💅 `remove` 💅

🌸 `setHelpString` 🌸

⭐ `setLabel` ⭐

👑 `setTitle` 👑