Class NativeMenu
- Namespace
- Godot
- Assembly
- GodotSharp.dll
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 PreferGlobalMenu set to true, and PopupMenu with PreferNativeMenu set to true.
To create a menu, use CreateMenu(), add menu items using add_*_item
methods. To remove a menu, use FreeMenu(Rid).
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)
public static class NativeMenu
- Inheritance
-
NativeMenu
- Inherited Members
Properties
Singleton
public static NativeMenuInstance Singleton { get; }
Property Value
Methods
AddCheckItem(Rid, string, Callable, Callable, Variant, Key, 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 keyCallback
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 keyCallback
are ignored.
public static int AddCheckItem(Rid rid, string label, Callable callback = default, Callable keyCallback = default, Variant tag = default, Key accelerator = Key.None, int index = -1)
Parameters
Returns
AddIconCheckItem(Rid, Texture2D, string, Callable, Callable, Variant, Key, 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 keyCallback
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 keyCallback
are ignored.
public static int AddIconCheckItem(Rid rid, Texture2D icon, string label, Callable callback = default, Callable keyCallback = default, Variant tag = default, Key accelerator = Key.None, int index = -1)
Parameters
rid
Ridicon
Texture2Dlabel
stringcallback
CallablekeyCallback
Callabletag
Variantaccelerator
Keyindex
int
Returns
AddIconItem(Rid, Texture2D, string, Callable, Callable, Variant, Key, 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 keyCallback
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 keyCallback
are ignored.
public static int AddIconItem(Rid rid, Texture2D icon, string label, Callable callback = default, Callable keyCallback = default, Variant tag = default, Key accelerator = Key.None, int index = -1)
Parameters
rid
Ridicon
Texture2Dlabel
stringcallback
CallablekeyCallback
Callabletag
Variantaccelerator
Keyindex
int
Returns
AddIconRadioCheckItem(Rid, Texture2D, string, Callable, Callable, Variant, Key, 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 SetItemChecked(Rid, int, bool) for more info on how to control it.
Note: The callback
and keyCallback
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 keyCallback
are ignored.
public static int AddIconRadioCheckItem(Rid rid, Texture2D icon, string label, Callable callback = default, Callable keyCallback = default, Variant tag = default, Key accelerator = Key.None, int index = -1)
Parameters
rid
Ridicon
Texture2Dlabel
stringcallback
CallablekeyCallback
Callabletag
Variantaccelerator
Keyindex
int
Returns
AddItem(Rid, string, Callable, Callable, Variant, Key, 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 keyCallback
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 keyCallback
are ignored.
public static int AddItem(Rid rid, string label, Callable callback = default, Callable keyCallback = default, Variant tag = default, Key accelerator = Key.None, int index = -1)
Parameters
Returns
AddMultistateItem(Rid, string, int, int, Callable, Callable, Variant, Key, 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 maxStates
. Each press or activate of the item will increase the state by one. The default value is defined by defaultState
.
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 keyCallback
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 keyCallback
are ignored.
public static int AddMultistateItem(Rid rid, string label, int maxStates, int defaultState, Callable callback = default, Callable keyCallback = default, Variant tag = default, Key accelerator = Key.None, int index = -1)
Parameters
rid
Ridlabel
stringmaxStates
intdefaultState
intcallback
CallablekeyCallback
Callabletag
Variantaccelerator
Keyindex
int
Returns
AddRadioCheckItem(Rid, string, Callable, Callable, Variant, Key, 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 SetItemChecked(Rid, int, bool) for more info on how to control it.
Note: The callback
and keyCallback
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 keyCallback
are ignored.
public static int AddRadioCheckItem(Rid rid, string label, Callable callback = default, Callable keyCallback = default, Variant tag = default, Key accelerator = Key.None, int index = -1)
Parameters
Returns
AddSeparator(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.
public static int AddSeparator(Rid rid, int index = -1)
Parameters
Returns
AddSubmenuItem(Rid, string, Rid, Variant, int)
Adds an item that will act as a submenu of the global menu rid
. The submenuRid
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.
public static int AddSubmenuItem(Rid rid, string label, Rid submenuRid, Variant tag = default, int index = -1)
Parameters
Returns
Clear(Rid)
Removes all items from the global menu rid
.
Note: This method is implemented on macOS and Windows.
public static void Clear(Rid rid)
Parameters
rid
Rid
CreateMenu()
Creates a new global menu object.
Note: This method is implemented on macOS and Windows.
public static Rid CreateMenu()
Returns
FindItemIndexWithSubmenu(Rid, Rid)
Returns the index of the item with the submenu specified by submenuRid
. Indices are automatically assigned to each item by the engine, and cannot be set manually.
Note: This method is implemented on macOS and Windows.
public static int FindItemIndexWithSubmenu(Rid rid, Rid submenuRid)
Parameters
Returns
FindItemIndexWithTag(Rid, Variant)
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.
public static int FindItemIndexWithTag(Rid rid, Variant tag)
Parameters
Returns
FindItemIndexWithText(Rid, string)
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.
public static int FindItemIndexWithText(Rid rid, string text)
Parameters
Returns
FreeMenu(Rid)
Frees a global menu object created by this NativeMenu.
Note: This method is implemented on macOS and Windows.
public static void FreeMenu(Rid rid)
Parameters
rid
Rid
GetItemAccelerator(Rid, int)
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.
public static Key GetItemAccelerator(Rid rid, int idx)
Parameters
Returns
GetItemCallback(Rid, int)
Returns the callback of the item at index idx
.
Note: This method is implemented on macOS and Windows.
public static Callable GetItemCallback(Rid rid, int idx)
Parameters
Returns
GetItemCount(Rid)
Returns number of items in the global menu rid
.
Note: This method is implemented on macOS and Windows.
public static int GetItemCount(Rid rid)
Parameters
rid
Rid
Returns
GetItemIcon(Rid, int)
Returns the icon of the item at index idx
.
Note: This method is implemented on macOS and Windows.
public static Texture2D GetItemIcon(Rid rid, int idx)
Parameters
Returns
GetItemIndentationLevel(Rid, int)
Returns the horizontal offset of the item at the given idx
.
Note: This method is implemented only on macOS.
public static int GetItemIndentationLevel(Rid rid, int idx)
Parameters
Returns
GetItemKeyCallback(Rid, int)
Returns the callback of the item accelerator at index idx
.
Note: This method is implemented only on macOS.
public static Callable GetItemKeyCallback(Rid rid, int idx)
Parameters
Returns
GetItemMaxStates(Rid, int)
Returns number of states of a multistate item. See AddMultistateItem(Rid, string, int, int, Callable, Callable, Variant, Key, int) for details.
Note: This method is implemented on macOS and Windows.
public static int GetItemMaxStates(Rid rid, int idx)
Parameters
Returns
GetItemState(Rid, int)
Returns the state of a multistate item. See AddMultistateItem(Rid, string, int, int, Callable, Callable, Variant, Key, int) for details.
Note: This method is implemented on macOS and Windows.
public static int GetItemState(Rid rid, int idx)
Parameters
Returns
GetItemSubmenu(Rid, int)
Returns the submenu ID of the item at index idx
. See AddSubmenuItem(Rid, string, Rid, Variant, int) for more info on how to add a submenu.
Note: This method is implemented on macOS and Windows.
public static Rid GetItemSubmenu(Rid rid, int idx)
Parameters
Returns
GetItemTag(Rid, int)
Returns the metadata of the specified item, which might be of any type. You can set it with SetItemTag(Rid, int, Variant), which provides a simple way of assigning context data to items.
Note: This method is implemented on macOS and Windows.
public static Variant GetItemTag(Rid rid, int idx)
Parameters
Returns
GetItemText(Rid, int)
Returns the text of the item at index idx
.
Note: This method is implemented on macOS and Windows.
public static string GetItemText(Rid rid, int idx)
Parameters
Returns
GetItemTooltip(Rid, int)
Returns the tooltip associated with the specified index idx
.
Note: This method is implemented only on macOS.
public static string GetItemTooltip(Rid rid, int idx)
Parameters
Returns
GetMinimumWidth(Rid)
Returns global menu minimum width.
Note: This method is implemented only on macOS.
public static float GetMinimumWidth(Rid rid)
Parameters
rid
Rid
Returns
GetPopupCloseCallback(Rid)
Returns global menu close callback.
b]Note:[/b] This method is implemented only on macOS.
public static Callable GetPopupCloseCallback(Rid rid)
Parameters
rid
Rid
Returns
GetPopupOpenCallback(Rid)
Returns global menu open callback.
b]Note:[/b] This method is implemented only on macOS.
public static Callable GetPopupOpenCallback(Rid rid)
Parameters
rid
Rid
Returns
GetSize(Rid)
Returns global menu size.
Note: This method is implemented on macOS and Windows.
public static Vector2 GetSize(Rid rid)
Parameters
rid
Rid
Returns
GetSystemMenu(SystemMenus)
Returns RID of a special system menu.
Note: This method is implemented only on macOS.
public static Rid GetSystemMenu(NativeMenu.SystemMenus menuId)
Parameters
menuId
NativeMenu.SystemMenus
Returns
GetSystemMenuName(SystemMenus)
Returns readable name of a special system menu.
Note: This method is implemented only on macOS.
public static string GetSystemMenuName(NativeMenu.SystemMenus menuId)
Parameters
menuId
NativeMenu.SystemMenus
Returns
HasFeature(Feature)
Returns true if the specified feature
is supported by the current NativeMenu, false otherwise.
Note: This method is implemented on macOS and Windows.
public static bool HasFeature(NativeMenu.Feature feature)
Parameters
feature
NativeMenu.Feature
Returns
HasMenu(Rid)
Returns true if rid
is valid global menu.
Note: This method is implemented on macOS and Windows.
public static bool HasMenu(Rid rid)
Parameters
rid
Rid
Returns
HasSystemMenu(SystemMenus)
Returns true if a special system menu is supported.
Note: This method is implemented only on macOS.
public static bool HasSystemMenu(NativeMenu.SystemMenus menuId)
Parameters
menuId
NativeMenu.SystemMenus
Returns
IsItemCheckable(Rid, int)
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.
public static bool IsItemCheckable(Rid rid, int idx)
Parameters
Returns
IsItemChecked(Rid, int)
Returns true if the item at index idx
is checked.
Note: This method is implemented on macOS and Windows.
public static bool IsItemChecked(Rid rid, int idx)
Parameters
Returns
IsItemDisabled(Rid, int)
Returns true if the item at index idx
is disabled. When it is disabled it can't be selected, or its action invoked.
See SetItemDisabled(Rid, int, bool) for more info on how to disable an item.
Note: This method is implemented on macOS and Windows.
public static bool IsItemDisabled(Rid rid, int idx)
Parameters
Returns
IsItemHidden(Rid, int)
Returns true if the item at index idx
is hidden.
See SetItemHidden(Rid, int, bool) for more info on how to hide an item.
Note: This method is implemented only on macOS.
public static bool IsItemHidden(Rid rid, int idx)
Parameters
Returns
IsItemRadioCheckable(Rid, int)
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.
public static bool IsItemRadioCheckable(Rid rid, int idx)
Parameters
Returns
IsOpened(Rid)
Returns true if the menu is currently opened.
Note: This method is implemented only on macOS.
public static bool IsOpened(Rid rid)
Parameters
rid
Rid
Returns
IsSystemMenu(Rid)
Return true is global menu is a special system menu.
Note: This method is implemented only on macOS.
public static bool IsSystemMenu(Rid rid)
Parameters
rid
Rid
Returns
Popup(Rid, Vector2I)
Shows the global menu at position
in the screen coordinates.
Note: This method is implemented on macOS and Windows.
public static void Popup(Rid rid, Vector2I position)
Parameters
RemoveItem(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.
public static void RemoveItem(Rid rid, int idx)
Parameters
SetInterfaceDirection(Rid, bool)
Sets the menu text layout direction from right-to-left if isRtl
is true.
Note: This method is implemented on macOS and Windows.
public static void SetInterfaceDirection(Rid rid, bool isRtl)
Parameters
SetItemAccelerator(Rid, int, Key)
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.
public static void SetItemAccelerator(Rid rid, int idx, Key keycode)
Parameters
SetItemCallback(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.
public static void SetItemCallback(Rid rid, int idx, Callable callback)
Parameters
SetItemCheckable(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.
public static void SetItemCheckable(Rid rid, int idx, bool checkable)
Parameters
SetItemChecked(Rid, int, bool)
Sets the checkstate status of the item at index idx
.
Note: This method is implemented on macOS and Windows.
public static void SetItemChecked(Rid rid, int idx, bool @checked)
Parameters
SetItemDisabled(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.
public static void SetItemDisabled(Rid rid, int idx, bool disabled)
Parameters
SetItemHidden(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.
public static void SetItemHidden(Rid rid, int idx, bool hidden)
Parameters
SetItemHoverCallbacks(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.
public static void SetItemHoverCallbacks(Rid rid, int idx, Callable callback)
Parameters
SetItemIcon(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.
public static void SetItemIcon(Rid rid, int idx, Texture2D icon)
Parameters
SetItemIndentationLevel(Rid, int, int)
Sets the horizontal offset of the item at the given idx
.
Note: This method is implemented only on macOS.
public static void SetItemIndentationLevel(Rid rid, int idx, int level)
Parameters
SetItemKeyCallback(Rid, int, Callable)
Sets the callback of the item at index idx
. Callback is emitted when its accelerator is activated.
Note: The keyCallback
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.
public static void SetItemKeyCallback(Rid rid, int idx, Callable keyCallback)
Parameters
SetItemMaxStates(Rid, int, int)
Sets number of state of a multistate item. See AddMultistateItem(Rid, string, int, int, Callable, Callable, Variant, Key, int) for details.
Note: This method is implemented on macOS and Windows.
public static void SetItemMaxStates(Rid rid, int idx, int maxStates)
Parameters
SetItemRadioCheckable(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.
public static void SetItemRadioCheckable(Rid rid, int idx, bool checkable)
Parameters
SetItemState(Rid, int, int)
Sets the state of a multistate item. See AddMultistateItem(Rid, string, int, int, Callable, Callable, Variant, Key, int) for details.
Note: This method is implemented on macOS and Windows.
public static void SetItemState(Rid rid, int idx, int state)
Parameters
SetItemSubmenu(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.
public static void SetItemSubmenu(Rid rid, int idx, Rid submenuRid)
Parameters
SetItemTag(Rid, int, Variant)
Sets the metadata of an item, which may be of any type. You can later get it with GetItemTag(Rid, int), which provides a simple way of assigning context data to items.
Note: This method is implemented on macOS and Windows.
public static void SetItemTag(Rid rid, int idx, Variant tag)
Parameters
SetItemText(Rid, int, string)
Sets the text of the item at index idx
.
Note: This method is implemented on macOS and Windows.
public static void SetItemText(Rid rid, int idx, string text)
Parameters
SetItemTooltip(Rid, int, string)
Sets the string tooltip of the item at the specified index idx
.
Note: This method is implemented only on macOS.
public static void SetItemTooltip(Rid rid, int idx, string tooltip)
Parameters
SetMinimumWidth(Rid, float)
Sets the minimum width of the global menu.
Note: This method is implemented only on macOS.
public static void SetMinimumWidth(Rid rid, float width)
Parameters
SetPopupCloseCallback(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 IsOpened(Rid) to check if the menu is currently opened.
Note: This method is implemented only on macOS.
public static void SetPopupCloseCallback(Rid rid, Callable callback)
Parameters
SetPopupOpenCallback(Rid, Callable)
Registers callable to emit after the menu is closed.
Note: This method is implemented only on macOS.
public static void SetPopupOpenCallback(Rid rid, Callable callback)