PopupMenu

继承： Popup < Window < Viewport < Node < Object

用于显示选项列表的模态窗口。

描述

PopupMenu 是用于显示选项列表的模态窗口，常见于工具栏和上下文菜单。

PopupMenu 的大小可以使用 Window.max_size 限制。如果菜单项列表的高度大于 PopupMenu 的最大高度，则会在弹出框中使用 ScrollContainer 让用户滚动内容。如果没有设置最大尺寸或者设为了 0，则该 PopupMenu 的高度会被限制在父级的矩形框之中。

所有的 set_* 方法都允许使用负数菜单项索引，即 -1 访问的是最后一个菜单项，-2 选择的是倒数第二个菜单项，依次类推。

增量搜索：与 ItemList 和 Tree 类似，PopupMenu 也支持在聚焦控件时在列表中进行搜索。按下与某个条目名称首字母一致的按键，就会选中以该字母开头的第一个条目。在此之后，进行增量搜索的办法有两种：1）在超时前再次按下同一个按键，选中以该字母开头的下一个条目。2）在超时前按下剩余字母对应的按键，直接匹配并选中所需的条目。这两个动作都会在最后一次按键超时后重置回列表顶端。你可以通过 ProjectSettings.gui/timers/incremental_search_max_interval_msec 修改超时时长。

注意：菜单项的 ID 有 32 位的限制，不是完整 int 的 64 位。取值范围为 -2^32 到 2^32 - 1，即 -2147483648 到 2147483647。

属性

方法

主题属性

信号

id_focused(id: int) 🔗

用户使用 ProjectSettings.input/ui_up 或 ProjectSettings.input/ui_down 输入动作移动至 ID 为 id 的菜单项时发出。

id_pressed(id: int) 🔗

ID 为 id 的菜单项被按下或者由快捷键激活时发出。

注意：如果 id 为负数（无论是明确指定的还是由于溢出导致的），将返回相应的索引来代替。

index_pressed(index: int) 🔗

索引为 index 的菜单项被按下或者由快捷键激活时发出。

menu_changed() 🔗

发生菜单项的添加、修改、删除时发出。

属性说明

bool allow_search = true 🔗

• void set_allow_search(value: bool)

• bool get_allow_search()

如果为 true，允许用字母键导航 PopupMenu。

bool hide_on_checkable_item_selection = true 🔗

• void set_hide_on_checkable_item_selection(value: bool)

• bool is_hide_on_checkable_item_selection()

如果为 true，则在选中复选框或单选按钮时隐藏 PopupMenu。

bool hide_on_item_selection = true 🔗

• void set_hide_on_item_selection(value: bool)

• bool is_hide_on_item_selection()

如果为 true，当一个项目被选中时隐藏 PopupMenu。

bool hide_on_state_item_selection = false 🔗

• void set_hide_on_state_item_selection(value: bool)

• bool is_hide_on_state_item_selection()

如果为 true，则在选中状态项时隐藏 PopupMenu。

int item_count = 0 🔗

• void set_item_count(value: int)

• int get_item_count()

当前列表中的项目数。

bool prefer_native_menu = false 🔗

• void set_prefer_native_menu(value: bool)

• bool is_prefer_native_menu()

If true, MenuBar will use native menu when supported.

Note: If PopupMenu is linked to StatusIndicator, MenuBar, or another PopupMenu item it can use native menu regardless of this property, use is_native_menu to check it.

float submenu_popup_delay = 0.3 🔗

• void set_submenu_popup_delay(value: float)

• float get_submenu_popup_delay()

设置鼠标悬停时子菜单项弹出的延迟时间，以秒为单位。如果弹出菜单被添加为另一个菜单的子菜单（作为子菜单），它将继承父菜单项的延迟时间。

SystemMenus system_menu_id = 0 🔗

• void set_system_menu(value: SystemMenus)

• SystemMenus get_system_menu()

如果设置为 SystemMenus 的值之一，则该 PopupMenu 将绑定到特殊系统菜单。每个特殊菜单在同一时间只能绑定一个 PopupMenu。

方法说明

bool activate_item_by_event(event: InputEvent, for_global_only: bool = false) 🔗

根据 PopupMenu 的快捷键和加速器检查提供的 event，并激活匹配事件的第一个项目。如果 for_global_only 为 true，则仅调用 global 被设置为 true 的快捷键和加速器。

如果项目已成功激活，则返回 true。

注意：某些 Control，例如 MenuButton，会自动调用该方法。

void add_check_item(label: String, id: int = -1, accel: Key = 0) 🔗

添加一个带有文本 label 的新的可勾选项。

可以选择提供一个 id 以及一个加速器（accel）。如果未提供 id，将从索引中创建一个。如果未提供 accel，则默认值 0（对应于 @GlobalScope.KEY_NONE）将被分配给该项（这意味着它不会有任何加速器）。有关加速器的更多信息，请参阅 get_item_accelerator。

注意：可勾选的项只显示一个勾选标记，但没有任何内置的勾选行为，必须手动勾选/取消勾选。有关如何控制它的更多信息，请参阅 set_item_checked。

void add_check_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false) 🔗

添加一个新的可勾选项并为其分配指定的 Shortcut。将复选框的标签设置为 Shortcut 的名称。

可以选择提供一个 id。如果未提供 id，将从索引中创建一个。

注意：可勾选项只显示一个勾选标记，但没有任何内置的勾选行为，必须手动勾选/取消勾选。有关如何控制它的更多信息，请参阅 set_item_checked。

void add_icon_check_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0) 🔗

添加一个带有文本 label 和图标 texture 的新的可勾选项。

可以选择提供一个 id 以及一个加速器（accel）。如果未提供 id，将从索引中创建一个。如果未提供 accel，则默认值 0（对应于 @GlobalScope.KEY_NONE）将被分配给该项（这意味着它不会有任何加速器）。有关加速器的更多信息，请参阅 get_item_accelerator。

注意：可勾选项只显示一个勾选标记，但没有任何内置的勾选行为，必须手动勾选/取消勾选。有关如何控制它的更多信息，请参阅 set_item_checked。

void add_icon_check_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false) 🔗

添加一个新的可勾选项并为其分配指定的 Shortcut 和图标 texture。将复选框的标签设置为 Shortcut 的名称。

可以选择提供一个 id。如果未提供 id，将从索引中创建一个。

注意：可勾选项只显示一个勾选标记，但没有任何内置的勾选行为，必须手动勾选/取消勾选。有关如何控制它的更多信息，请参阅 set_item_checked。

void add_icon_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0) 🔗

添加带有文本 label 和图标 texture 的新菜单项。

还可以提供 id 和快捷键（accel）。如果没有提供 id，则会根据索引来创建。如果没有提供 accel，则会为该菜单项分配默认的 0（对应 @GlobalScope.KEY_NONE，在这里表示没有快捷键）。更多快捷键相关的信息见 get_item_accelerator。

void add_icon_radio_check_item(texture: Texture2D, label: String, id: int = -1, accel: Key = 0) 🔗

与 add_icon_check_item 相同，但使用单选按钮。

void add_icon_radio_check_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false) 🔗

与 add_icon_check_shortcut 相同，但使用一个单选按钮。

void add_icon_shortcut(texture: Texture2D, shortcut: Shortcut, id: int = -1, global: bool = false, allow_echo: bool = false) 🔗

添加新的菜单项，并为其分配指定的 Shortcut 和图标 texture。复选框的标签会被设为 Shortcut 的名称。

还可以提供 id。如果没有提供 id，则会根据索引来创建。

如果 allow_echo 为 true，则快捷键可以被回响事件激活。

void add_item(label: String, id: int = -1, accel: Key = 0) 🔗

添加一个带有文本 label 的新项。

可以选择提供一个 id 以及一个加速器（accel）。如果未提供 id，将从索引中创建一个。如果未提供 accel，则默认值 0（对应于 @GlobalScope.KEY_NONE）将被分配给该项（这意味着它不会有任何加速器）。有关加速器的更多信息，请参阅 get_item_accelerator。

注意：提供的 id 仅用于 id_pressed 和 id_focused 信号。它与在函数中，例如在 set_item_checked 中的 index 参数无关。

void add_multistate_item(label: String, max_states: int, default_state: int = 0, id: int = -1, accel: Key = 0) 🔗

添加新的多状态菜单项，使用 label 作为文本。

与普通的双态菜单项不同，多状态菜单项的状态可以超过两个，数量由 max_states 定义。默认值由 default_state 定义。

还可以提供 id 和快捷键（accel）。如果没有提供 id，则会根据索引来创建。如果没有提供 accel，则会为该菜单项分配默认的 0（对应 @GlobalScope.KEY_NONE，在这里表示没有快捷键）。更多快捷键相关的信息见 get_item_accelerator。

注意：多状态菜单项的状态不会自动变化，必须手动修改。如何控制见 toggle_item_multistate、set_item_multistate、get_item_multistate。

示例用法：

func _ready():
    add_multistate_item("菜单项", 3, 0)
    index_pressed.connect(func(index: int):
            toggle_item_multistate(index)
            match get_item_multistate(index):
                0:
                    print("甲状态")
                1:
                    print("乙状态")
                2:
                    print("丙状态")
        )

void add_radio_check_item(label: String, id: int = -1, accel: Key = 0) 🔗

添加一个带有文本 label 的新单选勾选按钮。

可以选择提供一个 id 以及一个加速器（accel）。如果未提供 id，将从索引中创建一个。如果未提供 accel，则默认值 0（对应于 @GlobalScope.KEY_NONE）将被分配给该项（这意味着它不会有任何加速器）。有关加速器的更多信息，请参阅 get_item_accelerator。

注意：可勾选项只显示一个勾选标记，但没有任何内置的勾选行为，必须手动勾选/取消勾选。有关如何控制它的更多信息，请参阅 set_item_checked。

void add_radio_check_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false) 🔗

添加一个新的单选勾选按钮并为其分配一个 Shortcut。将复选框的标签设置为 Shortcut 的名称。

可以选择提供一个 id。如果未提供 id，将从索引中创建一个。

注意：可勾选项只显示一个勾选标记，但没有任何内置的勾选行为，必须手动勾选/取消勾选。有关如何控制它的更多信息，请参阅 set_item_checked。

void add_separator(label: String = “”, id: int = -1) 🔗

在菜单项之间添加分隔线。分隔线也占用索引，可以使用 id 参数设置。

还可以提供 label，会在分隔线的中间位置显示。

void add_shortcut(shortcut: Shortcut, id: int = -1, global: bool = false, allow_echo: bool = false) 🔗

添加 Shortcut。

还可以提供 id。如果没有提供 id，则会根据索引来创建。

如果 allow_echo 为 true，则快捷键可以被回响事件激活。

void add_submenu_item(label: String, submenu: String, id: int = -1) 🔗

已弃用： Prefer using add_submenu_node_item instead.

添加菜单项，点击时会作为父级 PopupMenu 节点的子菜单。submenu 参数必须是已作为子节点添加到此节点的现有 PopupMenu 的名称。当点击该项目、悬停足够长的时间或使用 ui_select 或 ui_right 输入操作激活该子菜单时，将显示该子菜单。

还可以提供 id。如果没有提供 id，则会根据索引来创建。

void add_submenu_node_item(label: String, submenu: PopupMenu, id: int = -1) 🔗

添加一个菜单项，点击时会作为父级 PopupMenu 节点的子菜单。当点击该项目、悬停足够长的时间或使用 ui_select 或 ui_right 输入操作激活该子菜单时，将显示该子菜单。

submenu 必须是该 PopupMenu 的子节点，或者没有父节点（在这种情况下，它将自动添加为子节点）。如果 submenu 弹出窗口有另一个父级节点，则该方法将失败。

还可以选择提供 id。如果没有提供 id，则将从索引创建一个。

void clear(free_submenus: bool = false) 🔗

移除 PopupMenu 中的所有项目。如果 free_submenus 为 true，则自动释放子菜单节点。

int get_focused_item() const 🔗

返回当前焦点项目的索引。如果没有焦点，则返回 -1。

Key get_item_accelerator(index: int) const 🔗

返回给定 index 处项目的加速器。加速器是一种键盘快捷键，即使当前未打开菜单按钮，也可以按下它来触发菜单按钮。返回值是一个整数，通常是 KeyModifierMask 和 Key 使用按位或操作的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。如果没有为指定的 index 定义加速器，则 get_item_accelerator 返回 0（对应于 @GlobalScope.KEY_NONE）。

Texture2D get_item_icon(index: int) const 🔗

返回给定 index 处菜单项的图标。

int get_item_icon_max_width(index: int) const 🔗

返回给定 index 处菜单项所允许的最大图标宽度。

Color get_item_icon_modulate(index: int) const 🔗

返回给定 index 处用于调制菜单项图标的 Color。

int get_item_id(index: int) const 🔗

返回给定 index 处菜单项的 ID。id 可以手动分配，而索引则不能。

int get_item_indent(index: int) const 🔗

返回给定 index 处菜单项的水平偏移量。

int get_item_index(id: int) const 🔗

返回包含指定 id 的菜单项的索引。索引由引擎自动分配给各个项目，无法手动设置。

String get_item_language(index: int) const 🔗

返回项目文本的语言代码。

Variant get_item_metadata(index: int) const 🔗

返回指定菜单项的元数据，可能是任何类型。可以使用 set_item_metadata 来设置元数据，这样就能很很方便地将上下文数据分配给菜单项。

int get_item_multistate(index: int) const 🔗

返回索引为 index 的菜单项的状态。

int get_item_multistate_max(index: int) const 🔗

返回索引为 index 的菜单项的最大状态数。

Shortcut get_item_shortcut(index: int) const 🔗

返回给定 index 处菜单项所关联的 Shortcut。

String get_item_submenu(index: int) const 🔗

已弃用： Prefer using get_item_submenu_node instead.

返回给定 index 处菜单项的子菜单名称。有关如何添加子菜单的更多信息，请参见 add_submenu_item。

PopupMenu get_item_submenu_node(index: int) const 🔗

返回给定 index 处菜单项的子菜单，如果尚未添加子菜单，则返回 null。有关如何添加子菜单的更多信息，请参阅 add_submenu_node_item。

String get_item_text(index: int) const 🔗

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

TextDirection get_item_text_direction(index: int) const 🔗

返回项目文本的基础书写方向。

String get_item_tooltip(index: int) const 🔗

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

bool is_item_checkable(index: int) const 🔗

如果给定 index 处的菜单项可以某种方式勾选，即如果它有一个复选框或单选按钮，则返回 true。

注意：可勾选项仅显示一个勾选标记或单选按钮，但没有任何内置的勾选行为，必须手动勾选/取消勾选。

bool is_item_checked(index: int) const 🔗

如果给定的 index 处的菜单项被勾选，则返回 true。

bool is_item_disabled(index: int) const 🔗

如果给定 index 处的菜单项被禁用，则返回 true。菜单项被禁用时无法被选择，对应的动作也无法被调用。

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

bool is_item_radio_checkable(index: int) const 🔗

如果给定 index 处的菜单项具有单选按钮样式的可勾选性，则返回 true。

注意：这纯粹是装饰性的；必须添加用于单选组中勾选/取消勾选项目的逻辑。

bool is_item_separator(index: int) const 🔗

如果菜单项是分隔符，则返回 true。分隔符会显示为一条线。有关如何添加分隔符的更多信息，请参阅 add_separator。

bool is_item_shortcut_disabled(index: int) const 🔗

如果指定菜单项的快捷方式被禁用，则返回 true。

bool is_native_menu() const 🔗

Returns true if the system native menu is supported and currently used by this PopupMenu.

bool is_system_menu() const 🔗

如果菜单与特殊系统菜单进行了绑定，则返回 true。

void remove_item(index: int) 🔗

从菜单中移除给定 index 处的菜单项。

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

void scroll_to_item(index: int) 🔗

移动滚动视图，使位于给定 index 的菜单项可见。

void set_focused_item(index: int) 🔗

将当前聚焦的菜单项设置为给定的 index。

将 -1 作为索引传入将不会聚焦任何菜单项。

void set_item_accelerator(index: int, accel: Key) 🔗

在给定的 index 处设置项目的加速器。加速器是一种键盘快捷键，即使当前未打开菜单按钮，也可以按下它来触发菜单按钮。accel 通常是 KeyModifierMask 和 Key 使用按位或操作的组合，例如 KEY_MASK_CTRL | KEY_A（Ctrl + A）。

void set_item_as_checkable(index: int, enable: bool) 🔗

设置给定 index 处的项是否具有一个复选框。如果为 false，则将项的类型设置为纯文本。

注意：可勾选的项只显示一个复选标记，但没有任何内置的勾选行为，必须手动勾选/取消勾选。

void set_item_as_radio_checkable(index: int, enable: bool) 🔗

将给定 index 处的项的类型设置为一个单选按钮。如果为 false，则将项的类型设置为纯文本。

void set_item_as_separator(index: int, enable: bool) 🔗

将给定 index 处的项标记为分隔符，这意味着它将显示为直线段。如果为 false，则将项的类型设置为纯文本。

void set_item_checked(index: int, checked: bool) 🔗

设置位于给定的 index 的菜单项的勾选状态。

void set_item_disabled(index: int, disabled: bool) 🔗

启用/禁用位于给定 index 的菜单项。处于禁用状态的菜单项无法被选中，也无法调用其动作。

void set_item_icon(index: int, icon: Texture2D) 🔗

替换索引为 index 的菜单项的 Texture2D 图标。

void set_item_icon_max_width(index: int, width: int) 🔗

设置给定 index 处菜单项所允许的最大图标宽度。这是在图标默认大小和 icon_max_width 的基础上的限制。高度会根据图标的长宽比调整。

void set_item_icon_modulate(index: int, modulate: Color) 🔗

设置索引为 index 的菜单项图标的调制 Color。

void set_item_id(index: int, id: int) 🔗

设置位于给定 index 的菜单项的 id。

id_pressed 和 id_focused 等信号中会用到 id。

void set_item_indent(index: int, indent: int) 🔗

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

void set_item_language(index: int, language: String) 🔗

设置项目文本的语言代码，用于断行和文本塑形算法，如果留空则使用当前区域设置。

void set_item_metadata(index: int, metadata: Variant) 🔗

设置项的元数据，该项可以是任何类型。稍后你可以使用get_item_metadata获取它，它提供了一种将上下文数据分配给项的简单方法。

void set_item_multistate(index: int, state: int) 🔗

设置一个多态项目的状态。详情请参阅 add_multistate_item。

void set_item_multistate_max(index: int, max_states: int) 🔗

设置多状态菜单项的最大状态数。详见 add_multistate_item。

void set_item_shortcut(index: int, shortcut: Shortcut, global: bool = false) 🔗

设置索引为 index 的菜单项的 Shortcut。

void set_item_shortcut_disabled(index: int, disabled: bool) 🔗

禁用索引为 index 的菜单项的 Shortcut。

void set_item_submenu(index: int, submenu: String) 🔗

已弃用： Prefer using set_item_submenu_node instead.

设置位于给定 index 的菜单项的子菜单。子菜单为点击该菜单项后应该显示的子 PopupMenu 节点的名称。

void set_item_submenu_node(index: int, submenu: PopupMenu) 🔗

设置给定 index 处的项目的子菜单。子菜单是一个 PopupMenu 节点，点击该项目时将显示该节点。它必须是该 PopupMenu 的子级或没有父级（在这种情况下，它将自动添加为子级）。如果 submenu 弹出窗口有另一个父级，则该方法将失败。

void set_item_text(index: int, text: String) 🔗

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

void set_item_text_direction(index: int, direction: TextDirection) 🔗

设置项目文本的基础书写方向。

void set_item_tooltip(index: int, tooltip: String) 🔗

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

void toggle_item_checked(index: int) 🔗

切换索引为 index 的菜单项的选中状态。

void toggle_item_multistate(index: int) 🔗

循环到一个多态项目的下一个状态。详情请参阅 add_multistate_item。

主题属性说明

Color font_accelerator_color = Color(0.7, 0.7, 0.7, 0.8) 🔗

文本 Color 用于快捷键和加速器，当定义时显示在菜单项名称旁边。有关加速器的更多信息，请参阅 get_item_accelerator。

Color font_color = Color(0.875, 0.875, 0.875, 1) 🔗

菜单项名称的默认文本 Color。

Color font_disabled_color = Color(0.4, 0.4, 0.4, 0.8) 🔗

用于禁用菜单项的文本 Color。

Color font_hover_color = Color(0.875, 0.875, 0.875, 1) 🔗

用于悬停文本的 Color。

Color font_outline_color = Color(0, 0, 0, 1) 🔗

菜单项文本轮廓的色调。

Color font_separator_color = Color(0.875, 0.875, 0.875, 1) 🔗

用于标注分隔符文本的颜色 Color。见 add_separator。

Color font_separator_outline_color = Color(0, 0, 0, 1) 🔗

带标签分隔符的文本轮廓的色调。

int h_separation = 4 🔗

菜单项元素之间的水平间距。

int icon_max_width = 0 🔗

菜单项图标所允许的最大宽度。这是在图标默认大小的基础上的限制，在 set_item_icon_max_width 所设置的值之前生效。高度会根据图标的长宽比调整。

int indent = 10 🔗

单个缩进级别的宽度。

int item_end_padding = 2 🔗

所有菜单项右侧的水平内边距（RTL 布局中为左侧）。

int item_start_padding = 2 🔗

所有菜单项左侧的水平内边距（RTL 布局中为右侧）。

int outline_size = 0 🔗

项目文本轮廓的大小。

注意：如果使用启用了 FontFile.multichannel_signed_distance_field 的字体，其 FontFile.msdf_pixel_range 必须至少设置为 outline_size 的两倍，轮廓渲染才能看起来正确。否则，轮廓可能会比预期的更早被切断。

int separator_outline_size = 0 🔗

带标签分隔符的文本轮廓的大小。

int v_separation = 4 🔗

每个菜单项之间的垂直间距。

Font font 🔗

用于菜单项的 Font 字体。

Font font_separator 🔗

用于带文字分隔线的 Font 字体。

int font_separator_size 🔗

带标签分隔符的字体大小。

int font_size 🔗

菜单项的字体大小。

Texture2D checked 🔗

Texture2D 图标，用于处于选中状态的复选项。

Texture2D checked_disabled 🔗

Texture2D 图标，用于处于选中状态的已禁用复选项。

Texture2D radio_checked 🔗

Texture2D 图标，用于处于选中状态的单选项。

Texture2D radio_checked_disabled 🔗

Texture2D 图标，用于处于选中状态的已禁用单选项。

Texture2D radio_unchecked 🔗

Texture2D 图标，用于处于未选状态的单选项。

Texture2D radio_unchecked_disabled 🔗

Texture2D 图标，用于处于未选状态的已禁用单选项。

Texture2D submenu 🔗

Texture2D 图标，用于子菜单箭头（用于从左至右布局）。

Texture2D submenu_mirrored 🔗

Texture2D 图标，用于子菜单箭头（用于从右至左布局）。

Texture2D unchecked 🔗

Texture2D 图标，用于处于未选状态的复选项。

Texture2D unchecked_disabled 🔗

Texture2D 图标，用于处于未选状态的已禁用复选项。

StyleBox hover 🔗

当 PopupMenu 菜单项被悬停时显示的 StyleBox。

StyleBox labeled_separator_left 🔗

用于标签分隔器的左侧 StyleBox。请参阅 add_separator。

StyleBox labeled_separator_right 🔗

用于标签分隔器的右侧 StyleBox。请参阅 add_separator。

StyleBox panel 🔗

用于背景面板的 StyleBox。

StyleBox separator 🔗

用于分隔符的 StyleBox。请参阅 add_separator。