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...

OptionButton

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

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

描述

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

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

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

注意：Button.text 和 Button.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(texture: Texture2D, label: String, id: int = -1)

void

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

void

add_separator(text: String = "")

void

clear()

Texture2D

get_item_icon(idx: int) const

int

get_item_id(idx: int) const

int

get_item_index(id: int) const

Variant

get_item_metadata(idx: int) const

String

get_item_text(idx: int) const

String

get_item_tooltip(idx: int) const

PopupMenu

get_popup() const

int

get_selectable_item(from_last: bool = false) const

int

get_selected_id() const

Variant

get_selected_metadata() const

bool

has_selectable_items() const

bool

is_item_disabled(idx: int) const

bool

is_item_separator(idx: int) const

void

remove_item(idx: int)

void

select(idx: int)

void

set_disable_shortcuts(disabled: bool)

void

set_item_disabled(idx: int, disabled: bool)

void

set_item_icon(idx: int, texture: Texture2D)

void

set_item_id(idx: int, id: int)

void

set_item_metadata(idx: int, metadata: Variant)

void

set_item_text(idx: int, text: String)

void

set_item_tooltip(idx: int, tooltip: String)

void

show_popup()

主题属性

int

arrow_margin

4

int

modulate_arrow

0

Texture2D

arrow

信号

item_focused(index: int) 🔗

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

item_selected(index: int) 🔗

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

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

属性说明

bool allow_reselect = false 🔗

  • void set_allow_reselect(value: bool)

  • bool get_allow_reselect()

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

bool fit_to_longest_item = true 🔗

  • void set_fit_to_longest_item(value: bool)

  • bool is_fit_to_longest_item()

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

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

int item_count = 0 🔗

  • void set_item_count(value: int)

  • int get_item_count()

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

int selected = -1 🔗

  • int get_selected()

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

方法说明

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

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

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

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

void add_separator(text: String = "") 🔗

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

void clear() 🔗

清除OptionButton中的所有项目。

Texture2D get_item_icon(idx: int) const 🔗

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

int get_item_id(idx: int) const 🔗

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

int get_item_index(id: int) const 🔗

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

Variant get_item_metadata(idx: int) const 🔗

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

String get_item_text(idx: int) const 🔗

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

String get_item_tooltip(idx: int) const 🔗

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

PopupMenu get_popup() const 🔗

返回这个按钮中包含的 PopupMenu。

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

int get_selectable_item(from_last: bool = false) const 🔗

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

如果没有找到则返回 -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(idx: int) const 🔗

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

bool is_item_separator(idx: int) const 🔗

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

void remove_item(idx: int) 🔗

移除索引为 idx 的菜单项。

void select(idx: int) 🔗

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

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

void set_disable_shortcuts(disabled: bool) 🔗

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

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

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

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

void set_item_icon(idx: int, texture: Texture2D) 🔗

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

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

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

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

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

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

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

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

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

void show_popup() 🔗

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

主题属性说明

int arrow_margin = 4 🔗

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

int modulate_arrow = 0 🔗

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

Texture2D arrow 🔗

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