Table of Contents

Class ItemList

Namespace
Godot
Assembly
GodotSharp.dll

This control provides a vertical list of selectable items that may be in a single or in multiple columns, with each item having options for text and an 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 Top mode, but the column's width is adjusted to fully fit its content by default. You need to set FixedColumnWidth greater than zero to wrap the text.

All set_* methods allow negative item indices, i.e. -1 to access the last item, -2 to select the second-to-last item, and so on.

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.

public class ItemList : Control, IDisposable
Inheritance
ItemList
Implements
Inherited Members

Constructors

ItemList() 

public ItemList()

Properties

AllowReselect

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

public bool AllowReselect { get; set; }

Property Value

bool

AllowRmbSelect

If true, right mouse button click can select items.

public bool AllowRmbSelect { get; set; }

Property Value

bool

AllowSearch

If true, allows navigating the ItemList with letter keys through incremental search.

public bool AllowSearch { get; set; }

Property Value

bool

AutoHeight

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

public bool AutoHeight { get; set; }

Property Value

bool

FixedColumnWidth

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.

public int FixedColumnWidth { get; set; }

Property Value

int

FixedIconSize

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.

public Vector2I FixedIconSize { get; set; }

Property Value

Vector2I

IconMode

The icon position, whether above or to the left of the text. See the ItemList.IconModeEnum constants.

public ItemList.IconModeEnum IconMode { get; set; }

Property Value

ItemList.IconModeEnum

IconScale

The scale of icon applied after FixedIconSize and transposing takes effect.

public float IconScale { get; set; }

Property Value

float

ItemCount

The number of items currently in the list.

public int ItemCount { get; set; }

Property Value

int

MaxColumns

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.

public int MaxColumns { get; set; }

Property Value

int

MaxTextLines

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 IconMode is Top. To make the text wrap, FixedColumnWidth should be greater than zero.

public int MaxTextLines { get; set; }

Property Value

int

SameColumnWidth

Whether all columns will have the same width.

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

public bool SameColumnWidth { get; set; }

Property Value

bool

SelectMode

Allows single or multiple item selection. See the ItemList.SelectModeEnum constants.

public ItemList.SelectModeEnum SelectMode { get; set; }

Property Value

ItemList.SelectModeEnum

TextOverrunBehavior

Sets the clipping behavior when the text exceeds an item's bounding rectangle. See TextServer.OverrunBehavior for a description of all modes.

public TextServer.OverrunBehavior TextOverrunBehavior { get; set; }

Property Value

TextServer.OverrunBehavior

Methods

AddIconItem(Texture2D, bool)

Adds an item to the item list with no text, only an icon. Returns the index of an added item.

public int AddIconItem(Texture2D icon, bool selectable = true)

Parameters

icon Texture2D
selectable bool

Returns

int

AddItem(string, Texture2D, bool)

Adds an item to the item list with specified text. Returns the index of an added item.

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.

public int AddItem(string text, Texture2D icon = null, bool selectable = true)

Parameters

text string
icon Texture2D
selectable bool

Returns

int

Clear()

Removes all items from the list.

public void Clear()

Deselect(int)

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

public void Deselect(int idx)

Parameters

idx int

DeselectAll()

Ensures there are no items selected.

public void DeselectAll()

EnsureCurrentIsVisible()

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

public void EnsureCurrentIsVisible()

ForceUpdateListSize()

Forces an update to the list size based on its items. This happens automatically whenever size of the items, or other relevant settings like AutoHeight, change. The method can be used to trigger the update ahead of next drawing pass.

public void ForceUpdateListSize()

GetItemAtPosition(Vector2, bool)

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.

Note: The returned value is unreliable if called right after modifying the ItemList, before it redraws in the next frame.

public int GetItemAtPosition(Vector2 position, bool exact = false)

Parameters

position Vector2
exact bool

Returns

int

GetItemCustomBgColor(int)

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

public Color GetItemCustomBgColor(int idx)

Parameters

idx int

Returns

Color

GetItemCustomFgColor(int)

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

public Color GetItemCustomFgColor(int idx)

Parameters

idx int

Returns

Color

GetItemIcon(int)

Returns the icon associated with the specified index.

public Texture2D GetItemIcon(int idx)

Parameters

idx int

Returns

Texture2D

GetItemIconModulate(int)

Returns a Color modulating item's icon at the specified index.

public Color GetItemIconModulate(int idx)

Parameters

idx int

Returns

Color

GetItemIconRegion(int)

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

public Rect2 GetItemIconRegion(int idx)

Parameters

idx int

Returns

Rect2

GetItemLanguage(int)

Returns item's text language code.

public string GetItemLanguage(int idx)

Parameters

idx int

Returns

string

GetItemMetadata(int)

Returns the metadata value of the specified index.

public Variant GetItemMetadata(int idx)

Parameters

idx int

Returns

Variant

GetItemRect(int, bool)

Returns the position and size of the item with the specified index, in the coordinate system of the ItemList node. If expand is true the last column expands to fill the rest of the row.

Note: The returned value is unreliable if called right after modifying the ItemList, before it redraws in the next frame.

public Rect2 GetItemRect(int idx, bool expand = true)

Parameters

idx int
expand bool

Returns

Rect2

GetItemText(int)

Returns the text associated with the specified index.

public string GetItemText(int idx)

Parameters

idx int

Returns

string

GetItemTextDirection(int)

Returns item's text base writing direction.

public Control.TextDirection GetItemTextDirection(int idx)

Parameters

idx int

Returns

Control.TextDirection

GetItemTooltip(int)

Returns the tooltip hint associated with the specified index.

public string GetItemTooltip(int idx)

Parameters

idx int

Returns

string

GetSelectedItems()

Returns an array with the indexes of the selected items.

public int[] GetSelectedItems()

Returns

int[]

GetVScrollBar()

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 Visible property.

public VScrollBar GetVScrollBar()

Returns

VScrollBar

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

IsAnythingSelected()

Returns true if one or more items are selected.

public bool IsAnythingSelected()

Returns

bool

IsItemDisabled(int)

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

public bool IsItemDisabled(int idx)

Parameters

idx int

Returns

bool

IsItemIconTransposed(int)

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

public bool IsItemIconTransposed(int idx)

Parameters

idx int

Returns

bool

IsItemSelectable(int)

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

public bool IsItemSelectable(int idx)

Parameters

idx int

Returns

bool

IsItemTooltipEnabled(int)

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

public bool IsItemTooltipEnabled(int idx)

Parameters

idx int

Returns

bool

IsSelected(int)

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

public bool IsSelected(int idx)

Parameters

idx int

Returns

bool

MoveItem(int, int)

Moves item from index fromIdx to toIdx.

public void MoveItem(int fromIdx, int toIdx)

Parameters

fromIdx int
toIdx int

RemoveItem(int)

Removes the item specified by idx index from the list.

public void RemoveItem(int idx)

Parameters

idx int

Select(int, bool)

Select the item at the specified index.

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

public void Select(int idx, bool single = true)

Parameters

idx int
single bool

SetItemCustomBgColor(int, Color)

Sets the background color of the item specified by idx index to the specified Color.

public void SetItemCustomBgColor(int idx, Color customBgColor)

Parameters

idx int
customBgColor Color

SetItemCustomFgColor(int, Color)

Sets the foreground color of the item specified by idx index to the specified Color.

public void SetItemCustomFgColor(int idx, Color customFgColor)

Parameters

idx int
customFgColor Color

SetItemDisabled(int, bool)

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).

public void SetItemDisabled(int idx, bool disabled)

Parameters

idx int
disabled bool

SetItemIcon(int, Texture2D)

Sets (or replaces) the icon's Texture2D associated with the specified index.

public void SetItemIcon(int idx, Texture2D icon)

Parameters

idx int
icon Texture2D

SetItemIconModulate(int, Color)

Sets a modulating Color of the item associated with the specified index.

public void SetItemIconModulate(int idx, Color modulate)

Parameters

idx int
modulate Color

SetItemIconRegion(int, Rect2)

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

public void SetItemIconRegion(int idx, Rect2 rect)

Parameters

idx int
rect Rect2

SetItemIconTransposed(int, bool)

Sets whether the item icon will be drawn transposed.

public void SetItemIconTransposed(int idx, bool transposed)

Parameters

idx int
transposed bool

SetItemLanguage(int, string)

Sets language code of item's text used for line-breaking and text shaping algorithms, if left empty current locale is used instead.

public void SetItemLanguage(int idx, string language)

Parameters

idx int
language string

SetItemMetadata(int, Variant)

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

public void SetItemMetadata(int idx, Variant metadata)

Parameters

idx int
metadata Variant

SetItemSelectable(int, bool)

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

public void SetItemSelectable(int idx, bool selectable)

Parameters

idx int
selectable bool

SetItemText(int, string)

Sets text of the item associated with the specified index.

public void SetItemText(int idx, string text)

Parameters

idx int
text string

SetItemTextDirection(int, TextDirection)

Sets item's text base writing direction.

public void SetItemTextDirection(int idx, Control.TextDirection direction)

Parameters

idx int
direction Control.TextDirection

SetItemTooltip(int, string)

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

public void SetItemTooltip(int idx, string tooltip)

Parameters

idx int
tooltip string

SetItemTooltipEnabled(int, bool)

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

public void SetItemTooltipEnabled(int idx, bool enable)

Parameters

idx int
enable bool

SortItemsByText()

Sorts items in the list by their text.

public void SortItemsByText()

Events

EmptyClicked

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

public event ItemList.EmptyClickedEventHandler EmptyClicked

Event Type

ItemList.EmptyClickedEventHandler

ItemActivated

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

public event ItemList.ItemActivatedEventHandler ItemActivated

Event Type

ItemList.ItemActivatedEventHandler

ItemClicked

Triggered when specified list item has been clicked with any mouse button.

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

public event ItemList.ItemClickedEventHandler ItemClicked

Event Type

ItemList.ItemClickedEventHandler

ItemSelected

Triggered when specified item has been selected.

AllowReselect must be enabled to reselect an item.

public event ItemList.ItemSelectedEventHandler ItemSelected

Event Type

ItemList.ItemSelectedEventHandler

MultiSelected

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

public event ItemList.MultiSelectedEventHandler MultiSelected

Event Type

ItemList.MultiSelectedEventHandler
Edit this page