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 is a type of button that brings up a dropdown with selectable items when pressed. The item selected becomes the "current" item and is displayed as the button text.

See also BaseButton which contains common properties and methods associated with this node.

Note: The IDs used for items are limited to signed 32-bit integers, not the full 64 bits of int. These have a range of -2^31 to 2^31 - 1, that is, -2147483648 to 2147483647.

Note: The Button.text and Button.icon properties are set automatically based on the selected item. They shouldn't be changed manually.

屬性

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
bool	popup/item_{index}/disabled	false
Texture2D	popup/item_{index}/icon
int	popup/item_{index}/id	0
bool	popup/item_{index}/separator	false
String	popup/item_{index}/text	""
bool	search_bar_enabled	false
bool	search_bar_fuzzy_search_enabled	true
int	search_bar_fuzzy_search_max_misses	2
int	search_bar_min_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()
AutoTranslateMode	get_item_auto_translate_mode(idx: int) const
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_auto_translate_mode(idx: int, mode: AutoTranslateMode)
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) 🔗

Emitted when the user navigates to an item using the ProjectSettings.input/ui_up or ProjectSettings.input/ui_down input actions. The index of the item focused is passed as argument.

---

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

可供挑選的功能表專案的數量。

---

bool popup/item_{index}/disabled = false 🔗

If true, the item at index is disabled.

Note: index is a value in the 0 .. item_count - 1 range.

---

Texture2D popup/item_{index}/icon 🔗

The icon of the item at index.

Note: index is a value in the 0 .. item_count - 1 range.

---

int popup/item_{index}/id = 0 🔗

The ID of the item at index.

Note: index is a value in the 0 .. item_count - 1 range.

---

bool popup/item_{index}/separator = false 🔗

If true, the item at index is a separator.

Note: index is a value in the 0 .. item_count - 1 range.

---

String popup/item_{index}/text = "" 🔗

The text of the item at index.

Note: index is a value in the 0 .. item_count - 1 range.

---

bool search_bar_enabled = false 🔗

• void set_search_bar_enabled(value: bool)

• bool is_search_bar_enabled()

If true, shows a search bar at the top of the PopupMenu for filtering items. See search_bar_min_item_count for dynamically controlling its visibility based on the number of items.

---

bool search_bar_fuzzy_search_enabled = true 🔗

• void set_search_bar_fuzzy_search_enabled(value: bool)

• bool is_search_bar_fuzzy_search_enabled()

If true, enables fuzzy searching in the PopupMenu search bar. This allows the search results to include items that almost match the search query, as well items that match the individual characters of the search query, but not in sequence.

Use search_bar_fuzzy_search_max_misses to set the maximum number of mismatches allowed in the search results.

---

int search_bar_fuzzy_search_max_misses = 2 🔗

• void set_search_bar_fuzzy_search_max_misses(value: int)

• int get_search_bar_fuzzy_search_max_misses()

Sets the maximum number of mismatches allowed in each search result when fuzzy searching is enabled for the PopupMenu search bar. Any item with more mismatches will be hidden from the search results.

---

int search_bar_min_item_count = 0 🔗

• void set_search_bar_min_item_count(value: int)

• int get_search_bar_min_item_count()

Sets the minimum number of items required for the PopupMenu search bar to be visible. search_bar_enabled must be true for this to have any effect.

---

int selected = -1 🔗

• int get_selected()

目前選定項的索引，如果沒有選定項，則為-1。

---

方法說明

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

Adds an item, with a texture icon, text label and (optionally) id. If no id is passed, the item index will be used as the item's ID. New items are appended at the end.

Note: The item will be selected if there are no other items.

---

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

Adds an item, with text label and (optionally) id. If no id is passed, the item index will be used as the item's ID. New items are appended at the end.

Note: The item will be selected if there are no other items.

---

void add_separator(text: String = "") 🔗

在功能表專案列表中新增分隔符號。分隔符號可以用來對功能表專案進行群組，還可以給出標題文字 text。分隔符號也設有索引，會追加到功能表專案列表的末尾。

---

void clear() 🔗

清除OptionButton中的所有專案。

---

AutoTranslateMode get_item_auto_translate_mode(idx: int) const 🔗

Returns the auto translate mode of the item at index idx.

---

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_auto_translate_mode(idx: int, mode: AutoTranslateMode) 🔗

Sets the auto translate mode of the item at index idx.

Items use Node.AUTO_TRANSLATE_MODE_INHERIT by default, which uses the same auto translate mode as the OptionButton itself.

---

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 🔗

要繪製在按鈕右側的箭頭圖示。