NativeMenu

继承： Object

操作系统原生菜单的服务器接口。

描述

NativeMenu 处理对 OS 原生全局菜单栏和弹出菜单的低级访问。

注意：这是低级 API，请考虑使用将 MenuBar.prefer_global_menu 设置为 true 的 MenuBar，以及将 PopupMenu.prefer_native_menu 设置为 true 的 PopupMenu。

要创建一个菜单，请使用 create_menu，使用 add_*_item 方法添加菜单项。要移除一个菜单，请使用 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():
    # 创建新菜单并添加项目：
    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():
    # 在鼠标位置显示弹出菜单：
    NativeMenu.popup(menu, DisplayServer.mouse_get_position())
func _exit_tree():
    # 当不再需要时移除菜单：
    NativeMenu.free_menu(menu)

方法

枚举

enum Feature: 🔗

Feature FEATURE_GLOBAL_MENU = 0

NativeMenu 支持原生全局主菜单。

Feature FEATURE_POPUP_MENU = 1

NativeMenu 支持原生弹出菜单。

Feature FEATURE_OPEN_CLOSE_CALLBACK = 2

NativeMenu 支持菜单打开和关闭回调。

Feature FEATURE_HOVER_CALLBACK = 3

NativeMenu 支持菜单项悬停回调。

Feature FEATURE_KEY_CALLBACK = 4

NativeMenu 支持菜单项加速器/键回调。

enum SystemMenus: 🔗

SystemMenus INVALID_MENU_ID = 0

无效的特殊系统菜单 ID。

SystemMenus MAIN_MENU_ID = 1

全局主菜单 ID。

SystemMenus APPLICATION_MENU_ID = 2

应用程序（macOS 上“Apple”菜单后的第一个菜单）菜单 ID。

SystemMenus WINDOW_MENU_ID = 3

“窗口”菜单 ID（在 macOS 上，该菜单包括标准窗口控制项和打开的窗口列表）。

SystemMenus HELP_MENU_ID = 4

“帮助”菜单 ID（在 macOS 上，该菜单包括帮助搜索栏）。

SystemMenus DOCK_MENU_ID = 5

Dock 图标右键菜单 ID（在 macOS 上，该菜单包括标准应用程序控制项和打开的窗口列表）。

方法说明

int add_check_item(rid: RID, label: String, callback: Callable = Callable(), key_callback: Callable = Callable(), tag: Variant = null, accelerator: Key = 0, index: int = -1) 🔗

向 ID 为 rid 的全局菜单中添加新的可勾选菜单项，显示的文本为 label。

返回插入菜单项的索引，不保证与 index 的值相同。

还可以定义键盘快捷键 accelerator，按下后即便该菜单按钮尚未打开，也会进行触发。accelerator 通常是将 KeyModifierMask 和 Key 用按位或操作进行的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

注意：callback 和 key_callback Callable 均只接受一个 Variant 参数，传入 Callable 的参数是传给 tag 的参数。

注意：该方法在 macOS 和 Windows 上实现。

注意：在 Windows 上会忽略 accelerator 和 key_callback。

int add_icon_check_item(rid: RID, icon: Texture2D, label: String, callback: Callable = Callable(), key_callback: Callable = Callable(), tag: Variant = null, accelerator: Key = 0, index: int = -1) 🔗

向 ID 为 rid 的全局菜单中添加新的可勾选菜单项，显示的文本为 label，图标为 icon。

返回插入菜单项的索引，不保证与 index 的值相同。

还可以定义键盘快捷键 accelerator，按下后即便该菜单按钮尚未打开，也会进行触发。accelerator 通常是将 KeyModifierMask 和 Key 用按位或操作进行的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

注意：callback 和 key_callback Callable 均只接受一个 Variant 参数，传入 Callable 的参数是传给 tag 的参数。

注意：该方法在 macOS 和 Windows 上实现。

注意：在 Windows 上会忽略 accelerator 和 key_callback。

int add_icon_item(rid: RID, icon: Texture2D, label: String, callback: Callable = Callable(), key_callback: Callable = Callable(), tag: Variant = null, accelerator: Key = 0, index: int = -1) 🔗

向 ID 为 rid 的全局菜单中添加新的菜单项，显示的文本为 label，图标为 icon。

返回插入菜单项的索引，不保证与 index 的值相同。

还可以定义键盘快捷键 accelerator，按下后即便该菜单按钮尚未打开，也会进行触发。accelerator 通常是将 KeyModifierMask 和 Key 用按位或操作进行的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

注意：callback 和 key_callback Callable 均只接受一个 Variant 参数，传入 Callable 的参数是传给 tag 的参数。

注意：该方法在 macOS 和 Windows 上实现。

注意：在 Windows 上会忽略 accelerator 和 key_callback。

int add_icon_radio_check_item(rid: RID, icon: Texture2D, label: String, callback: Callable = Callable(), key_callback: Callable = Callable(), tag: Variant = null, accelerator: Key = 0, index: int = -1) 🔗

向 ID 为 rid 的全局菜单中添加新的单选菜单项，显示的文本为 label，图标为 icon。

返回插入菜单项的索引，不保证与 index 的值相同。

还可以定义键盘快捷键 accelerator，按下后即便该菜单按钮尚未打开，也会进行触发。accelerator 通常是将 KeyModifierMask 和 Key 用按位或操作进行的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

注意：单选菜单项只负责显示选中标记，并没有任何内置检查行为，必须手动进行选中、取消选中的操作。关于如何进行控制的更多信息见 set_item_checked。

注意：callback 和 key_callback Callable 均只接受一个 Variant 参数，传入 Callable 的参数是传给 tag 的参数。

注意：该方法在 macOS 和 Windows 上实现。

注意：在 Windows 上会忽略 accelerator 和 key_callback。

int add_item(rid: RID, label: String, callback: Callable = Callable(), key_callback: Callable = Callable(), tag: Variant = null, accelerator: Key = 0, index: int = -1) 🔗

向 ID 为 rid 的全局菜单添加新的菜单项，显示的文本为 label。

返回插入菜单项的索引，不保证与 index 的值相同。

还可以定义键盘快捷键 accelerator，按下后即便该菜单按钮尚未打开，也会进行触发。accelerator 通常是将 KeyModifierMask 和 Key 用按位或操作进行的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

注意：callback 和 key_callback Callable 均只接受一个 Variant 参数，传入 Callable 的参数是传给 tag 的参数。

注意：该方法在 macOS 和 Windows 上实现。

注意：在 Windows 上会忽略 accelerator 和 key_callback。

int add_multistate_item(rid: RID, label: String, max_states: int, default_state: int, callback: Callable = Callable(), key_callback: Callable = Callable(), tag: Variant = null, accelerator: Key = 0, index: int = -1) 🔗

向 ID 为 rid 的全局菜单中添加新的菜单项，显示的文本为 label。

与常规的二态菜单项不同，多状态菜单项的状态可以多于两个，由 max_states 定义。每点击或激活该菜单项一次，状态就会加一。默认值由 default_state 定义。

返回插入菜单项的索引，不保证与 index 的值相同。

还可以定义键盘快捷键 accelerator，按下后即便该菜单按钮尚未打开，也会进行触发。accelerator 通常是将 KeyModifierMask 和 Key 用按位或操作进行的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

注意：默认情况下不会展示当前菜单项的状态，应该手动更改。

注意：callback 和 key_callback Callable 均只接受一个 Variant 参数，传入 Callable 的参数是传给 tag 的参数。

注意：该方法在 macOS 和 Windows 上实现。

注意：在 Windows 上会忽略 accelerator 和 key_callback。

int add_radio_check_item(rid: RID, label: String, callback: Callable = Callable(), key_callback: Callable = Callable(), tag: Variant = null, accelerator: Key = 0, index: int = -1) 🔗

向 ID 为 rid 的全局菜单中添加新的单选菜单项，显示的文本为 label。

返回插入菜单项的索引，不保证与 index 的值相同。

还可以定义键盘快捷键 accelerator，按下后即便该菜单按钮尚未打开，也会进行触发。accelerator 通常是将 KeyModifierMask 和 Key 用按位或操作进行的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

注意：单选菜单项只负责显示选中标记，并没有任何内置检查行为，必须手动进行选中、取消选中的操作。关于如何进行控制的更多信息见 set_item_checked。

注意：callback 和 key_callback Callable 均只接受一个 Variant 参数，传入 Callable 的参数是传给 tag 的参数。

注意：该方法在 macOS 和 Windows 上实现。

注意：在 Windows 上会忽略 accelerator 和 key_callback。

int add_separator(rid: RID, index: int = -1) 🔗

向 ID 为 rid 的全局菜单中添加分隔符。分隔符也会占据一个索引号。

返回插入菜单项的索引，不保证与 index 的值相同。

注意：该方法在 macOS 和 Windows 上实现。

int add_submenu_item(rid: RID, label: String, submenu_rid: RID, tag: Variant = null, index: int = -1) 🔗

向 ID 为 rid 的全局菜单中添加作为子菜单的菜单项。submenu_rid 参数为全局菜单根菜单项的 RID，会在点击该菜单项时显示。

返回插入菜单项的索引，不保证与 index 的值相同。

注意：该方法在 macOS 和 Windows 上实现。

void clear(rid: RID) 🔗

从全局菜单中移除所有菜单项 rid。

注意：该方法在 macOS 和 Windows 上实现。

RID create_menu() 🔗

新建全局菜单对象。

注意：该方法在 macOS 和 Windows 上实现。

int find_item_index_with_submenu(rid: RID, submenu_rid: RID) const 🔗

返回由 submenu_rid 指定的子菜单项的索引。索引由引擎自动分配给每个菜单项，无法手动设置。

注意：该方法在 macOS 和 Windows 上实现。

int find_item_index_with_tag(rid: RID, tag: Variant) const 🔗

返回具有指定 tag 的菜单项的索引。引擎会自动为每个菜单项分配索引，无法手动设置。

注意：该方法在 macOS 和 Windows 上实现。

int find_item_index_with_text(rid: RID, text: String) const 🔗

返回具有指定 text 的菜单项的索引。引擎会自动为每个菜单项分配索引，无法手动设置。

注意：该方法在 macOS 和 Windows 上实现。

void free_menu(rid: RID) 🔗

释放该 NativeMenu 所创建的全局菜单对象。

注意：该方法在 macOS 和 Windows 上实现。

Key get_item_accelerator(rid: RID, idx: int) const 🔗

返回索引为 idx 的菜单项的快捷键。快捷键是能够激活该菜单项的特殊按键组合，无论该控件是否有焦点。

注意：该方法仅在 macOS 上实现。

Callable get_item_callback(rid: RID, idx: int) const 🔗

返回索引为 idx 的菜单项的回调。

注意：该方法在 macOS 和 Windows 上实现。

int get_item_count(rid: RID) const 🔗

返回全局菜单 rid 中的菜单项的数量。

注意：该方法在 macOS 和 Windows 上实现。

Texture2D get_item_icon(rid: RID, idx: int) const 🔗

返回索引为 idx 的菜单项的图标。

注意：该方法在 macOS 和 Windows 上实现。

int get_item_indentation_level(rid: RID, idx: int) const 🔗

返回索引为 idx 的菜单项的水平偏移量。

注意：该方法仅在 macOS 上实现。

Callable get_item_key_callback(rid: RID, idx: int) const 🔗

返回索引为 idx 的菜单项的快捷键回调。

注意：该方法仅在 macOS 上实现。

int get_item_max_states(rid: RID, idx: int) const 🔗

返回多状态项的状态数。详见 add_multistate_item。

注意：该方法在 macOS 和 Windows 上实现。

int get_item_state(rid: RID, idx: int) const 🔗

返回多状态项的状态。详见 add_multistate_item。

注意：该方法在 macOS 和 Windows 上实现。

RID get_item_submenu(rid: RID, idx: int) const 🔗

返回索引为 idx 的菜单项的子菜单 ID。关于如何添加子菜单的更多信息见 add_submenu_item。

注意：该方法在 macOS 和 Windows 上实现。

Variant get_item_tag(rid: RID, idx: int) const 🔗

返回指定菜单项的元数据，可能是任何类型。元数据可以使用 set_item_tag 设置，该方法提供了一种将上下文数据分配给菜单项的简单方式。

注意：该方法在 macOS 和 Windows 上实现。

String get_item_text(rid: RID, idx: int) const 🔗

返回索引为 idx 的菜单项的文本。

注意：该方法在 macOS 和 Windows 上实现。

String get_item_tooltip(rid: RID, idx: int) const 🔗

返回索引为 idx 的菜单项所关联的工具提示。

注意：该方法仅在 macOS 上实现。

float get_minimum_width(rid: RID) const 🔗

返回全局菜单的最小宽度。

注意：该方法仅在 macOS 上实现。

Callable get_popup_close_callback(rid: RID) const 🔗

返回全局菜单的关闭回调。

注意：该方法仅在 macOS 上实现。

Callable get_popup_open_callback(rid: RID) const 🔗

返回全局菜单的打开回调。

注意：该方法仅在 macOS 上实现。

Vector2 get_size(rid: RID) const 🔗

返回全局菜单的大小。

注意：该方法在 macOS 和 Windows 上实现。

RID get_system_menu(menu_id: SystemMenus) const 🔗

返回特殊系统菜单的 RID。

注意：该方法仅在 macOS 上实现。

String get_system_menu_name(menu_id: SystemMenus) const 🔗

返回特殊系统菜单的可读名称。

注意：该方法仅在 macOS 上实现。

bool has_feature(feature: Feature) const 🔗

如果当前的 NativeMenu 支持指定的特性 feature，则返回 true，否则返回 false。

注意：该方法在 macOS 和 Windows 上实现。

bool has_menu(rid: RID) const 🔗

如果 rid 是有效的全局菜单，则返回 true。

注意：该方法在 macOS 和 Windows 上实现。

bool has_system_menu(menu_id: SystemMenus) const 🔗

如果支持特殊系统菜单则返回 true。

注意：该方法仅在 macOS 上实现。

bool is_item_checkable(rid: RID, idx: int) const 🔗

如果索引为 idx 的菜单项能够以某种方式被勾选，即有复选框或单选按钮，则返回 true。

注意：该方法在 macOS 和 Windows 上实现。

bool is_item_checked(rid: RID, idx: int) const 🔗

如果索引 idx 处的菜单项被勾选，则返回 true。

注意：该方法在 macOS 和 Windows 上实现。

bool is_item_disabled(rid: RID, idx: int) const 🔗

如果索引 idx 处的菜单项被禁用，则返回 true。禁用后，无法选择它，也无法调用其动作。

有关如何禁用菜单项的更多信息，请参阅 set_item_disabled。

注意：该方法在 macOS 和 Windows 上实现。

bool is_item_hidden(rid: RID, idx: int) const 🔗

如果索引 idx 处的菜单项被隐藏，则返回 true。

有关如何隐藏菜单项的更多信息，请参阅 set_item_hidden。

注意：该方法仅在 macOS 上实现。

bool is_item_radio_checkable(rid: RID, idx: int) const 🔗

如果索引为 idx 的菜单项为单选按钮风格，则返回 true。

注意：仅为装饰作用；必须自行为单选组添加勾选、取消勾选的逻辑。

注意：该方法在 macOS 和 Windows 上实现。

bool is_opened(rid: RID) const 🔗

如果菜单当前已打开，则返回 true。

注意：该方法仅在 macOS 上实现。

bool is_system_menu(rid: RID) const 🔗

如果全局菜单为特殊系统菜单则返回 true 。

注意：该方法仅在 macOS 上实现。

void popup(rid: RID, position: Vector2i) 🔗

在屏幕坐标中的 position 处显示全局菜单。

注意：该方法在 macOS 和 Windows 上实现。

void remove_item(rid: RID, idx: int) 🔗

从全局菜单 rid 中移除索引 idx 处的菜单项。

注意：被移除菜单项之后的菜单项的索引将移动一格。

注意：该方法在 macOS 和 Windows 上实现。

void set_interface_direction(rid: RID, is_rtl: bool) 🔗

如果 is_rtl 为 true，则设置菜单文本布局方向为从右到左。

注意：该方法在 macOS 和 Windows 上实现。

void set_item_accelerator(rid: RID, idx: int, keycode: Key) 🔗

设置索引为 idx 的菜单项的快捷键。keycode 可以是单一 Key，也可以是 KeyModifierMask 和 Key 用按位或操作进行的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

注意：该方法仅在 macOS 上实现。

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

设置索引为 idx 的菜单项的回调。回调会在按下菜单项时发出。

注意：callback Callable 只接受一个 Variant 参数，传入 Callable 的参数是创建菜单项时传给 tag 参数的值。

注意：该方法在 macOS 和 Windows 上实现。

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

设置索引为 idx 的菜单项是否为复选框。如果为 false，则会将该菜单项的类型设置为纯文本。

注意：该方法在 macOS 和 Windows 上实现。

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

设置索引为 idx 的菜单项的勾选状态。

注意：该方法在 macOS 和 Windows 上实现。

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

启用/禁用索引为 idx 的菜单项。禁用状态下无法被选中，也无法激活动作。

注意：该方法在 macOS 和 Windows 上实现。

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

隐藏/显示索引为 idx 的菜单项。当它被隐藏时，项目不会出现在菜单中，并且无法调用其操作。

注意：该方法仅在 macOS 上实现。

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

设置索引为 idx 的菜单项的回调。回调会在菜单项被悬停时发出。

注意：callback Callable 需要接受一个 Variant 参数，传入 Callable 的参数是创建菜单项时传给 tag 参数的值。

注意：该方法仅在 macOS 上实现。

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

替换指定索引 idx 的 Texture2D 图标。

注意：该方法在 macOS 和 Windows 上实现。

注意：macOS Dock 菜单项不支持该方法。

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

设置索引为 idx 的菜单项的水平偏移量。

注意：该方法仅在 macOS 上实现。

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

设置索引为 idx 的菜单项的回调。回调会在激活快捷键时发出。

注意：key_callback Callable 只接受一个 Variant 参数，传入 Callable 的参数是创建菜单项时传给 tag 参数的值。

注意：该方法仅在 macOS 上实现。

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

设置多状态项的状态数。详见 add_multistate_item。

注意：该方法在 macOS 和 Windows 上实现。

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

将索引为 idx 的菜单项设置为单选按钮风格。如果为 false，则会将该菜单项的类型设置为纯文本。

注意：仅为装饰作用；必须自行为单选组添加选中、取消选中的逻辑。

注意：该方法在 macOS 和 Windows 上实现。

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

设置多状态项的状态。详见 add_multistate_item。

注意：该方法在 macOS 和 Windows 上实现。

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

设置索引 idx 处菜单项的子菜单 RID。子菜单是一个全局菜单，点击该菜单项时将显示该菜单。

注意：该方法在 macOS 和 Windows 上实现。

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

设置指定菜单项的元数据，可以是任何类型。后续可以使用 get_item_tag 获取，它提供了一种将上下文数据分配给项目的简单方式。

注意：该方法在 macOS 和 Windows 上实现。

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

设置索引为 idx 的菜单项的文本。

注意：该方法在 macOS 和 Windows 上实现。

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

设置索引为 idx 的菜单项的工具提示 String。

注意：该方法仅在 macOS 上实现。

void set_minimum_width(rid: RID, width: float) 🔗

设置全局菜单的最小宽度。

注意：该方法仅在 macOS 上实现。

void set_popup_close_callback(rid: RID, callback: Callable) 🔗

注册可调用函数，以在菜单即将显示时发出。

注意：操作系统可以模拟菜单打开来跟踪菜单项更改和全局快捷键，在这种情况下不会触发相应的关闭回调。使用 is_opened 检查菜单当前是否已打开。

注意：该方法仅在 macOS 上实现。

void set_popup_open_callback(rid: RID, callback: Callable) 🔗

注册可调用函数以在菜单关闭后发出。

注意：该方法仅在 macOS 上实现。