Table of Contents

Class NativeMenu

A server interface for OS native menus.

Inheritance
NativeMenu

Remarks

NativeMenu handles low-level access to the OS native global menu bar and popup menus.

Note: This is low-level API, consider using MenuBar with prefer_global_menu set to true, and PopupMenu with prefer_native_menu set to true.

To create a menu, use create_menu, add menu items using add_*_item methods. To remove a menu, use NativeMenu.free_menu.

var menu

func _menu_callback(item_id):
    if item_id == "ITEM_CUT":
        cut()
    elif item_id == "ITEM_COPY":
        copy()
    elif item_id == "ITEM_PASTE":
        paste()

func _enter_tree():
    # Create new menu and add items:
    menu = NativeMenu.create_menu()
    NativeMenu.add_item(menu, "Cut", _menu_callback, Callable(), "ITEM_CUT")
    NativeMenu.add_item(menu, "Copy", _menu_callback, Callable(), "ITEM_COPY")
    NativeMenu.add_separator(menu)
    NativeMenu.add_item(menu, "Paste", _menu_callback, Callable(), "ITEM_PASTE")

func _on_button_pressed():
    # Show popup menu at mouse position:
    NativeMenu.popup(menu, DisplayServer.mouse_get_position())

func _exit_tree():
    # Remove menu when it's no longer needed:
    NativeMenu.free_menu(menu)

Methods

add_check_item(RID, String, Callable, Callable, Variant, int, int)

Adds a new checkable item with text label to the global menu rid.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

An accelerator can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The accelerator is generally a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).

Note: The callback and key_callback Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to tag.

Note: This method is implemented on macOS and Windows.

Note: On Windows, accelerator and key_callback are ignored.

int add_check_item(RID rid, String label, Callable callback, Callable key_callback, Variant tag, int accelerator, int index)

Parameters

rid RID
label String
callback Callable
key_callback Callable
tag Variant
accelerator int
index int

add_icon_check_item(RID, Texture2D, String, Callable, Callable, Variant, int, int)

Adds a new checkable item with text label and icon icon to the global menu rid.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

An accelerator can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The accelerator is generally a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).

Note: The callback and key_callback Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to tag.

Note: This method is implemented on macOS and Windows.

Note: On Windows, accelerator and key_callback are ignored.

int add_icon_check_item(RID rid, Texture2D icon, String label, Callable callback, Callable key_callback, Variant tag, int accelerator, int index)

Parameters

rid RID
icon Texture2D
label String
callback Callable
key_callback Callable
tag Variant
accelerator int
index int

add_icon_item(RID, Texture2D, String, Callable, Callable, Variant, int, int)

Adds a new item with text label and icon icon to the global menu rid.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

An accelerator can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The accelerator is generally a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).

Note: The callback and key_callback Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to tag.

Note: This method is implemented on macOS and Windows.

Note: On Windows, accelerator and key_callback are ignored.

int add_icon_item(RID rid, Texture2D icon, String label, Callable callback, Callable key_callback, Variant tag, int accelerator, int index)

Parameters

rid RID
icon Texture2D
label String
callback Callable
key_callback Callable
tag Variant
accelerator int
index int

add_icon_radio_check_item(RID, Texture2D, String, Callable, Callable, Variant, int, int)

Adds a new radio-checkable item with text label and icon icon to the global menu rid.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

An accelerator can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The accelerator is generally a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).

Note: Radio-checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See NativeMenu.set_item_checked for more info on how to control it.

Note: The callback and key_callback Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to tag.

Note: This method is implemented on macOS and Windows.

Note: On Windows, accelerator and key_callback are ignored.

int add_icon_radio_check_item(RID rid, Texture2D icon, String label, Callable callback, Callable key_callback, Variant tag, int accelerator, int index)

Parameters

rid RID
icon Texture2D
label String
callback Callable
key_callback Callable
tag Variant
accelerator int
index int

add_item(RID, String, Callable, Callable, Variant, int, int)

Adds a new item with text label to the global menu rid.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

An accelerator can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The accelerator is generally a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).

Note: The callback and key_callback Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to tag.

Note: This method is implemented on macOS and Windows.

Note: On Windows, accelerator and key_callback are ignored.

int add_item(RID rid, String label, Callable callback, Callable key_callback, Variant tag, int accelerator, int index)

Parameters

rid RID
label String
callback Callable
key_callback Callable
tag Variant
accelerator int
index int

add_multistate_item(RID, String, int, int, Callable, Callable, Variant, int, int)

Adds a new item with text label to the global menu rid.

Contrarily to normal binary items, multistate items can have more than two states, as defined by max_states. Each press or activate of the item will increase the state by one. The default value is defined by default_state.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

An accelerator can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The accelerator is generally a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).

Note: By default, there's no indication of the current item state, it should be changed manually.

Note: The callback and key_callback Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to tag.

Note: This method is implemented on macOS and Windows.

Note: On Windows, accelerator and key_callback are ignored.

int add_multistate_item(RID rid, String label, int max_states, int default_state, Callable callback, Callable key_callback, Variant tag, int accelerator, int index)

Parameters

rid RID
label String
max_states int
default_state int
callback Callable
key_callback Callable
tag Variant
accelerator int
index int

add_radio_check_item(RID, String, Callable, Callable, Variant, int, int)

Adds a new radio-checkable item with text label to the global menu rid.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

An accelerator can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The accelerator is generally a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).

Note: Radio-checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See NativeMenu.set_item_checked for more info on how to control it.

Note: The callback and key_callback Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to tag.

Note: This method is implemented on macOS and Windows.

Note: On Windows, accelerator and key_callback are ignored.

int add_radio_check_item(RID rid, String label, Callable callback, Callable key_callback, Variant tag, int accelerator, int index)

Parameters

rid RID
label String
callback Callable
key_callback Callable
tag Variant
accelerator int
index int

add_separator(RID, int)

Adds a separator between items to the global menu rid. Separators also occupy an index.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

Note: This method is implemented on macOS and Windows.

int add_separator(RID rid, int index)

Parameters

rid RID
index int

add_submenu_item(RID, String, RID, Variant, int)

Adds an item that will act as a submenu of the global menu rid. The submenu_rid argument is the RID of the global menu that will be shown when the item is clicked.

Returns index of the inserted item, it's not guaranteed to be the same as index value.

Note: This method is implemented on macOS and Windows.

int add_submenu_item(RID rid, String label, RID submenu_rid, Variant tag, int index)

Parameters

rid RID
label String
submenu_rid RID
tag Variant
index int

clear(RID)

Removes all items from the global menu rid.

Note: This method is implemented on macOS and Windows.

void clear(RID rid)

Parameters

rid RID

create_menu

Creates a new global menu object.

Note: This method is implemented on macOS and Windows.

RID create_menu

find_item_index_with_submenu(RID, RID)

Qualifiers: const

Returns the index of the item with the submenu specified by submenu_rid. Indices are automatically assigned to each item by the engine, and cannot be set manually.

Note: This method is implemented on macOS and Windows.

int find_item_index_with_submenu(RID rid, RID submenu_rid)

Parameters

rid RID
submenu_rid RID

find_item_index_with_tag(RID, Variant)

Qualifiers: const

Returns the index of the item with the specified tag. Indices are automatically assigned to each item by the engine, and cannot be set manually.

Note: This method is implemented on macOS and Windows.

int find_item_index_with_tag(RID rid, Variant tag)

Parameters

rid RID
tag Variant

find_item_index_with_text(RID, String)

Qualifiers: const

Returns the index of the item with the specified text. Indices are automatically assigned to each item by the engine, and cannot be set manually.

Note: This method is implemented on macOS and Windows.

int find_item_index_with_text(RID rid, String text)

Parameters

rid RID
text String

free_menu(RID)

Frees a global menu object created by this NativeMenu.

Note: This method is implemented on macOS and Windows.

void free_menu(RID rid)

Parameters

rid RID

get_item_accelerator(RID, int)

Qualifiers: const

Returns the accelerator of the item at index idx. Accelerators are special combinations of keys that activate the item, no matter which control is focused.

Note: This method is implemented only on macOS.

int get_item_accelerator(RID rid, int idx)

Parameters

rid RID
idx int

get_item_callback(RID, int)

Qualifiers: const

Returns the callback of the item at index idx.

Note: This method is implemented on macOS and Windows.

Callable get_item_callback(RID rid, int idx)

Parameters

rid RID
idx int

get_item_count(RID)

Qualifiers: const

Returns number of items in the global menu rid.

Note: This method is implemented on macOS and Windows.

int get_item_count(RID rid)

Parameters

rid RID

get_item_icon(RID, int)

Qualifiers: const

Returns the icon of the item at index idx.

Note: This method is implemented on macOS and Windows.

Texture2D get_item_icon(RID rid, int idx)

Parameters

rid RID
idx int

get_item_indentation_level(RID, int)

Qualifiers: const

Returns the horizontal offset of the item at the given idx.

Note: This method is implemented only on macOS.

int get_item_indentation_level(RID rid, int idx)

Parameters

rid RID
idx int

get_item_key_callback(RID, int)

Qualifiers: const

Returns the callback of the item accelerator at index idx.

Note: This method is implemented only on macOS.

Callable get_item_key_callback(RID rid, int idx)

Parameters

rid RID
idx int

get_item_max_states(RID, int)

Qualifiers: const

Returns number of states of a multistate item. See NativeMenu.add_multistate_item for details.

Note: This method is implemented on macOS and Windows.

int get_item_max_states(RID rid, int idx)

Parameters

rid RID
idx int

get_item_state(RID, int)

Qualifiers: const

Returns the state of a multistate item. See NativeMenu.add_multistate_item for details.

Note: This method is implemented on macOS and Windows.

int get_item_state(RID rid, int idx)

Parameters

rid RID
idx int

get_item_submenu(RID, int)

Qualifiers: const

Returns the submenu ID of the item at index idx. See NativeMenu.add_submenu_item for more info on how to add a submenu.

Note: This method is implemented on macOS and Windows.

RID get_item_submenu(RID rid, int idx)

Parameters

rid RID
idx int

get_item_tag(RID, int)

Qualifiers: const

Returns the metadata of the specified item, which might be of any type. You can set it with NativeMenu.set_item_tag, which provides a simple way of assigning context data to items.

Note: This method is implemented on macOS and Windows.

Variant get_item_tag(RID rid, int idx)

Parameters

rid RID
idx int

get_item_text(RID, int)

Qualifiers: const

Returns the text of the item at index idx.

Note: This method is implemented on macOS and Windows.

String get_item_text(RID rid, int idx)

Parameters

rid RID
idx int

get_item_tooltip(RID, int)

Qualifiers: const

Returns the tooltip associated with the specified index idx.

Note: This method is implemented only on macOS.

String get_item_tooltip(RID rid, int idx)

Parameters

rid RID
idx int

get_minimum_width(RID)

Qualifiers: const

Returns global menu minimum width.

Note: This method is implemented only on macOS.

float get_minimum_width(RID rid)

Parameters

rid RID

get_popup_close_callback(RID)

Qualifiers: const

Returns global menu close callback.

Note: This method is implemented on macOS and Windows.

Callable get_popup_close_callback(RID rid)

Parameters

rid RID

get_popup_open_callback(RID)

Qualifiers: const

Returns global menu open callback.

Note: This method is implemented only on macOS.

Callable get_popup_open_callback(RID rid)

Parameters

rid RID

get_size(RID)

Qualifiers: const

Returns global menu size.

Note: This method is implemented on macOS and Windows.

Vector2 get_size(RID rid)

Parameters

rid RID

get_system_menu(int)

Qualifiers: const

Returns RID of a special system menu.

Note: This method is implemented only on macOS.

RID get_system_menu(int menu_id)

Parameters

menu_id int

get_system_menu_name(int)

Qualifiers: const

Returns readable name of a special system menu.

Note: This method is implemented only on macOS.

String get_system_menu_name(int menu_id)

Parameters

menu_id int

has_feature(int)

Qualifiers: const

Returns true if the specified feature is supported by the current NativeMenu, false otherwise.

Note: This method is implemented on macOS and Windows.

bool has_feature(int feature)

Parameters

feature int

has_menu(RID)

Qualifiers: const

Returns true if rid is valid global menu.

Note: This method is implemented on macOS and Windows.

bool has_menu(RID rid)

Parameters

rid RID

has_system_menu(int)

Qualifiers: const

Returns true if a special system menu is supported.

Note: This method is implemented only on macOS.

bool has_system_menu(int menu_id)

Parameters

menu_id int

is_item_checkable(RID, int)

Qualifiers: const

Returns true if the item at index idx is checkable in some way, i.e. if it has a checkbox or radio button.

Note: This method is implemented on macOS and Windows.

bool is_item_checkable(RID rid, int idx)

Parameters

rid RID
idx int

is_item_checked(RID, int)

Qualifiers: const

Returns true if the item at index idx is checked.

Note: This method is implemented on macOS and Windows.

bool is_item_checked(RID rid, int idx)

Parameters

rid RID
idx int

is_item_disabled(RID, int)

Qualifiers: const

Returns true if the item at index idx is disabled. When it is disabled it can't be selected, or its action invoked.

See NativeMenu.set_item_disabled for more info on how to disable an item.

Note: This method is implemented on macOS and Windows.

bool is_item_disabled(RID rid, int idx)

Parameters

rid RID
idx int

is_item_hidden(RID, int)

Qualifiers: const

Returns true if the item at index idx is hidden.

See NativeMenu.set_item_hidden for more info on how to hide an item.

Note: This method is implemented only on macOS.

bool is_item_hidden(RID rid, int idx)

Parameters

rid RID
idx int

is_item_radio_checkable(RID, int)

Qualifiers: const

Returns true if the item at index idx has radio button-style checkability.

Note: This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups.

Note: This method is implemented on macOS and Windows.

bool is_item_radio_checkable(RID rid, int idx)

Parameters

rid RID
idx int

is_opened(RID)

Qualifiers: const

Returns true if the menu is currently opened.

Note: This method is implemented only on macOS.

bool is_opened(RID rid)

Parameters

rid RID

is_system_menu(RID)

Qualifiers: const

Return true is global menu is a special system menu.

Note: This method is implemented only on macOS.

bool is_system_menu(RID rid)

Parameters

rid RID

popup(RID, Vector2i)

Shows the global menu at position in the screen coordinates.

Note: This method is implemented on macOS and Windows.

void popup(RID rid, Vector2i position)

Parameters

rid RID
position Vector2i

remove_item(RID, int)

Removes the item at index idx from the global menu rid.

Note: The indices of items after the removed item will be shifted by one.

Note: This method is implemented on macOS and Windows.

void remove_item(RID rid, int idx)

Parameters

rid RID
idx int

set_interface_direction(RID, bool)

Sets the menu text layout direction from right-to-left if is_rtl is true.

Note: This method is implemented on macOS and Windows.

void set_interface_direction(RID rid, bool is_rtl)

Parameters

rid RID
is_rtl bool

set_item_accelerator(RID, int, int)

Sets the accelerator of the item at index idx. keycode can be a single Key, or a combination of KeyModifierMasks and Keys using bitwise OR such as KEY_MASK_CTRL | KEY_A (Ctrl + A).

Note: This method is implemented only on macOS.

void set_item_accelerator(RID rid, int idx, int keycode)

Parameters

rid RID
idx int
keycode int

set_item_callback(RID, int, Callable)

Sets the callback of the item at index idx. Callback is emitted when an item is pressed.

Note: The callback Callable needs to accept exactly one Variant parameter, the parameter passed to the Callable will be the value passed to the tag parameter when the menu item was created.

Note: This method is implemented on macOS and Windows.

void set_item_callback(RID rid, int idx, Callable callback)

Parameters

rid RID
idx int
callback Callable

set_item_checkable(RID, int, bool)

Sets whether the item at index idx has a checkbox. If false, sets the type of the item to plain text.

Note: This method is implemented on macOS and Windows.

void set_item_checkable(RID rid, int idx, bool checkable)

Parameters

rid RID
idx int
checkable bool

set_item_checked(RID, int, bool)

Sets the checkstate status of the item at index idx.

Note: This method is implemented on macOS and Windows.

void set_item_checked(RID rid, int idx, bool checked)

Parameters

rid RID
idx int
checked bool

set_item_disabled(RID, int, bool)

Enables/disables the item at index idx. When it is disabled, it can't be selected and its action can't be invoked.

Note: This method is implemented on macOS and Windows.

void set_item_disabled(RID rid, int idx, bool disabled)

Parameters

rid RID
idx int
disabled bool

set_item_hidden(RID, int, bool)

Hides/shows the item at index idx. When it is hidden, an item does not appear in a menu and its action cannot be invoked.

Note: This method is implemented only on macOS.

void set_item_hidden(RID rid, int idx, bool hidden)

Parameters

rid RID
idx int
hidden bool

set_item_hover_callbacks(RID, int, Callable)

Sets the callback of the item at index idx. The callback is emitted when an item is hovered.

Note: The callback Callable needs to accept exactly one Variant parameter, the parameter passed to the Callable will be the value passed to the tag parameter when the menu item was created.

Note: This method is implemented only on macOS.

void set_item_hover_callbacks(RID rid, int idx, Callable callback)

Parameters

rid RID
idx int
callback Callable

set_item_icon(RID, int, Texture2D)

Replaces the Texture2D icon of the specified idx.

Note: This method is implemented on macOS and Windows.

Note: This method is not supported by macOS Dock menu items.

void set_item_icon(RID rid, int idx, Texture2D icon)

Parameters

rid RID
idx int
icon Texture2D

set_item_indentation_level(RID, int, int)

Sets the horizontal offset of the item at the given idx.

Note: This method is implemented only on macOS.

void set_item_indentation_level(RID rid, int idx, int level)

Parameters

rid RID
idx int
level int

set_item_key_callback(RID, int, Callable)

Sets the callback of the item at index idx. Callback is emitted when its accelerator is activated.

Note: The key_callback Callable needs to accept exactly one Variant parameter, the parameter passed to the Callable will be the value passed to the tag parameter when the menu item was created.

Note: This method is implemented only on macOS.

void set_item_key_callback(RID rid, int idx, Callable key_callback)

Parameters

rid RID
idx int
key_callback Callable

set_item_max_states(RID, int, int)

Sets number of state of a multistate item. See NativeMenu.add_multistate_item for details.

Note: This method is implemented on macOS and Windows.

void set_item_max_states(RID rid, int idx, int max_states)

Parameters

rid RID
idx int
max_states int

set_item_radio_checkable(RID, int, bool)

Sets the type of the item at the specified index idx to radio button. If false, sets the type of the item to plain text.

Note: This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups.

Note: This method is implemented on macOS and Windows.

void set_item_radio_checkable(RID rid, int idx, bool checkable)

Parameters

rid RID
idx int
checkable bool

set_item_state(RID, int, int)

Sets the state of a multistate item. See NativeMenu.add_multistate_item for details.

Note: This method is implemented on macOS and Windows.

void set_item_state(RID rid, int idx, int state)

Parameters

rid RID
idx int
state int

set_item_submenu(RID, int, RID)

Sets the submenu RID of the item at index idx. The submenu is a global menu that would be shown when the item is clicked.

Note: This method is implemented on macOS and Windows.

void set_item_submenu(RID rid, int idx, RID submenu_rid)

Parameters

rid RID
idx int
submenu_rid RID

set_item_tag(RID, int, Variant)

Sets the metadata of an item, which may be of any type. You can later get it with NativeMenu.get_item_tag, which provides a simple way of assigning context data to items.

Note: This method is implemented on macOS and Windows.

void set_item_tag(RID rid, int idx, Variant tag)

Parameters

rid RID
idx int
tag Variant

set_item_text(RID, int, String)

Sets the text of the item at index idx.

Note: This method is implemented on macOS and Windows.

void set_item_text(RID rid, int idx, String text)

Parameters

rid RID
idx int
text String

set_item_tooltip(RID, int, String)

Sets the String tooltip of the item at the specified index idx.

Note: This method is implemented only on macOS.

void set_item_tooltip(RID rid, int idx, String tooltip)

Parameters

rid RID
idx int
tooltip String

set_minimum_width(RID, float)

Sets the minimum width of the global menu.

Note: This method is implemented only on macOS.

void set_minimum_width(RID rid, float width)

Parameters

rid RID
width float

set_popup_close_callback(RID, Callable)

Registers callable to emit when the menu is about to show.

Note: The OS can simulate menu opening to track menu item changes and global shortcuts, in which case the corresponding close callback is not triggered. Use NativeMenu.is_opened to check if the menu is currently opened.

Note: This method is implemented on macOS and Windows.

void set_popup_close_callback(RID rid, Callable callback)

Parameters

rid RID
callback Callable

set_popup_open_callback(RID, Callable)

Registers callable to emit after the menu is closed.

Note: This method is implemented only on macOS.

void set_popup_open_callback(RID rid, Callable callback)

Parameters

rid RID
callback Callable