Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

PopupMenu

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

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

描述

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

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

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

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

注意:菜单项的 ID 有 32 位的限制,不是完整 int 的 64 位。取值范围为 -2^322^32 - 1,即 -21474836482147483647

属性

bool

allow_search

true

bool

hide_on_checkable_item_selection

true

bool

hide_on_item_selection

true

bool

hide_on_state_item_selection

false

int

item_count

0

float

submenu_popup_delay

0.3

方法

bool

activate_item_by_event ( InputEvent event, bool for_global_only=false )

void

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

void

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

void

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

void

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

void

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

void

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

void

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

void

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

void

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

void

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

void

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

void

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

void

add_separator ( String label="", int id=-1 )

void

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

void

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

void

clear ( bool free_submenus=false )

int

get_focused_item ( ) const

Key

get_item_accelerator ( int index ) const

Texture2D

get_item_icon ( int index ) const

int

get_item_icon_max_width ( int index ) const

Color

get_item_icon_modulate ( int index ) const

int

get_item_id ( int index ) const

int

get_item_indent ( int index ) const

int

get_item_index ( int id ) const

String

get_item_language ( int index ) const

Variant

get_item_metadata ( int index ) const

Shortcut

get_item_shortcut ( int index ) const

String

get_item_submenu ( int index ) const

String

get_item_text ( int index ) const

TextDirection

get_item_text_direction ( int index ) const

String

get_item_tooltip ( int index ) const

bool

is_item_checkable ( int index ) const

bool

is_item_checked ( int index ) const

bool

is_item_disabled ( int index ) const

bool

is_item_radio_checkable ( int index ) const

bool

is_item_separator ( int index ) const

bool

is_item_shortcut_disabled ( int index ) const

void

remove_item ( int index )

void

scroll_to_item ( int index )

void

set_focused_item ( int index )

void

set_item_accelerator ( int index, Key accel )

void

set_item_as_checkable ( int index, bool enable )

void

set_item_as_radio_checkable ( int index, bool enable )

void

set_item_as_separator ( int index, bool enable )

void

set_item_checked ( int index, bool checked )

void

set_item_disabled ( int index, bool disabled )

void

set_item_icon ( int index, Texture2D icon )

void

set_item_icon_max_width ( int index, int width )

void

set_item_icon_modulate ( int index, Color modulate )

void

set_item_id ( int index, int id )

void

set_item_indent ( int index, int indent )

void

set_item_language ( int index, String language )

void

set_item_metadata ( int index, Variant metadata )

void

set_item_multistate ( int index, int state )

void

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

void

set_item_shortcut_disabled ( int index, bool disabled )

void

set_item_submenu ( int index, String submenu )

void

set_item_text ( int index, String text )

void

set_item_text_direction ( int index, TextDirection direction )

void

set_item_tooltip ( int index, String tooltip )

void

toggle_item_checked ( int index )

void

toggle_item_multistate ( int index )

主题属性

Color

font_accelerator_color

Color(0.7, 0.7, 0.7, 0.8)

Color

font_color

Color(0.875, 0.875, 0.875, 1)

Color

font_disabled_color

Color(0.4, 0.4, 0.4, 0.8)

Color

font_hover_color

Color(0.875, 0.875, 0.875, 1)

Color

font_outline_color

Color(1, 1, 1, 1)

Color

font_separator_color

Color(0.875, 0.875, 0.875, 1)

Color

font_separator_outline_color

Color(1, 1, 1, 1)

int

h_separation

4

int

icon_max_width

0

int

indent

10

int

item_end_padding

2

int

item_start_padding

2

int

outline_size

0

int

separator_outline_size

0

int

v_separation

4

Font

font

Font

font_separator

int

font_separator_size

int

font_size

Texture2D

checked

Texture2D

checked_disabled

Texture2D

radio_checked

Texture2D

radio_checked_disabled

Texture2D

radio_unchecked

Texture2D

radio_unchecked_disabled

Texture2D

submenu

Texture2D

submenu_mirrored

Texture2D

unchecked

Texture2D

unchecked_disabled

StyleBox

hover

StyleBox

labeled_separator_left

StyleBox

labeled_separator_right

StyleBox

separator


信号

id_focused ( int id )

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


id_pressed ( int id )

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

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


index_pressed ( int index )

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


menu_changed ( )

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


属性说明

  • 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_onlytrue,则仅调用 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_echotrue,则快捷键可以被回响事件激活。


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_pressedid_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_echotrue,则快捷键可以被回响事件激活。


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

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

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


void clear ( bool free_submenus=false )

移除 PopupMenu 中的所有项目。如果 free_submenustrue,则自动释放子菜单节点。


int get_focused_item ( ) const

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


Key get_item_accelerator ( int index ) const

返回给定 index 处项目的加速器。加速器是一种键盘快捷键,即使当前未打开菜单按钮,也可以按下它来触发菜单按钮。返回值是一个整数,通常是 KeyModifierMaskKey 使用按位或操作的组合,例如 KEY_MASK_CTRL | KEY_ACtrl + 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 作为索引传入将不会聚