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 ( int id )

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

id_pressed ( int id )

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

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

index_pressed ( int index )

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

menu_changed ( )

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

属性说明

bool allow_search = true

• void set_allow_search ( bool value )

• bool get_allow_search ( )

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

bool hide_on_checkable_item_selection = true

• void set_hide_on_checkable_item_selection ( bool value )

• bool is_hide_on_checkable_item_selection ( )

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

bool hide_on_item_selection = true

• void set_hide_on_item_selection ( bool value )

• bool is_hide_on_item_selection ( )

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

bool hide_on_state_item_selection = false

• void set_hide_on_state_item_selection ( bool value )

• bool is_hide_on_state_item_selection ( )

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

int item_count = 0

• void set_item_count ( int value )

• int get_item_count ( )

当前列表中的项目数。

float submenu_popup_delay = 0.3

• void set_submenu_popup_delay ( float value )

• float get_submenu_popup_delay ( )

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

方法说明

bool activate_item_by_event ( InputEvent event, bool for_global_only=false )

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void add_item ( String label, int id=-1, Key accel=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 ( String label, int max_states, int default_state=0, int id=-1, Key accel=0 )

添加文本为 label 的新多状态菜单项。

与普通的双态菜单项不同，多状态菜单项的状态可以超过两个，数量由 max_states 定义。菜单项每按下或激活一次，状态就会加一。默认值由 default_state 定义。

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

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

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

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

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

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

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

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

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

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

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

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

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

添加 Shortcut。

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

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

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

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

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

void clear ( bool free_submenus=false )

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

int get_focused_item ( ) const

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

Key get_item_accelerator ( int index ) const

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

Texture2D get_item_icon ( int index ) const

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

int get_item_icon_max_width ( int index ) const

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

Color get_item_icon_modulate ( int index ) const

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

int get_item_id ( int index ) const

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

int get_item_indent ( int index ) const

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

int get_item_index ( int id ) const

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

String get_item_language ( int index ) const

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

Variant get_item_metadata ( int index ) const

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

Shortcut get_item_shortcut ( int index ) const

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

String get_item_submenu ( int index ) const

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

String get_item_text ( int index ) const

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

TextDirection get_item_text_direction ( int index ) const

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

String get_item_tooltip ( int index ) const

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

bool is_item_checkable ( int index ) const

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

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

bool is_item_checked ( int index ) const

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

bool is_item_disabled ( int index ) const

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

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

bool is_item_radio_checkable ( int index ) const

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

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

bool is_item_separator ( int index ) const

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

bool is_item_shortcut_disabled ( int index ) const

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

void remove_item ( int index )

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

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

void scroll_to_item ( int index )

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

void set_focused_item ( int index )

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

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

void set_item_accelerator ( int index, Key accel )

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

void set_item_as_checkable ( int index, bool enable )

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

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

void set_item_as_radio_checkable ( int index, bool enable )

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

void set_item_as_separator ( int index, bool enable )

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

void set_item_checked ( int index, bool checked )

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

void set_item_disabled ( int index, bool disabled )

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

void set_item_icon ( int index, Texture2D icon )

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

void set_item_icon_max_width ( int index, int width )

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

void set_item_icon_modulate ( int index, Color modulate )

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

void set_item_id ( int index, int id )

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

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

void set_item_indent ( int index, int indent )

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

void set_item_language ( int index, String language )

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

void set_item_metadata ( int index, Variant metadata )

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

void set_item_multistate ( int index, int state )

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

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

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

void set_item_shortcut_disabled ( int index, bool disabled )

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

void set_item_submenu ( int index, String submenu )

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

void set_item_text ( int index, String text )

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

void set_item_text_direction ( int index, TextDirection direction )

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

void set_item_tooltip ( int index, String tooltip )

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

void toggle_item_checked ( int index )

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

void toggle_item_multistate ( int index )

循环到一个多态项目的下一个状态。详情请参阅 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(1, 1, 1, 1)

菜单项文本轮廓的色调。

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

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

Color font_separator_outline_color = Color(1, 1, 1, 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 separator

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

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.