Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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。

属性

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_up 或 ProjectSettings.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_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 的菜单项可见。