:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/OptionButton.xml. .. _class_OptionButton: OptionButton ============ **Inherits:** :ref:`Button` **<** :ref:`BaseButton` **<** :ref:`Control` **<** :ref:`CanvasItem` **<** :ref:`Node` **<** :ref:`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. See also :ref:`BaseButton` which contains common properties and methods associated with this node. \ **Note:** Properties :ref:`Button.text` and :ref:`Button.icon` are automatically set based on the selected item. They shouldn't be changed manually. Properties ---------- +-------------------------------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`ActionMode` | action_mode | ``0`` (overrides :ref:`BaseButton`) | +-------------------------------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`HorizontalAlignment` | alignment | ``0`` (overrides :ref:`Button`) | +-------------------------------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`int` | :ref:`item_count` | ``0`` | +-------------------------------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`int` | :ref:`selected` | ``-1`` | +-------------------------------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`bool` | toggle_mode | ``true`` (overrides :ref:`BaseButton`) | +-------------------------------------------------------------------+-----------------------------------------------------------+-------------------------------------------------------------------------------+ Methods ------- +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_icon_item` **(** :ref:`Texture2D` texture, :ref:`String` label, :ref:`int` id=-1 **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_item` **(** :ref:`String` label, :ref:`int` id=-1 **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`add_separator` **(** :ref:`String` text="" **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`clear` **(** **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Texture2D` | :ref:`get_item_icon` **(** :ref:`int` idx **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_item_id` **(** :ref:`int` idx **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_item_index` **(** :ref:`int` id **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_item_metadata` **(** :ref:`int` idx **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_item_text` **(** :ref:`int` idx **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_item_tooltip` **(** :ref:`int` idx **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PopupMenu` | :ref:`get_popup` **(** **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_selectable_item` **(** :ref:`bool` from_last=false **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_selected_id` **(** **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`get_selected_metadata` **(** **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_selectable_items` **(** **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_item_disabled` **(** :ref:`int` idx **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_item_separator` **(** :ref:`int` idx **)** |const| | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`remove_item` **(** :ref:`int` idx **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`select` **(** :ref:`int` idx **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_item_disabled` **(** :ref:`int` idx, :ref:`bool` disabled **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_item_icon` **(** :ref:`int` idx, :ref:`Texture2D` texture **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_item_id` **(** :ref:`int` idx, :ref:`int` id **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_item_metadata` **(** :ref:`int` idx, :ref:`Variant` metadata **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_item_text` **(** :ref:`int` idx, :ref:`String` text **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`set_item_tooltip` **(** :ref:`int` idx, :ref:`String` tooltip **)** | +-----------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Theme Properties ---------------- +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Color` | :ref:`font_color` | ``Color(0.875, 0.875, 0.875, 1)`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Color` | :ref:`font_disabled_color` | ``Color(0.875, 0.875, 0.875, 0.5)`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Color` | :ref:`font_focus_color` | ``Color(0.95, 0.95, 0.95, 1)`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Color` | :ref:`font_hover_color` | ``Color(0.95, 0.95, 0.95, 1)`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Color` | :ref:`font_outline_color` | ``Color(1, 1, 1, 1)`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Color` | :ref:`font_pressed_color` | ``Color(1, 1, 1, 1)`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`int` | :ref:`arrow_margin` | ``4`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`int` | :ref:`h_separation` | ``2`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`int` | :ref:`outline_size` | ``0`` | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Font` | :ref:`font` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`int` | :ref:`font_size` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Texture2D` | :ref:`arrow` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`disabled` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`disabled_mirrored` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`focus` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`hover` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`hover_mirrored` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`normal` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`normal_mirrored` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`pressed` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ | :ref:`StyleBox` | :ref:`pressed_mirrored` | | +-----------------------------------+--------------------------------------------------------------------------------+-------------------------------------+ Signals ------- .. _class_OptionButton_signal_item_focused: - **item_focused** **(** :ref:`int` index **)** Emitted when the 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` index **)** 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_item_count: - :ref:`int` **item_count** +-----------+-----------------------+ | *Default* | ``0`` | +-----------+-----------------------+ | *Setter* | set_item_count(value) | +-----------+-----------------------+ | *Getter* | get_item_count() | +-----------+-----------------------+ The number of items to select from. ---- .. _class_OptionButton_property_selected: - :ref:`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` texture, :ref:`String` label, :ref:`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` label, :ref:`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** **(** :ref:`String` text="" **)** 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. ---- .. _class_OptionButton_method_clear: - void **clear** **(** **)** Clears all the items in the ``OptionButton``. ---- .. _class_OptionButton_method_get_item_icon: - :ref:`Texture2D` **get_item_icon** **(** :ref:`int` idx **)** |const| Returns the icon of the item at index ``idx``. ---- .. _class_OptionButton_method_get_item_id: - :ref:`int` **get_item_id** **(** :ref:`int` idx **)** |const| Returns the ID of the item at index ``idx``. ---- .. _class_OptionButton_method_get_item_index: - :ref:`int` **get_item_index** **(** :ref:`int` id **)** |const| Returns the index of the item with the given ``id``. ---- .. _class_OptionButton_method_get_item_metadata: - :ref:`Variant` **get_item_metadata** **(** :ref:`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` **get_item_text** **(** :ref:`int` idx **)** |const| Returns the text of the item at index ``idx``. ---- .. _class_OptionButton_method_get_item_tooltip: - :ref:`String` **get_item_tooltip** **(** :ref:`int` idx **)** |const| Returns the tooltip of the item at index ``idx``. ---- .. _class_OptionButton_method_get_popup: - :ref:`PopupMenu` **get_popup** **(** **)** |const| Returns the :ref:`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 :ref:`Window.visible` property. ---- .. _class_OptionButton_method_get_selectable_item: - :ref:`int` **get_selectable_item** **(** :ref:`bool` from_last=false **)** |const| ---- .. _class_OptionButton_method_get_selected_id: - :ref:`int` **get_selected_id** **(** **)** |const| Returns the ID of the selected item, or ``-1`` if no item is selected. ---- .. _class_OptionButton_method_get_selected_metadata: - :ref:`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_has_selectable_items: - :ref:`bool` **has_selectable_items** **(** **)** |const| ---- .. _class_OptionButton_method_is_item_disabled: - :ref:`bool` **is_item_disabled** **(** :ref:`int` idx **)** |const| Returns ``true`` if the item at index ``idx`` is disabled. ---- .. _class_OptionButton_method_is_item_separator: - :ref:`bool` **is_item_separator** **(** :ref:`int` idx **)** |const| ---- .. _class_OptionButton_method_remove_item: - void **remove_item** **(** :ref:`int` idx **)** Removes the item at index ``idx``. ---- .. _class_OptionButton_method_select: - void **select** **(** :ref:`int` idx **)** 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. ---- .. _class_OptionButton_method_set_item_disabled: - void **set_item_disabled** **(** :ref:`int` idx, :ref:`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` idx, :ref:`Texture2D` texture **)** Sets the icon of the item at index ``idx``. ---- .. _class_OptionButton_method_set_item_id: - void **set_item_id** **(** :ref:`int` idx, :ref:`int` id **)** Sets the ID of the item at index ``idx``. ---- .. _class_OptionButton_method_set_item_metadata: - void **set_item_metadata** **(** :ref:`int` idx, :ref:`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` idx, :ref:`String` text **)** Sets the text of the item at index ``idx``. ---- .. _class_OptionButton_method_set_item_tooltip: - void **set_item_tooltip** **(** :ref:`int` idx, :ref:`String` tooltip **)** Sets the tooltip of the item at index ``idx``. Theme Property Descriptions --------------------------- .. _class_OptionButton_theme_color_font_color: - :ref:`Color` **font_color** +-----------+-----------------------------------+ | *Default* | ``Color(0.875, 0.875, 0.875, 1)`` | +-----------+-----------------------------------+ Default text :ref:`Color` of the ``OptionButton``. ---- .. _class_OptionButton_theme_color_font_disabled_color: - :ref:`Color` **font_disabled_color** +-----------+-------------------------------------+ | *Default* | ``Color(0.875, 0.875, 0.875, 0.5)`` | +-----------+-------------------------------------+ Text :ref:`Color` used when the ``OptionButton`` is disabled. ---- .. _class_OptionButton_theme_color_font_focus_color: - :ref:`Color` **font_focus_color** +-----------+--------------------------------+ | *Default* | ``Color(0.95, 0.95, 0.95, 1)`` | +-----------+--------------------------------+ Text :ref:`Color` used when the ``OptionButton`` is focused. Only replaces the normal text color of the button. Disabled, hovered, and pressed states take precedence over this color. ---- .. _class_OptionButton_theme_color_font_hover_color: - :ref:`Color` **font_hover_color** +-----------+--------------------------------+ | *Default* | ``Color(0.95, 0.95, 0.95, 1)`` | +-----------+--------------------------------+ Text :ref:`Color` used when the ``OptionButton`` is being hovered. ---- .. _class_OptionButton_theme_color_font_outline_color: - :ref:`Color` **font_outline_color** +-----------+-----------------------+ | *Default* | ``Color(1, 1, 1, 1)`` | +-----------+-----------------------+ The tint of text outline of the ``OptionButton``. ---- .. _class_OptionButton_theme_color_font_pressed_color: - :ref:`Color` **font_pressed_color** +-----------+-----------------------+ | *Default* | ``Color(1, 1, 1, 1)`` | +-----------+-----------------------+ Text :ref:`Color` used when the ``OptionButton`` is being pressed. ---- .. _class_OptionButton_theme_constant_arrow_margin: - :ref:`int` **arrow_margin** +-----------+-------+ | *Default* | ``4`` | +-----------+-------+ The horizontal space between the arrow icon and the right edge of the button. ---- .. _class_OptionButton_theme_constant_h_separation: - :ref:`int` **h_separation** +-----------+-------+ | *Default* | ``2`` | +-----------+-------+ The horizontal space between ``OptionButton``'s icon and text. ---- .. _class_OptionButton_theme_constant_outline_size: - :ref:`int` **outline_size** +-----------+-------+ | *Default* | ``0`` | +-----------+-------+ The size of the text outline. ---- .. _class_OptionButton_theme_font_font: - :ref:`Font` **font** :ref:`Font` of the ``OptionButton``'s text. ---- .. _class_OptionButton_theme_font_size_font_size: - :ref:`int` **font_size** Font size of the ``OptionButton``'s text. ---- .. _class_OptionButton_theme_icon_arrow: - :ref:`Texture2D` **arrow** The arrow icon to be drawn on the right end of the button. ---- .. _class_OptionButton_theme_style_disabled: - :ref:`StyleBox` **disabled** :ref:`StyleBox` used when the ``OptionButton`` is disabled (for left-to-right layouts). ---- .. _class_OptionButton_theme_style_disabled_mirrored: - :ref:`StyleBox` **disabled_mirrored** :ref:`StyleBox` used when the ``OptionButton`` is disabled (for right-to-left layouts). ---- .. _class_OptionButton_theme_style_focus: - :ref:`StyleBox` **focus** :ref:`StyleBox` used when the ``OptionButton`` is focused. The ``focus`` :ref:`StyleBox` is displayed *over* the base :ref:`StyleBox`, so a partially transparent :ref:`StyleBox` should be used to ensure the base :ref:`StyleBox` remains visible. A :ref:`StyleBox` that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a :ref:`StyleBoxEmpty` resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. ---- .. _class_OptionButton_theme_style_hover: - :ref:`StyleBox` **hover** :ref:`StyleBox` used when the ``OptionButton`` is being hovered (for left-to-right layouts). ---- .. _class_OptionButton_theme_style_hover_mirrored: - :ref:`StyleBox` **hover_mirrored** :ref:`StyleBox` used when the ``OptionButton`` is being hovered (for right-to-left layouts). ---- .. _class_OptionButton_theme_style_normal: - :ref:`StyleBox` **normal** Default :ref:`StyleBox` for the ``OptionButton`` (for left-to-right layouts). ---- .. _class_OptionButton_theme_style_normal_mirrored: - :ref:`StyleBox` **normal_mirrored** Default :ref:`StyleBox` for the ``OptionButton`` (for right-to-left layouts). ---- .. _class_OptionButton_theme_style_pressed: - :ref:`StyleBox` **pressed** :ref:`StyleBox` used when the ``OptionButton`` is being pressed (for left-to-right layouts). ---- .. _class_OptionButton_theme_style_pressed_mirrored: - :ref:`StyleBox` **pressed_mirrored** :ref:`StyleBox` used when the ``OptionButton`` is being pressed (for right-to-left layouts). .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`