godot-docs/classes/class_itemlist.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/3.5/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/3.5/doc/classes/ItemList.xml.

.. _class_ItemList:

ItemList
========

**Inherits:** :ref:`Control<class_Control>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

Control that provides a list of selectable items (and/or icons) in a single column, or optionally in multiple columns.

.. rst-class:: classref-introduction-group

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

This control provides a selectable list of items that may be in a single (or multiple columns) with option of text, icons, or both text and icon. Tooltips are supported and may be different for every item in the list.

Selectable items in the list may be selected or deselected and multiple selection may be enabled. Selection with right mouse button may also be enabled to allow use of popup context menus. Items may also be "activated" by double-clicking them or by pressing Enter.

Item text only supports single-line strings, newline characters (e.g. ``\n``) in the string won't produce a newline. Text wrapping is enabled in :ref:`ICON_MODE_TOP<class_ItemList_constant_ICON_MODE_TOP>` mode, but column's width is adjusted to fully fit its content by default. You need to set :ref:`fixed_column_width<class_ItemList_property_fixed_column_width>` greater than zero to wrap the text.

\ **Incremental search:** Like :ref:`PopupMenu<class_PopupMenu>` and :ref:`Tree<class_Tree>`, **ItemList** supports searching within the list while the control is focused. Press a key that matches the first letter of an item's name to select the first item starting with the given letter. After that point, there are two ways to perform incremental search: 1) Press the same key again before the timeout duration to select the next item starting with the same letter. 2) Press letter keys that match the rest of the word before the timeout duration to match to select the item in question directly. Both of these actions will be reset to the beginning of the list if the timeout duration has passed since the last keystroke was registered. You can adjust the timeout duration by changing :ref:`ProjectSettings.gui/timers/incremental_search_max_interval_msec<class_ProjectSettings_property_gui/timers/incremental_search_max_interval_msec>`.

.. rst-class:: classref-reftable-group

Properties
----------

.. table::
   :widths: auto

   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                     | :ref:`allow_reselect<class_ItemList_property_allow_reselect>`         | ``false``                                                                     |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                     | :ref:`allow_rmb_select<class_ItemList_property_allow_rmb_select>`     | ``false``                                                                     |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                     | :ref:`auto_height<class_ItemList_property_auto_height>`               | ``false``                                                                     |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                       | :ref:`fixed_column_width<class_ItemList_property_fixed_column_width>` | ``0``                                                                         |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`Vector2<class_Vector2>`               | :ref:`fixed_icon_size<class_ItemList_property_fixed_icon_size>`       | ``Vector2( 0, 0 )``                                                           |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`FocusMode<enum_Control_FocusMode>`    | focus_mode                                                            | ``2`` (overrides :ref:`Control<class_Control_property_focus_mode>`)           |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`IconMode<enum_ItemList_IconMode>`     | :ref:`icon_mode<class_ItemList_property_icon_mode>`                   | ``1``                                                                         |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`float<class_float>`                   | :ref:`icon_scale<class_ItemList_property_icon_scale>`                 | ``1.0``                                                                       |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                       | :ref:`max_columns<class_ItemList_property_max_columns>`               | ``1``                                                                         |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                       | :ref:`max_text_lines<class_ItemList_property_max_text_lines>`         | ``1``                                                                         |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                     | rect_clip_content                                                     | ``true`` (overrides :ref:`Control<class_Control_property_rect_clip_content>`) |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                     | :ref:`same_column_width<class_ItemList_property_same_column_width>`   | ``false``                                                                     |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+
   | :ref:`SelectMode<enum_ItemList_SelectMode>` | :ref:`select_mode<class_ItemList_property_select_mode>`               | ``0``                                                                         |
   +---------------------------------------------+-----------------------------------------------------------------------+-------------------------------------------------------------------------------+

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`add_icon_item<class_ItemList_method_add_icon_item>` **(** :ref:`Texture<class_Texture>` icon, :ref:`bool<class_bool>` selectable=true **)**                              |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`add_item<class_ItemList_method_add_item>` **(** :ref:`String<class_String>` text, :ref:`Texture<class_Texture>` icon=null, :ref:`bool<class_bool>` selectable=true **)** |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`clear<class_ItemList_method_clear>` **(** **)**                                                                                                                          |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`ensure_current_is_visible<class_ItemList_method_ensure_current_is_visible>` **(** **)**                                                                                  |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                   | :ref:`get_item_at_position<class_ItemList_method_get_item_at_position>` **(** :ref:`Vector2<class_Vector2>` position, :ref:`bool<class_bool>` exact=false **)** |const|        |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`int<class_int>`                   | :ref:`get_item_count<class_ItemList_method_get_item_count>` **(** **)** |const|                                                                                                |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Color<class_Color>`               | :ref:`get_item_custom_bg_color<class_ItemList_method_get_item_custom_bg_color>` **(** :ref:`int<class_int>` idx **)** |const|                                                  |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Color<class_Color>`               | :ref:`get_item_custom_fg_color<class_ItemList_method_get_item_custom_fg_color>` **(** :ref:`int<class_int>` idx **)** |const|                                                  |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Texture<class_Texture>`           | :ref:`get_item_icon<class_ItemList_method_get_item_icon>` **(** :ref:`int<class_int>` idx **)** |const|                                                                        |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Color<class_Color>`               | :ref:`get_item_icon_modulate<class_ItemList_method_get_item_icon_modulate>` **(** :ref:`int<class_int>` idx **)** |const|                                                      |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Rect2<class_Rect2>`               | :ref:`get_item_icon_region<class_ItemList_method_get_item_icon_region>` **(** :ref:`int<class_int>` idx **)** |const|                                                          |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`Variant<class_Variant>`           | :ref:`get_item_metadata<class_ItemList_method_get_item_metadata>` **(** :ref:`int<class_int>` idx **)** |const|                                                                |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`String<class_String>`             | :ref:`get_item_text<class_ItemList_method_get_item_text>` **(** :ref:`int<class_int>` idx **)** |const|                                                                        |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`String<class_String>`             | :ref:`get_item_tooltip<class_ItemList_method_get_item_tooltip>` **(** :ref:`int<class_int>` idx **)** |const|                                                                  |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`PoolIntArray<class_PoolIntArray>` | :ref:`get_selected_items<class_ItemList_method_get_selected_items>` **(** **)**                                                                                                |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`VScrollBar<class_VScrollBar>`     | :ref:`get_v_scroll<class_ItemList_method_get_v_scroll>` **(** **)**                                                                                                            |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                 | :ref:`is_anything_selected<class_ItemList_method_is_anything_selected>` **(** **)**                                                                                            |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                 | :ref:`is_item_disabled<class_ItemList_method_is_item_disabled>` **(** :ref:`int<class_int>` idx **)** |const|                                                                  |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                 | :ref:`is_item_icon_transposed<class_ItemList_method_is_item_icon_transposed>` **(** :ref:`int<class_int>` idx **)** |const|                                                    |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                 | :ref:`is_item_selectable<class_ItemList_method_is_item_selectable>` **(** :ref:`int<class_int>` idx **)** |const|                                                              |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                 | :ref:`is_item_tooltip_enabled<class_ItemList_method_is_item_tooltip_enabled>` **(** :ref:`int<class_int>` idx **)** |const|                                                    |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                 | :ref:`is_selected<class_ItemList_method_is_selected>` **(** :ref:`int<class_int>` idx **)** |const|                                                                            |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`move_item<class_ItemList_method_move_item>` **(** :ref:`int<class_int>` from_idx, :ref:`int<class_int>` to_idx **)**                                                     |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`remove_item<class_ItemList_method_remove_item>` **(** :ref:`int<class_int>` idx **)**                                                                                    |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`select<class_ItemList_method_select>` **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` single=true **)**                                                         |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_custom_bg_color<class_ItemList_method_set_item_custom_bg_color>` **(** :ref:`int<class_int>` idx, :ref:`Color<class_Color>` custom_bg_color **)**               |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_custom_fg_color<class_ItemList_method_set_item_custom_fg_color>` **(** :ref:`int<class_int>` idx, :ref:`Color<class_Color>` custom_fg_color **)**               |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_disabled<class_ItemList_method_set_item_disabled>` **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` disabled **)**                                      |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_icon<class_ItemList_method_set_item_icon>` **(** :ref:`int<class_int>` idx, :ref:`Texture<class_Texture>` icon **)**                                            |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_icon_modulate<class_ItemList_method_set_item_icon_modulate>` **(** :ref:`int<class_int>` idx, :ref:`Color<class_Color>` modulate **)**                          |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_icon_region<class_ItemList_method_set_item_icon_region>` **(** :ref:`int<class_int>` idx, :ref:`Rect2<class_Rect2>` rect **)**                                  |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_icon_transposed<class_ItemList_method_set_item_icon_transposed>` **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` transposed **)**                      |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_metadata<class_ItemList_method_set_item_metadata>` **(** :ref:`int<class_int>` idx, :ref:`Variant<class_Variant>` metadata **)**                                |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_selectable<class_ItemList_method_set_item_selectable>` **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` selectable **)**                                |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_text<class_ItemList_method_set_item_text>` **(** :ref:`int<class_int>` idx, :ref:`String<class_String>` text **)**                                              |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_tooltip<class_ItemList_method_set_item_tooltip>` **(** :ref:`int<class_int>` idx, :ref:`String<class_String>` tooltip **)**                                     |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`set_item_tooltip_enabled<class_ItemList_method_set_item_tooltip_enabled>` **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` enable **)**                          |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`sort_items_by_text<class_ItemList_method_sort_items_by_text>` **(** **)**                                                                                                |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`unselect<class_ItemList_method_unselect>` **(** :ref:`int<class_int>` idx **)**                                                                                          |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | void                                    | :ref:`unselect_all<class_ItemList_method_unselect_all>` **(** **)**                                                                                                            |
   +-----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-reftable-group

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

.. table::
   :widths: auto

   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`Color<class_Color>`       | :ref:`font_color<class_ItemList_theme_color_font_color>`                   | ``Color( 0.63, 0.63, 0.63, 1 )`` |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`Color<class_Color>`       | :ref:`font_color_selected<class_ItemList_theme_color_font_color_selected>` | ``Color( 1, 1, 1, 1 )``          |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`Color<class_Color>`       | :ref:`guide_color<class_ItemList_theme_color_guide_color>`                 | ``Color( 0, 0, 0, 0.1 )``        |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`int<class_int>`           | :ref:`hseparation<class_ItemList_theme_constant_hseparation>`              | ``4``                            |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`int<class_int>`           | :ref:`icon_margin<class_ItemList_theme_constant_icon_margin>`              | ``4``                            |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`int<class_int>`           | :ref:`line_separation<class_ItemList_theme_constant_line_separation>`      | ``2``                            |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`int<class_int>`           | :ref:`vseparation<class_ItemList_theme_constant_vseparation>`              | ``2``                            |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`Font<class_Font>`         | :ref:`font<class_ItemList_theme_font_font>`                                |                                  |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`StyleBox<class_StyleBox>` | :ref:`bg<class_ItemList_theme_style_bg>`                                   |                                  |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`StyleBox<class_StyleBox>` | :ref:`bg_focus<class_ItemList_theme_style_bg_focus>`                       |                                  |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`StyleBox<class_StyleBox>` | :ref:`cursor<class_ItemList_theme_style_cursor>`                           |                                  |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`StyleBox<class_StyleBox>` | :ref:`cursor_unfocused<class_ItemList_theme_style_cursor_unfocused>`       |                                  |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`StyleBox<class_StyleBox>` | :ref:`selected<class_ItemList_theme_style_selected>`                       |                                  |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+
   | :ref:`StyleBox<class_StyleBox>` | :ref:`selected_focus<class_ItemList_theme_style_selected_focus>`           |                                  |
   +---------------------------------+----------------------------------------------------------------------------+----------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Signals
-------

.. _class_ItemList_signal_item_activated:

.. rst-class:: classref-signal

**item_activated** **(** :ref:`int<class_int>` index **)**

Triggered when specified list item is activated via double-clicking or by pressing Enter.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_signal_item_rmb_selected:

.. rst-class:: classref-signal

**item_rmb_selected** **(** :ref:`int<class_int>` index, :ref:`Vector2<class_Vector2>` at_position **)**

Triggered when specified list item has been selected via right mouse clicking.

The click position is also provided to allow appropriate popup of context menus at the correct location.

\ :ref:`allow_rmb_select<class_ItemList_property_allow_rmb_select>` must be enabled.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_signal_item_selected:

.. rst-class:: classref-signal

**item_selected** **(** :ref:`int<class_int>` index **)**

Triggered when specified item has been selected.

\ :ref:`allow_reselect<class_ItemList_property_allow_reselect>` must be enabled to reselect an item.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_signal_multi_selected:

.. rst-class:: classref-signal

**multi_selected** **(** :ref:`int<class_int>` index, :ref:`bool<class_bool>` selected **)**

Triggered when a multiple selection is altered on a list allowing multiple selection.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_signal_nothing_selected:

.. rst-class:: classref-signal

**nothing_selected** **(** **)**

Triggered when a left mouse click is issued within the rect of the list but on empty space.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_signal_rmb_clicked:

.. rst-class:: classref-signal

**rmb_clicked** **(** :ref:`Vector2<class_Vector2>` at_position **)**

Triggered when a right mouse click is issued within the rect of the list but on empty space.

\ :ref:`allow_rmb_select<class_ItemList_property_allow_rmb_select>` must be enabled.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Enumerations
------------

.. _enum_ItemList_IconMode:

.. rst-class:: classref-enumeration

enum **IconMode**:

.. _class_ItemList_constant_ICON_MODE_TOP:

.. rst-class:: classref-enumeration-constant

:ref:`IconMode<enum_ItemList_IconMode>` **ICON_MODE_TOP** = ``0``

Icon is drawn above the text.

.. _class_ItemList_constant_ICON_MODE_LEFT:

.. rst-class:: classref-enumeration-constant

:ref:`IconMode<enum_ItemList_IconMode>` **ICON_MODE_LEFT** = ``1``

Icon is drawn to the left of the text.

.. rst-class:: classref-item-separator

----

.. _enum_ItemList_SelectMode:

.. rst-class:: classref-enumeration

enum **SelectMode**:

.. _class_ItemList_constant_SELECT_SINGLE:

.. rst-class:: classref-enumeration-constant

:ref:`SelectMode<enum_ItemList_SelectMode>` **SELECT_SINGLE** = ``0``

Only allow selecting a single item.

.. _class_ItemList_constant_SELECT_MULTI:

.. rst-class:: classref-enumeration-constant

:ref:`SelectMode<enum_ItemList_SelectMode>` **SELECT_MULTI** = ``1``

Allows selecting multiple items by holding Ctrl or Shift.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

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

.. _class_ItemList_property_allow_reselect:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **allow_reselect** = ``false``

.. rst-class:: classref-property-setget

- void **set_allow_reselect** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_allow_reselect** **(** **)**

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

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_allow_rmb_select:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **allow_rmb_select** = ``false``

.. rst-class:: classref-property-setget

- void **set_allow_rmb_select** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_allow_rmb_select** **(** **)**

If ``true``, right mouse button click can select items.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_auto_height:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **auto_height** = ``false``

.. rst-class:: classref-property-setget

- void **set_auto_height** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **has_auto_height** **(** **)**

If ``true``, the control will automatically resize the height to fit its content.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_fixed_column_width:

.. rst-class:: classref-property

:ref:`int<class_int>` **fixed_column_width** = ``0``

.. rst-class:: classref-property-setget

- void **set_fixed_column_width** **(** :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_fixed_column_width** **(** **)**

The width all columns will be adjusted to.

A value of zero disables the adjustment, each item will have a width equal to the width of its content and the columns will have an uneven width.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_fixed_icon_size:

.. rst-class:: classref-property

:ref:`Vector2<class_Vector2>` **fixed_icon_size** = ``Vector2( 0, 0 )``

.. rst-class:: classref-property-setget

- void **set_fixed_icon_size** **(** :ref:`Vector2<class_Vector2>` value **)**
- :ref:`Vector2<class_Vector2>` **get_fixed_icon_size** **(** **)**

The size all icons will be adjusted to.

If either X or Y component is not greater than zero, icon size won't be affected.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_icon_mode:

.. rst-class:: classref-property

:ref:`IconMode<enum_ItemList_IconMode>` **icon_mode** = ``1``

.. rst-class:: classref-property-setget

- void **set_icon_mode** **(** :ref:`IconMode<enum_ItemList_IconMode>` value **)**
- :ref:`IconMode<enum_ItemList_IconMode>` **get_icon_mode** **(** **)**

The icon position, whether above or to the left of the text. See the :ref:`IconMode<enum_ItemList_IconMode>` constants.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_icon_scale:

.. rst-class:: classref-property

:ref:`float<class_float>` **icon_scale** = ``1.0``

.. rst-class:: classref-property-setget

- void **set_icon_scale** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_icon_scale** **(** **)**

The scale of icon applied after :ref:`fixed_icon_size<class_ItemList_property_fixed_icon_size>` and transposing takes effect.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_max_columns:

.. rst-class:: classref-property

:ref:`int<class_int>` **max_columns** = ``1``

.. rst-class:: classref-property-setget

- void **set_max_columns** **(** :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_max_columns** **(** **)**

Maximum columns the list will have.

If greater than zero, the content will be split among the specified columns.

A value of zero means unlimited columns, i.e. all items will be put in the same row.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_max_text_lines:

.. rst-class:: classref-property

:ref:`int<class_int>` **max_text_lines** = ``1``

.. rst-class:: classref-property-setget

- void **set_max_text_lines** **(** :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_max_text_lines** **(** **)**

Maximum lines of text allowed in each item. Space will be reserved even when there is not enough lines of text to display.

\ **Note:** This property takes effect only when :ref:`icon_mode<class_ItemList_property_icon_mode>` is :ref:`ICON_MODE_TOP<class_ItemList_constant_ICON_MODE_TOP>`. To make the text wrap, :ref:`fixed_column_width<class_ItemList_property_fixed_column_width>` should be greater than zero.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_same_column_width:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **same_column_width** = ``false``

.. rst-class:: classref-property-setget

- void **set_same_column_width** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **is_same_column_width** **(** **)**

Whether all columns will have the same width.

If ``true``, the width is equal to the largest column width of all columns.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_property_select_mode:

.. rst-class:: classref-property

:ref:`SelectMode<enum_ItemList_SelectMode>` **select_mode** = ``0``

.. rst-class:: classref-property-setget

- void **set_select_mode** **(** :ref:`SelectMode<enum_ItemList_SelectMode>` value **)**
- :ref:`SelectMode<enum_ItemList_SelectMode>` **get_select_mode** **(** **)**

Allows single or multiple item selection. See the :ref:`SelectMode<enum_ItemList_SelectMode>` constants.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

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

.. _class_ItemList_method_add_icon_item:

.. rst-class:: classref-method

void **add_icon_item** **(** :ref:`Texture<class_Texture>` icon, :ref:`bool<class_bool>` selectable=true **)**

Adds an item to the item list with no text, only an icon.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_add_item:

.. rst-class:: classref-method

void **add_item** **(** :ref:`String<class_String>` text, :ref:`Texture<class_Texture>` icon=null, :ref:`bool<class_bool>` selectable=true **)**

Adds an item to the item list with specified text. Specify an ``icon``, or use ``null`` as the ``icon`` for a list item with no icon.

If selectable is ``true``, the list item will be selectable.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_clear:

.. rst-class:: classref-method

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

Removes all items from the list.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_ensure_current_is_visible:

.. rst-class:: classref-method

void **ensure_current_is_visible** **(** **)**

Ensure current selection is visible, adjusting the scroll position as necessary.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_at_position:

.. rst-class:: classref-method

:ref:`int<class_int>` **get_item_at_position** **(** :ref:`Vector2<class_Vector2>` position, :ref:`bool<class_bool>` exact=false **)** |const|

Returns the item index at the given ``position``.

When there is no item at that point, -1 will be returned if ``exact`` is ``true``, and the closest item index will be returned otherwise.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_count:

.. rst-class:: classref-method

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

Returns the number of items currently in the list.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_custom_bg_color:

.. rst-class:: classref-method

:ref:`Color<class_Color>` **get_item_custom_bg_color** **(** :ref:`int<class_int>` idx **)** |const|

Returns the custom background color of the item specified by ``idx`` index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_custom_fg_color:

.. rst-class:: classref-method

:ref:`Color<class_Color>` **get_item_custom_fg_color** **(** :ref:`int<class_int>` idx **)** |const|

Returns the custom foreground color of the item specified by ``idx`` index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_icon:

.. rst-class:: classref-method

:ref:`Texture<class_Texture>` **get_item_icon** **(** :ref:`int<class_int>` idx **)** |const|

Returns the icon associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_icon_modulate:

.. rst-class:: classref-method

:ref:`Color<class_Color>` **get_item_icon_modulate** **(** :ref:`int<class_int>` idx **)** |const|

Returns a :ref:`Color<class_Color>` modulating item's icon at the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_icon_region:

.. rst-class:: classref-method

:ref:`Rect2<class_Rect2>` **get_item_icon_region** **(** :ref:`int<class_int>` idx **)** |const|

Returns the region of item's icon used. The whole icon will be used if the region has no area.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_metadata:

.. rst-class:: classref-method

:ref:`Variant<class_Variant>` **get_item_metadata** **(** :ref:`int<class_int>` idx **)** |const|

Returns the metadata value of the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_text:

.. rst-class:: classref-method

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

Returns the text associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_item_tooltip:

.. rst-class:: classref-method

:ref:`String<class_String>` **get_item_tooltip** **(** :ref:`int<class_int>` idx **)** |const|

Returns the tooltip hint associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_selected_items:

.. rst-class:: classref-method

:ref:`PoolIntArray<class_PoolIntArray>` **get_selected_items** **(** **)**

Returns an array with the indexes of the selected items.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_get_v_scroll:

.. rst-class:: classref-method

:ref:`VScrollBar<class_VScrollBar>` **get_v_scroll** **(** **)**

Returns the vertical scrollbar.

\ **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:`CanvasItem.visible<class_CanvasItem_property_visible>` property.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_is_anything_selected:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **is_anything_selected** **(** **)**

Returns ``true`` if one or more items are selected.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_is_item_disabled:

.. rst-class:: classref-method

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

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

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_is_item_icon_transposed:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **is_item_icon_transposed** **(** :ref:`int<class_int>` idx **)** |const|

Returns ``true`` if the item icon will be drawn transposed, i.e. the X and Y axes are swapped.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_is_item_selectable:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **is_item_selectable** **(** :ref:`int<class_int>` idx **)** |const|

Returns ``true`` if the item at the specified index is selectable.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_is_item_tooltip_enabled:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **is_item_tooltip_enabled** **(** :ref:`int<class_int>` idx **)** |const|

Returns ``true`` if the tooltip is enabled for specified item index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_is_selected:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **is_selected** **(** :ref:`int<class_int>` idx **)** |const|

Returns ``true`` if the item at the specified index is currently selected.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_move_item:

.. rst-class:: classref-method

void **move_item** **(** :ref:`int<class_int>` from_idx, :ref:`int<class_int>` to_idx **)**

Moves item from index ``from_idx`` to ``to_idx``.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_remove_item:

.. rst-class:: classref-method

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

Removes the item specified by ``idx`` index from the list.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_select:

.. rst-class:: classref-method

void **select** **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` single=true **)**

Select the item at the specified index.

\ **Note:** This method does not trigger the item selection signal.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_custom_bg_color:

.. rst-class:: classref-method

void **set_item_custom_bg_color** **(** :ref:`int<class_int>` idx, :ref:`Color<class_Color>` custom_bg_color **)**

Sets the background color of the item specified by ``idx`` index to the specified :ref:`Color<class_Color>`.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_custom_fg_color:

.. rst-class:: classref-method

void **set_item_custom_fg_color** **(** :ref:`int<class_int>` idx, :ref:`Color<class_Color>` custom_fg_color **)**

Sets the foreground color of the item specified by ``idx`` index to the specified :ref:`Color<class_Color>`.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_disabled:

.. rst-class:: classref-method

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

Disables (or enables) the item at the specified index.

Disabled items cannot be selected and do not trigger activation signals (when double-clicking or pressing Enter).

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_icon:

.. rst-class:: classref-method

void **set_item_icon** **(** :ref:`int<class_int>` idx, :ref:`Texture<class_Texture>` icon **)**

Sets (or replaces) the icon's :ref:`Texture<class_Texture>` associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_icon_modulate:

.. rst-class:: classref-method

void **set_item_icon_modulate** **(** :ref:`int<class_int>` idx, :ref:`Color<class_Color>` modulate **)**

Sets a modulating :ref:`Color<class_Color>` of the item associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_icon_region:

.. rst-class:: classref-method

void **set_item_icon_region** **(** :ref:`int<class_int>` idx, :ref:`Rect2<class_Rect2>` rect **)**

Sets the region of item's icon used. The whole icon will be used if the region has no area.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_icon_transposed:

.. rst-class:: classref-method

void **set_item_icon_transposed** **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` transposed **)**

Sets whether the item icon will be drawn transposed.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_metadata:

.. rst-class:: classref-method

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

Sets a value (of any type) to be stored with the item associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_selectable:

.. rst-class:: classref-method

void **set_item_selectable** **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` selectable **)**

Allows or disallows selection of the item associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_text:

.. rst-class:: classref-method

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

Sets text of the item associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_tooltip:

.. rst-class:: classref-method

void **set_item_tooltip** **(** :ref:`int<class_int>` idx, :ref:`String<class_String>` tooltip **)**

Sets the tooltip hint for the item associated with the specified index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_set_item_tooltip_enabled:

.. rst-class:: classref-method

void **set_item_tooltip_enabled** **(** :ref:`int<class_int>` idx, :ref:`bool<class_bool>` enable **)**

Sets whether the tooltip hint is enabled for specified item index.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_sort_items_by_text:

.. rst-class:: classref-method

void **sort_items_by_text** **(** **)**

Sorts items in the list by their text.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_unselect:

.. rst-class:: classref-method

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

Ensures the item associated with the specified index is not selected.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_method_unselect_all:

.. rst-class:: classref-method

void **unselect_all** **(** **)**

Ensures there are no items selected.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Theme Property Descriptions
---------------------------

.. _class_ItemList_theme_color_font_color:

.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` **font_color** = ``Color( 0.63, 0.63, 0.63, 1 )``

Default text :ref:`Color<class_Color>` of the item.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_color_font_color_selected:

.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` **font_color_selected** = ``Color( 1, 1, 1, 1 )``

Text :ref:`Color<class_Color>` used when the item is selected.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_color_guide_color:

.. rst-class:: classref-themeproperty

:ref:`Color<class_Color>` **guide_color** = ``Color( 0, 0, 0, 0.1 )``

:ref:`Color<class_Color>` of the guideline. The guideline is a line drawn between each row of items.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_constant_hseparation:

.. rst-class:: classref-themeproperty

:ref:`int<class_int>` **hseparation** = ``4``

The horizontal spacing between items.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_constant_icon_margin:

.. rst-class:: classref-themeproperty

:ref:`int<class_int>` **icon_margin** = ``4``

The spacing between item's icon and text.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_constant_line_separation:

.. rst-class:: classref-themeproperty

:ref:`int<class_int>` **line_separation** = ``2``

The vertical spacing between each line of text.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_constant_vseparation:

.. rst-class:: classref-themeproperty

:ref:`int<class_int>` **vseparation** = ``2``

The vertical spacing between items.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_font_font:

.. rst-class:: classref-themeproperty

:ref:`Font<class_Font>` **font**

:ref:`Font<class_Font>` of the item's text.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_style_bg:

.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` **bg**

Default :ref:`StyleBox<class_StyleBox>` for the **ItemList**, i.e. used when the control is not being focused.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_style_bg_focus:

.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` **bg_focus**

:ref:`StyleBox<class_StyleBox>` used when the **ItemList** is being focused.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_style_cursor:

.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` **cursor**

:ref:`StyleBox<class_StyleBox>` used for the cursor, when the **ItemList** is being focused.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_style_cursor_unfocused:

.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` **cursor_unfocused**

:ref:`StyleBox<class_StyleBox>` used for the cursor, when the **ItemList** is not being focused.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_style_selected:

.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` **selected**

:ref:`StyleBox<class_StyleBox>` for the selected items, used when the **ItemList** is not being focused.

.. rst-class:: classref-item-separator

----

.. _class_ItemList_theme_style_selected_focus:

.. rst-class:: classref-themeproperty

:ref:`StyleBox<class_StyleBox>` **selected_focus**

:ref:`StyleBox<class_StyleBox>` for the selected items, used when the **ItemList** is being focused.

.. |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.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`