Class OptionButton

A button that brings up a dropdown with selectable options when pressed.

Inheritance

Button

BaseButton

Control

CanvasItem

Node

Object

OptionButton

Remarks

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 ID values used for items are limited to 32 bits, not full 64 bits of int. This has a range of -2^32 to 2^32 - 1, i.e. -2147483648 to 2147483647.

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

Properties

allow_reselect

If true, the currently selected item can be selected again.

var allow_reselect : bool = false

Property Value

bool

Remarks

• void set_allow_reselect(bool value)
• bool get_allow_reselect

fit_to_longest_item

If true, minimum size will be determined by the longest item's text, instead of the currently selected one's.

Note: For performance reasons, the minimum size doesn't update immediately when adding, removing or modifying items.

var fit_to_longest_item : bool = true

Property Value

bool

Remarks

• void set_fit_to_longest_item(bool value)
• bool is_fit_to_longest_item

item_count

The number of items to select from.

var item_count : int = 0

Property Value

int

Remarks

• void set_item_count(int value)
• int get_item_count

selected

The index of the currently selected item, or -1 if no item is selected.

var selected : int = -1

Property Value

int

Remarks

• int get_selected

arrow_margin

Theme Property

The horizontal space between the arrow icon and the right edge of the button.

 = ``4``

Property Value

int

modulate_arrow

Theme Property

If different than 0, the arrow icon will be modulated to the font color.

 = ``0``

Property Value

int

arrow

Theme Property

The arrow icon to be drawn on the right end of the button.

Texture2D arrow

Property Value

Texture2D

Methods

add_icon_item(Texture2D, String, int)

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.

void add_icon_item(Texture2D texture, String label, int id)

Parameters

texture Texture2D

label String

id int

add_item(String, int)

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.

void add_item(String label, int id)

Parameters

label String

id int

add_separator(String)

Adds a separator to the list of items. Separators help to group items, and can optionally be given a text header. A separator also gets an index assigned, and is appended at the end of the item list.

void add_separator(String text)

Parameters

text String

clear

Clears all the items in the OptionButton.

void clear

get_item_icon(int)

Qualifiers: const

Returns the icon of the item at index idx.

Texture2D get_item_icon(int idx)

Parameters

idx int

get_item_id(int)

Qualifiers: const

Returns the ID of the item at index idx.

int get_item_id(int idx)

Parameters

idx int

get_item_index(int)

Qualifiers: const

Returns the index of the item with the given id.

int get_item_index(int id)

Parameters

id int

get_item_metadata(int)

Qualifiers: const

Retrieves the metadata of an item. Metadata may be any type and can be used to store extra information about an item, such as an external string ID.

Variant get_item_metadata(int idx)

Parameters

idx int

get_item_text(int)

Qualifiers: const

Returns the text of the item at index idx.

String get_item_text(int idx)

Parameters

idx int

get_item_tooltip(int)

Qualifiers: const

Returns the tooltip of the item at index idx.

String get_item_tooltip(int idx)

Parameters

idx int

get_popup

Qualifiers: const

Returns the PopupMenu contained in this button.

Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their visible property.

PopupMenu get_popup

get_selectable_item(bool)

Qualifiers: const

Returns the index of the first item which is not disabled, or marked as a separator. If from_last is true, the items will be searched in reverse order.

Returns -1 if no item is found.

int get_selectable_item(bool from_last)

Parameters

from_last bool

get_selected_id

Qualifiers: const

Returns the ID of the selected item, or -1 if no item is selected.

int get_selected_id

get_selected_metadata

Qualifiers: const

Gets the metadata of the selected item. Metadata for items can be set using OptionButton.set_item_metadata.

Variant get_selected_metadata

has_selectable_items

Qualifiers: const

Returns true if this button contains at least one item which is not disabled, or marked as a separator.

bool has_selectable_items

is_item_disabled(int)

Qualifiers: const

Returns true if the item at index idx is disabled.

bool is_item_disabled(int idx)

Parameters

idx int

is_item_separator(int)

Qualifiers: const

Returns true if the item at index idx is marked as a separator.

bool is_item_separator(int idx)

Parameters

idx int

remove_item(int)

Removes the item at index idx.

void remove_item(int idx)

Parameters

idx int

select(int)

Selects an item by index and makes it the current item. This will work even if the item is disabled.

Passing -1 as the index deselects any currently selected item.

void select(int idx)

Parameters

idx int

set_disable_shortcuts(bool)

If true, shortcuts are disabled and cannot be used to trigger the button.

void set_disable_shortcuts(bool disabled)

Parameters

disabled bool

set_item_disabled(int, bool)

Sets whether the item at index idx is disabled.

Disabled items are drawn differently in the dropdown and are not selectable by the user. If the current selected item is set as disabled, it will remain selected.

void set_item_disabled(int idx, bool disabled)

Parameters

idx int

disabled bool

set_item_icon(int, Texture2D)

Sets the icon of the item at index idx.

void set_item_icon(int idx, Texture2D texture)

Parameters

idx int

texture Texture2D

set_item_id(int, int)

Sets the ID of the item at index idx.

void set_item_id(int idx, int id)

Parameters

idx int

id int

set_item_metadata(int, Variant)

Sets the metadata of an item. Metadata may be of any type and can be used to store extra information about an item, such as an external string ID.

void set_item_metadata(int idx, Variant metadata)

Parameters

idx int

metadata Variant

set_item_text(int, String)

Sets the text of the item at index idx.

void set_item_text(int idx, String text)

Parameters

idx int

text String

set_item_tooltip(int, String)

Sets the tooltip of the item at index idx.

void set_item_tooltip(int idx, String tooltip)

Parameters

idx int

tooltip String

show_popup

Adjusts popup position and sizing for the OptionButton, then shows the PopupMenu. Prefer this over using get_popup().popup().

void show_popup

Events

item_focused(int)

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

signal item_focused(int index)

Parameters

index int

item_selected(int)

Emitted when the current item has been changed by the user. The index of the item selected is passed as argument.

allow_reselect must be enabled to reselect an item.

signal item_selected(int index)

Parameters

index int