Godot
/
godot-docs
mirror of https://github.com/godotengine/godot-docs.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314
							:github_url: hide

.. Generated automatically by doc/tools/makerst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the OptionButton.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_OptionButton:

OptionButton
============

**Inherits:** :ref:`Button<class_Button>` **<** :ref:`BaseButton<class_BaseButton>` **<** :ref:`Control<class_Control>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

Button control that provides selectable options when pressed.

Description
-----------

OptionButton is a type button that provides a selectable list of items when pressed. The item selected becomes the "current" item and is displayed as the button text.

Properties
----------

+-----------------------------------------------+-------------------------------------------------------+-----------------+
| :ref:`ActionMode<enum_BaseButton_ActionMode>` | action_mode                                           | **O:** ``0``    |
+-----------------------------------------------+-------------------------------------------------------+-----------------+
| :ref:`TextAlign<enum_Button_TextAlign>`       | align                                                 | **O:** ``0``    |
+-----------------------------------------------+-------------------------------------------------------+-----------------+
| :ref:`int<class_int>`                         | :ref:`selected<class_OptionButton_property_selected>` | ``-1``          |
+-----------------------------------------------+-------------------------------------------------------+-----------------+
| :ref:`bool<class_bool>`                       | toggle_mode                                           | **O:** ``true`` |
+-----------------------------------------------+-------------------------------------------------------+-----------------+

Methods
-------

+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`add_icon_item<class_OptionButton_method_add_icon_item>` **(** :ref:`Texture2D<class_Texture2D>` texture, :ref:`String<class_String>` label, :ref:`int<class_int>` id=-1 **)** |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`add_item<class_OptionButton_method_add_item>` **(** :ref:`String<class_String>` label, :ref:`int<class_int>` id=-1 **)**                                                      |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`add_separator<class_OptionButton_method_add_separator>` **(** **)**                                                                                                           |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`clear<class_OptionButton_method_clear>` **(** **)**                                                                                                                           |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`             | :ref:`get_item_count<class_OptionButton_method_get_item_count>` **(** **)** const                                                                                                   |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Texture2D<class_Texture2D>` | :ref:`get_item_icon<class_OptionButton_method_get_item_icon>` **(** :ref:`int<class_int>` idx **)** const                                                                           |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`             | :ref:`get_item_id<class_OptionButton_method_get_item_id>` **(** :ref:`int<class_int>` idx **)** const                                                                               |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`             | :ref:`get_item_index<class_OptionButton_method_get_item_index>` **(** :ref:`int<class_int>` id **)** const                                                                          |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>`     | :ref:`get_item_metadata<class_OptionButton_method_get_item_metadata>` **(** :ref:`int<class_int>` idx **)** const                                                                   |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>`       | :ref:`get_item_text<class_OptionButton_method_get_item_text>` **(** :ref:`int<class_int>` idx **)** const                                                                           |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PopupMenu<class_PopupMenu>` | :ref:`get_popup<class_OptionButton_method_get_popup>` **(** **)** const                                                                                                             |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>`             | :ref:`get_selected_id<class_OptionButton_method_get_selected_id>` **(** **)** const                                                                                                 |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>`     | :ref:`get_selected_metadata<class_OptionButton_method_get_selected_metadata>` **(** **)** const                                                                                     |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`           | :ref:`is_item_disabled<class_OptionButton_method_is_item_disabled>` **(** :ref:`int<class_int>` idx **)** const                                                                     |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`remove_item<class_OptionButton_method_remove_item>` **(** :ref:`int<class_int>` idx **)**                                                                                     |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`select<class_OptionButton_method_select>` **(** :ref:`int<class_int>` idx **)**                                                                                               |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`set_item_disabled<class_OptionButton_method_set_item_disabled>` **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` disabled **)**                                       |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`set_item_icon<class_OptionButton_method_set_item_icon>` **(** :ref:`int<class_int>` idx, :ref:`Texture2D<class_Texture2D>` texture **)**                                      |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`set_item_id<class_OptionButton_method_set_item_id>` **(** :ref:`int<class_int>` idx, :ref:`int<class_int>` id **)**                                                           |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`set_item_metadata<class_OptionButton_method_set_item_metadata>` **(** :ref:`int<class_int>` idx, :ref:`Variant<class_Variant>` metadata **)**                                 |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                              | :ref:`set_item_text<class_OptionButton_method_set_item_text>` **(** :ref:`int<class_int>` idx, :ref:`String<class_String>` text **)**                                               |
+-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Theme Properties
----------------

+-----------------------------------+---------------------+------------------------------+
| :ref:`Texture2D<class_Texture2D>` | arrow               |                              |
+-----------------------------------+---------------------+------------------------------+
| :ref:`int<class_int>`             | arrow_margin        | 2                            |
+-----------------------------------+---------------------+------------------------------+
| :ref:`StyleBox<class_StyleBox>`   | disabled            |                              |
+-----------------------------------+---------------------+------------------------------+
| :ref:`StyleBox<class_StyleBox>`   | focus               |                              |
+-----------------------------------+---------------------+------------------------------+
| :ref:`Font<class_Font>`           | font                |                              |
+-----------------------------------+---------------------+------------------------------+
| :ref:`Color<class_Color>`         | font_color          | Color( 0.88, 0.88, 0.88, 1 ) |
+-----------------------------------+---------------------+------------------------------+
| :ref:`Color<class_Color>`         | font_color_disabled | Color( 0.9, 0.9, 0.9, 0.2 )  |
+-----------------------------------+---------------------+------------------------------+
| :ref:`Color<class_Color>`         | font_color_hover    | Color( 0.94, 0.94, 0.94, 1 ) |
+-----------------------------------+---------------------+------------------------------+
| :ref:`Color<class_Color>`         | font_color_pressed  | Color( 1, 1, 1, 1 )          |
+-----------------------------------+---------------------+------------------------------+
| :ref:`StyleBox<class_StyleBox>`   | hover               |                              |
+-----------------------------------+---------------------+------------------------------+
| :ref:`int<class_int>`             | hseparation         | 2                            |
+-----------------------------------+---------------------+------------------------------+
| :ref:`StyleBox<class_StyleBox>`   | normal              |                              |
+-----------------------------------+---------------------+------------------------------+
| :ref:`StyleBox<class_StyleBox>`   | pressed             |                              |
+-----------------------------------+---------------------+------------------------------+

Signals
-------

.. _class_OptionButton_signal_item_focused:

- **item_focused** **(** :ref:`int<class_int>` id **)**

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

----

.. _class_OptionButton_signal_item_selected:

- **item_selected** **(** :ref:`int<class_int>` id **)**

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

Property Descriptions
---------------------

.. _class_OptionButton_property_selected:

- :ref:`int<class_int>` **selected**

+-----------+----------------+
| *Default* | ``-1``         |
+-----------+----------------+
| *Getter*  | get_selected() |
+-----------+----------------+

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

Method Descriptions
-------------------

.. _class_OptionButton_method_add_icon_item:

- void **add_icon_item** **(** :ref:`Texture2D<class_Texture2D>` texture, :ref:`String<class_String>` label, :ref:`int<class_int>` id=-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.

----

.. _class_OptionButton_method_add_item:

- void **add_item** **(** :ref:`String<class_String>` label, :ref:`int<class_int>` id=-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.

----

.. _class_OptionButton_method_add_separator:

- void **add_separator** **(** **)**

Adds a separator to the list of items. Separators help to group items. Separator also takes up an index and is appended at the end.

----

.. _class_OptionButton_method_clear:

- void **clear** **(** **)**

Clears all the items in the ``OptionButton``.

----

.. _class_OptionButton_method_get_item_count:

- :ref:`int<class_int>` **get_item_count** **(** **)** const

Returns the amount of items in the OptionButton, including separators.

----

.. _class_OptionButton_method_get_item_icon:

- :ref:`Texture2D<class_Texture2D>` **get_item_icon** **(** :ref:`int<class_int>` idx **)** const

Returns the icon of the item at index ``idx``.

----

.. _class_OptionButton_method_get_item_id:

- :ref:`int<class_int>` **get_item_id** **(** :ref:`int<class_int>` idx **)** const

Returns the ID of the item at index ``idx``.

----

.. _class_OptionButton_method_get_item_index:

- :ref:`int<class_int>` **get_item_index** **(** :ref:`int<class_int>` id **)** const

Returns the index of the item with the given ``id``.

----

.. _class_OptionButton_method_get_item_metadata:

- :ref:`Variant<class_Variant>` **get_item_metadata** **(** :ref:`int<class_int>` idx **)** 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.

----

.. _class_OptionButton_method_get_item_text:

- :ref:`String<class_String>` **get_item_text** **(** :ref:`int<class_int>` idx **)** const

Returns the text of the item at index ``idx``.

----

.. _class_OptionButton_method_get_popup:

- :ref:`PopupMenu<class_PopupMenu>` **get_popup** **(** **)** const

Returns the :ref:`PopupMenu<class_PopupMenu>` contained in this button.

----

.. _class_OptionButton_method_get_selected_id:

- :ref:`int<class_int>` **get_selected_id** **(** **)** const

Returns the ID of the selected item, or ``0`` if no item is selected.

----

.. _class_OptionButton_method_get_selected_metadata:

- :ref:`Variant<class_Variant>` **get_selected_metadata** **(** **)** const

Gets the metadata of the selected item. Metadata for items can be set using :ref:`set_item_metadata<class_OptionButton_method_set_item_metadata>`.

----

.. _class_OptionButton_method_is_item_disabled:

- :ref:`bool<class_bool>` **is_item_disabled** **(** :ref:`int<class_int>` idx **)** const

Returns ``true`` if the item at index ``idx`` is disabled.

----

.. _class_OptionButton_method_remove_item:

- void **remove_item** **(** :ref:`int<class_int>` idx **)**

Removes the item at index ``idx``.

----

.. _class_OptionButton_method_select:

- void **select** **(** :ref:`int<class_int>` idx **)**

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

----

.. _class_OptionButton_method_set_item_disabled:

- void **set_item_disabled** **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` disabled **)**

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.

----

.. _class_OptionButton_method_set_item_icon:

- void **set_item_icon** **(** :ref:`int<class_int>` idx, :ref:`Texture2D<class_Texture2D>` texture **)**

Sets the icon of the item at index ``idx``.

----

.. _class_OptionButton_method_set_item_id:

- void **set_item_id** **(** :ref:`int<class_int>` idx, :ref:`int<class_int>` id **)**

Sets the ID of the item at index ``idx``.

----

.. _class_OptionButton_method_set_item_metadata:

- void **set_item_metadata** **(** :ref:`int<class_int>` idx, :ref:`Variant<class_Variant>` metadata **)**

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.

----

.. _class_OptionButton_method_set_item_text:

- void **set_item_text** **(** :ref:`int<class_int>` idx, :ref:`String<class_String>` text **)**

Sets the text of the item at index ``idx``.