Up to date

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

OptionButton

继承: Button < BaseButton < Control < CanvasItem < Node < Object

按下时弹出下拉菜单的按钮。

描述

OptionButton 是一种按下时弹出下拉菜单的按钮。选中的菜单项会成为“当前”菜单项,作为按钮文本显示。

另见 BaseButton,其中包含与此节点相关联的通用属性和方法。

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

注意:Button.textButton.icon 属性会根据当前所选菜单项自动设置。不应该手动更改。

属性

ActionMode

action_mode

0 (overrides BaseButton)

HorizontalAlignment

alignment

0 (overrides Button)

bool

allow_reselect

false

bool

fit_to_longest_item

true

int

item_count

0

int

selected

-1

bool

toggle_mode

true (overrides BaseButton)

方法

void

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

void

add_item ( String label, int id=-1 )

void

add_separator ( String text="" )

void

clear ( )

Texture2D

get_item_icon ( int idx ) const

int

get_item_id ( int idx ) const

int

get_item_index ( int id ) const

Variant

get_item_metadata ( int idx ) const

String

get_item_text ( int idx ) const

String

get_item_tooltip ( int idx ) const

PopupMenu

get_popup ( ) const

int

get_selectable_item ( bool from_last=false ) const

int

get_selected_id ( ) const

Variant

get_selected_metadata ( ) const

bool

has_selectable_items ( ) const

bool

is_item_disabled ( int idx ) const

bool

is_item_separator ( int idx ) const

void

remove_item ( int idx )

void

select ( int idx )

void

set_disable_shortcuts ( bool disabled )

void

set_item_disabled ( int idx, bool disabled )

void

set_item_icon ( int idx, Texture2D texture )

void

set_item_id ( int idx, int id )

void

set_item_metadata ( int idx, Variant metadata )

void

set_item_text ( int idx, String text )

void

set_item_tooltip ( int idx, String tooltip )

void

show_popup ( )

主题属性

int

arrow_margin

4

int

modulate_arrow

0

Texture2D

arrow


信号

item_focused ( int index )

当用户使用 ProjectSettings.input/ui_upProjectSettings.input/ui_down 输入动作导航到某个项目时发出。所选项目的索引将作为参数传递。


item_selected ( int index )

当用户更改当前项时触发。所选项目的索引作为参数传递。

必须启用 allow_reselect 才能重新选中项目。


属性说明

bool allow_reselect = false

  • void set_allow_reselect ( bool value )

  • bool get_allow_reselect ( )

如果为 true,则可以再次选择当前选中的项目。


bool fit_to_longest_item = true

  • void set_fit_to_longest_item ( bool value )

  • bool is_fit_to_longest_item ( )

如果为 true,最小尺寸将由最长项目的文本确定,而不是当前选定的文本。

注意:出于性能原因,在添加、移除、或修改项目时,最小尺寸不会立即更新。


int item_count = 0

  • void set_item_count ( int value )

  • int get_item_count ( )

可供挑选的菜单项的数量。


int selected = -1

  • int get_selected ( )

当前选定项的索引,如果没有选定项,则为-1


方法说明

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

添加一个菜单项,图标为 texture,文本为 label,(可选)ID 为 id。如果没有传入 id,则会将菜单项的索引用作 ID。新菜单项会追加到末尾。


void add_item ( String label, int id=-1 )

添加一个菜单项,文本为 label,(可选)ID 为 id。如果没有传入 id,则会将菜单项的索引用作 ID。新菜单项会追加到末尾。


void add_separator ( String text="" )

在菜单项列表中添加分隔符。分隔符可以用来对菜单项进行分组,还可以给出标题文本 text。分隔符也设有索引,会追加到菜单项列表的末尾。


void clear ( )

清除OptionButton中的所有项目。


Texture2D get_item_icon ( int idx ) const

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


int get_item_id ( int idx ) const

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


int get_item_index ( int id ) const

返回 ID 为 id 的菜单项的索引。


Variant get_item_metadata ( int idx ) const

检索项的元数据。元数据可以是任何类型,并可用于存储关于项的额外信息,如外部字符串ID。


String get_item_text ( int idx ) const

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


String get_item_tooltip ( int idx ) const

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


PopupMenu get_popup ( ) const

返回这个按钮中包含的 PopupMenu

警告:这是一个必需的内部节点,移除和释放它可能会导致崩溃。如果你想隐藏它或它的任何子节点,请使用其 Window.visible 属性。


int get_selectable_item ( bool from_last=false ) const

返回第一个处于非禁用状态或被标记为分隔符的菜单项的索引。如果 from_lasttrue,则会逆序搜索菜单项。

如果没有找到则返回 -1


int get_selected_id ( ) const

返回所选项目的 ID,如果没有选择项目,则返回 -1


Variant get_selected_metadata ( ) const

获取选定项的元数据。可以使用 set_item_metadata 设置项的元数据。


bool has_selectable_items ( ) const

如果这个按钮至少包含一个未禁用或被标记为分隔符的菜单项,则返回 true


bool is_item_disabled ( int idx ) const

如果索引为 idx 的菜单项被禁用,则返回 true


bool is_item_separator ( int idx ) const

如果索引为 idx 的菜单项被标记为分隔符,则返回 true


void remove_item ( int idx )

移除索引为 idx 的菜单项。


void select ( int idx )

按索引选择项并使其为当前选中项。即使该项是禁用的,这也将起作用。

-1 作为索引传入会取消选中任何当前选中的项目。


void set_disable_shortcuts ( bool disabled )

如果为 true,快捷方式将被禁用,无法用于触发按钮。


void set_item_disabled ( int idx, bool disabled )

设置是否禁用索引为 idx 的菜单项。

处于禁用状态的菜单项在下拉列表中绘制的方式不同,用户无法选中这个菜单项。如果将当前选中的菜单项设为了禁用,则仍然会处于选中状态。


void set_item_icon ( int idx, Texture2D texture )

设置索引为 idx 的菜单项的图标。


void set_item_id ( int idx, int id )

设置索引为 idx 的菜单项的 ID。


void set_item_metadata ( int idx, Variant metadata )

设置项的元数据。元数据可以是任何类型,可以用来存储关于项目的额外信息,比如外部字符串ID。


void set_item_text ( int idx, String text )

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


void set_item_tooltip ( int idx, String tooltip )

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


void show_popup ( )

调整 OptionButton 弹出项的位置和大小,然后显示 PopupMenu。请优先使用这个方法,而不是 get_popup().popup()


主题属性说明

int arrow_margin = 4

箭头图标和按钮的右边缘之间的水平空间。


int modulate_arrow = 0

如果不为 0,箭头图标会与字体颜色进行调制。


Texture2D arrow

要绘制在按钮右侧的箭头图标。