ItemList

Inherits: Control < CanvasItem < Node < Object Control that provides a list of selectable items (and/or icons) in a single column, or optionally in multiple columns.

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. \n) in the string won’t produce a newline. Text wrapping is enabled in ICON_MODE_TOP mode, but column’s width is adjusted to fully fit its content by default. You need to set fixed_column_width greater than zero to wrap the text. Incremental search: Like PopupMenu and 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 ProjectSettings.gui/timers/incremental_search_max_interval_msec.

Properties

Methods

Theme Properties

Signals

  • item_activated ( int index ) Triggered when specified list item is activated via double-clicking or by pressing Enter.
  • item_rmb_selected ( int index, 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. allow_rmb_select must be enabled.
  • item_selected ( int index ) Triggered when specified item has been selected. allow_reselect must be enabled to reselect an item.
  • multi_selected ( int index, bool selected ) Triggered when a multiple selection is altered on a list allowing multiple selection.
  • nothing_selected ( ) Triggered when a left mouse click is issued within the rect of the list but on empty space.
  • rmb_clicked ( Vector2 at_position ) Triggered when a right mouse click is issued within the rect of the list but on empty space. allow_rmb_select must be enabled.

    Enumerations

    IconMode:
  • ICON_MODE_TOP = 0 —- Icon is drawn above the text.
  • ICON_MODE_LEFT = 1 —- Icon is drawn to the left of the text.

SelectMode:

  • SELECT_SINGLE = 0 —- Only allow selecting a single item.
  • SELECT_MULTI = 1 —- Allows selecting multiple items by holding Ctrl or Shift.

    Property Descriptions

  • bool allow_reselect true, the currently selected item can be selected again.
  • bool allow_rmb_select true, right mouse button click can select items.
  • bool auto_height true, the control will automatically resize the height to fit its content.
  • int 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.
  • Vector2 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.
  • IconMode icon_mode IconMode constants.
  • float icon_scale fixed_icon_size and transposing takes effect.
  • int 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.
  • int 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 icon_mode is ICON_MODE_TOP. To make the text wrap, fixed_column_width should be greater than zero.
  • bool same_column_width Whether all columns will have the same width. true, the width is equal to the largest column width of all columns.
  • SelectMode select_mode SelectMode constants.

    Method Descriptions

  • add_icon_item ( Texture icon, bool selectable=true ) Adds an item to the item list with no text, only an icon.
  • add_item ( String text, Texture icon=null, bool selectable=true ) icon, or use null as the icon for a list item with no icon. true, the list item will be selectable.
  • clear ( ) Removes all items from the list.
  • ensure_current_is_visible ( ) Ensure current selection is visible, adjusting the scroll position as necessary.
  • int get_item_at_position ( Vector2 position, bool exact=false ) const position. exact is true, and the closest item index will be returned otherwise.
  • int get_item_count ( ) const Returns the number of items currently in the list.
  • Color get_item_custom_bg_color ( int idx ) const idx index.
  • Color get_item_custom_fg_color ( int idx ) const idx index.
  • Texture get_item_icon ( int idx ) const Returns the icon associated with the specified index.
  • Color get_item_icon_modulate ( int idx ) const Color modulating item’s icon at the specified index.
  • Rect2 get_item_icon_region ( int idx ) const Returns the region of item’s icon used. The whole icon will be used if the region has no area.
  • Variant get_item_metadata ( int idx ) const Returns the metadata value of the specified index.
  • String get_item_text ( int idx ) const Returns the text associated with the specified index.
  • String get_item_tooltip ( int idx ) const Returns the tooltip hint associated with the specified index.
  • PoolIntArray get_selected_items ( ) Returns an array with the indexes of the selected items.
  • 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 CanvasItem.visible property.
  • bool is_anything_selected ( ) true if one or more items are selected.
  • bool is_item_disabled ( int idx ) const true if the item at the specified index is disabled.
  • bool is_item_icon_transposed ( int idx ) const true if the item icon will be drawn transposed, i.e. the X and Y axes are swapped.
  • bool is_item_selectable ( int idx ) const true if the item at the specified index is selectable.
  • bool is_item_tooltip_enabled ( int idx ) const true if the tooltip is enabled for specified item index.
  • bool is_selected ( int idx ) const true if the item at the specified index is currently selected.
  • move_item ( int from_idx, int to_idx ) from_idx to to_idx.
  • remove_item ( int idx ) idx index from the list.
  • select ( int idx, bool single=true ) Select the item at the specified index. Note: This method does not trigger the item selection signal.
  • set_item_custom_bg_color ( int idx, Color custom_bg_color ) idx index to the specified Color.
  • set_item_custom_fg_color ( int idx, Color custom_fg_color ) idx index to the specified Color.
  • set_item_disabled ( int idx, 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).
  • set_item_icon ( int idx, Texture icon ) Texture associated with the specified index.
  • set_item_icon_modulate ( int idx, Color modulate ) Color of the item associated with the specified index.
  • set_item_icon_region ( int idx, Rect2 rect ) Sets the region of item’s icon used. The whole icon will be used if the region has no area.
  • set_item_icon_transposed ( int idx, bool transposed ) Sets whether the item icon will be drawn transposed.
  • set_item_metadata ( int idx, Variant metadata ) Sets a value (of any type) to be stored with the item associated with the specified index.
  • set_item_selectable ( int idx, bool selectable ) Allows or disallows selection of the item associated with the specified index.
  • set_item_text ( int idx, String text ) Sets text of the item associated with the specified index.
  • set_item_tooltip ( int idx, String tooltip ) Sets the tooltip hint for the item associated with the specified index.
  • set_item_tooltip_enabled ( int idx, bool enable ) Sets whether the tooltip hint is enabled for specified item index.
  • sort_items_by_text ( ) Sorts items in the list by their text.
  • unselect ( int idx ) Ensures the item associated with the specified index is not selected.
  • unselect_all ( ) Ensures there are no items selected.

    Theme Property Descriptions

  • Color font_color Color of the item.
  • Color font_color_selected Color used when the item is selected.
  • Color guide_color Color of the guideline. The guideline is a line drawn between each row of items.
  • int hseparation The horizontal spacing between items.
  • int icon_margin The spacing between item’s icon and text.
  • int line_separation The vertical spacing between each line of text.
  • int vseparation The vertical spacing between items.
  • Font font Font of the item’s text.
  • StyleBox bg StyleBox for the ItemList, i.e. used when the control is not being focused.
  • StyleBox bg_focus StyleBox used when the ItemList is being focused.
  • StyleBox cursor StyleBox used for the cursor, when the ItemList is being focused.
  • StyleBox cursor_unfocused StyleBox used for the cursor, when the ItemList is not being focused.
  • StyleBox selected StyleBox for the selected items, used when the ItemList is not being focused.
  • StyleBox selected_focus StyleBox for the selected items, used when the ItemList is being focused.