ItemList

package
v0.0.0-...-20ed0ac Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 19, 2025 License: MIT Imports: 34 Imported by: 0

Documentation

Overview

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 IconModeTop 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".

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Advanced 

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any 

type Any interface {
	gd.IsClass
	AsItemList() Instance
}

type Expanded 

type Expanded = MoreArgs

type Extension 

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsCanvasItem 

func (self *Extension[T]) AsCanvasItem() CanvasItem.Instance

func (*Extension[T]) AsControl 

func (self *Extension[T]) AsControl() Control.Instance

func (*Extension[T]) AsItemList 

func (self *Extension[T]) AsItemList() Instance

func (*Extension[T]) AsNode 

func (self *Extension[T]) AsNode() Node.Instance

func (*Extension[T]) AsObject 

func (self *Extension[T]) AsObject() [1]gd.Object

type ID 

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance 

func (id ID) Instance() (Instance, bool)

type IconMode 

type IconMode int //gd:ItemList.IconMode

const (
	// Icon is drawn above the text.
	IconModeTop IconMode = 0
	// Icon is drawn to the left of the text.
	IconModeLeft IconMode = 1
)

type Instance 

type Instance [1]gdclass.ItemList

Instance of the class with convieniently typed arguments and results. 

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New 

func New() Instance

func (Instance) AddIconItem 

func (self Instance) AddIconItem(icon Texture2D.Instance) int

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

func (Instance) AddItem 

func (self Instance) AddItem(text string) int

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.

func (Instance) AllowReselect 

func (self Instance) AllowReselect() bool

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

func (Instance) AllowRmbSelect 

func (self Instance) AllowRmbSelect() bool

If true, right mouse button click can select items.

func (Instance) AllowSearch 

func (self Instance) AllowSearch() bool

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

func (Instance) AsCanvasItem 

func (self Instance) AsCanvasItem() CanvasItem.Instance

func (Instance) AsControl 

func (self Instance) AsControl() Control.Instance

func (Instance) AsItemList 

func (self Instance) AsItemList() Instance

func (Instance) AsNode 

func (self Instance) AsNode() Node.Instance

func (Instance) AsObject 

func (self Instance) AsObject() [1]gd.Object

func (Instance) AutoHeight 

func (self Instance) AutoHeight() bool

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

func (Instance) AutoWidth 

func (self Instance) AutoWidth() bool

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

func (Instance) Clear 

func (self Instance) Clear()

Removes all items from the list.

func (Instance) Deselect 

func (self Instance) Deselect(idx int)

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

func (Instance) DeselectAll 

func (self Instance) DeselectAll()

Ensures there are no items selected.

func (Instance) EnsureCurrentIsVisible 

func (self Instance) EnsureCurrentIsVisible()

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

func (Instance) FixedColumnWidth 

func (self Instance) FixedColumnWidth() int

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.

func (Instance) FixedIconSize 

func (self Instance) FixedIconSize() Vector2i.XY

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.

func (Instance) ForceUpdateListSize 

func (self Instance) 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.

func (Instance) GetHScrollBar 

func (self Instance) GetHScrollBar() HScrollBar.Instance

Returns the horizontal 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.

func (Instance) GetItemAtPosition 

func (self Instance) GetItemAtPosition(position Vector2.XY) int

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.

func (Instance) GetItemAutoTranslateMode 

func (self Instance) GetItemAutoTranslateMode(idx int) Node.AutoTranslateMode

Returns item's auto translate mode.

func (Instance) GetItemCustomBgColor 

func (self Instance) GetItemCustomBgColor(idx int) Color.RGBA

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

func (Instance) GetItemCustomFgColor 

func (self Instance) GetItemCustomFgColor(idx int) Color.RGBA

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

func (Instance) GetItemIcon 

func (self Instance) GetItemIcon(idx int) Texture2D.Instance

Returns the icon associated with the specified index.

func (Instance) GetItemIconModulate 

func (self Instance) GetItemIconModulate(idx int) Color.RGBA

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

func (Instance) GetItemIconRegion 

func (self Instance) GetItemIconRegion(idx int) Rect2.PositionSize

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

func (Instance) GetItemLanguage 

func (self Instance) GetItemLanguage(idx int) string

Returns item's text language code.

func (Instance) GetItemMetadata 

func (self Instance) GetItemMetadata(idx int) any

Returns the metadata value of the specified index.

func (Instance) GetItemRect 

func (self Instance) GetItemRect(idx int) Rect2.PositionSize

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.

func (Instance) GetItemText 

func (self Instance) GetItemText(idx int) string

Returns the text associated with the specified index.

func (Instance) GetItemTextDirection 

func (self Instance) GetItemTextDirection(idx int) Control.TextDirection

Returns item's text base writing direction.

func (Instance) GetItemTooltip 

func (self Instance) GetItemTooltip(idx int) string

Returns the tooltip hint associated with the specified index.

func (Instance) GetSelectedItems 

func (self Instance) GetSelectedItems() []int32

Returns an array with the indexes of the selected items.

func (Instance) GetVScrollBar 

func (self Instance) GetVScrollBar() VScrollBar.Instance

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.

func (Instance) ID 

func (self Instance) ID() ID

func (Instance) IconMode 

func (self Instance) IconMode() IconMode

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

func (Instance) IconScale 

func (self Instance) IconScale() Float.X

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

func (Instance) IsAnythingSelected 

func (self Instance) IsAnythingSelected() bool

Returns true if one or more items are selected.

func (Instance) IsItemDisabled 

func (self Instance) IsItemDisabled(idx int) bool

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

func (Instance) IsItemIconTransposed 

func (self Instance) IsItemIconTransposed(idx int) bool

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

func (Instance) IsItemSelectable 

func (self Instance) IsItemSelectable(idx int) bool

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

func (Instance) IsItemTooltipEnabled 

func (self Instance) IsItemTooltipEnabled(idx int) bool

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

func (Instance) IsSelected 

func (self Instance) IsSelected(idx int) bool

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

func (Instance) ItemCount 

func (self Instance) ItemCount() int

The number of items currently in the list.

func (Instance) MaxColumns 

func (self Instance) MaxColumns() int

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.

func (Instance) MaxTextLines 

func (self Instance) MaxTextLines() int

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

func (Instance) MoreArgs 

func (self Instance) MoreArgs() MoreArgs

MoreArgs enables certain functions to be called with additional 'optional' arguments.

func (Instance) MoveItem 

func (self Instance) MoveItem(from_idx int, to_idx int)

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

func (Instance) OnEmptyClicked 

func (self Instance) OnEmptyClicked(cb func(at_position Vector2.XY, mouse_button_index int), flags ...Signal.Flags)

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

'at_position' is the click position in this control's local coordinate system.

func (Instance) OnItemActivated 

func (self Instance) OnItemActivated(cb func(index int), flags ...Signal.Flags)

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

func (Instance) OnItemClicked 

func (self Instance) OnItemClicked(cb func(index int, at_position Vector2.XY, mouse_button_index int), flags ...Signal.Flags)

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

'at_position' is the click position in this control's local coordinate system.

func (Instance) OnItemSelected 

func (self Instance) OnItemSelected(cb func(index int), flags ...Signal.Flags)

Emitted when specified item has been selected. Only applicable in single selection mode.

AllowReselect must be enabled to reselect an item.

func (Instance) OnMultiSelected 

func (self Instance) OnMultiSelected(cb func(index int, selected bool), flags ...Signal.Flags)

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

func (Instance) RemoveItem 

func (self Instance) RemoveItem(idx int)

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

func (Instance) SameColumnWidth 

func (self Instance) SameColumnWidth() bool

Whether all columns will have the same width.

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

func (Instance) Select 

func (self Instance) Select(idx int)

Select the item at the specified index.

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

func (Instance) SelectMode 

func (self Instance) SelectMode() SelectMode

Allows single or multiple item selection. See the SelectMode constants.

func (Instance) SetAllowReselect 

func (self Instance) SetAllowReselect(value bool)

SetAllowReselect sets the property returned by [GetAllowReselect].

func (Instance) SetAllowRmbSelect 

func (self Instance) SetAllowRmbSelect(value bool)

SetAllowRmbSelect sets the property returned by [GetAllowRmbSelect].

func (Instance) SetAllowSearch 

func (self Instance) SetAllowSearch(value bool)

SetAllowSearch sets the property returned by [GetAllowSearch].

func (Instance) SetAutoHeight 

func (self Instance) SetAutoHeight(value bool)

SetAutoHeight sets the property returned by [HasAutoHeight].

func (Instance) SetAutoWidth 

func (self Instance) SetAutoWidth(value bool)

SetAutoWidth sets the property returned by [HasAutoWidth].

func (Instance) SetFixedColumnWidth 

func (self Instance) SetFixedColumnWidth(value int)

SetFixedColumnWidth sets the property returned by [GetFixedColumnWidth].

func (Instance) SetFixedIconSize 

func (self Instance) SetFixedIconSize(value Vector2i.XY)

SetFixedIconSize sets the property returned by [GetFixedIconSize].

func (Instance) SetIconMode 

func (self Instance) SetIconMode(value IconMode)

SetIconMode sets the property returned by [GetIconMode].

func (Instance) SetIconScale 

func (self Instance) SetIconScale(value Float.X)

SetIconScale sets the property returned by [GetIconScale].

func (Instance) SetItemAutoTranslateMode 

func (self Instance) SetItemAutoTranslateMode(idx int, mode Node.AutoTranslateMode)

Sets the auto translate mode of the item associated with the specified index.

Items use [Node.AutoTranslateModeInherit] by default, which uses the same auto translate mode as the ItemList itself.

func (Instance) SetItemCount 

func (self Instance) SetItemCount(value int)

SetItemCount sets the property returned by [GetItemCount].

func (Instance) SetItemCustomBgColor 

func (self Instance) SetItemCustomBgColor(idx int, custom_bg_color Color.RGBA)

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

func (Instance) SetItemCustomFgColor 

func (self Instance) SetItemCustomFgColor(idx int, custom_fg_color Color.RGBA)

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

func (Instance) SetItemDisabled 

func (self Instance) SetItemDisabled(idx int, disabled 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).

func (Instance) SetItemIcon 

func (self Instance) SetItemIcon(idx int, icon Texture2D.Instance)

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

func (Instance) SetItemIconModulate 

func (self Instance) SetItemIconModulate(idx int, modulate Color.RGBA)

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

func (Instance) SetItemIconRegion 

func (self Instance) SetItemIconRegion(idx int, rect Rect2.PositionSize)

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

func (Instance) SetItemIconTransposed 

func (self Instance) SetItemIconTransposed(idx int, transposed bool)

Sets whether the item icon will be drawn transposed.

func (Instance) SetItemLanguage 

func (self Instance) SetItemLanguage(idx int, language string)

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

func (Instance) SetItemMetadata 

func (self Instance) SetItemMetadata(idx int, metadata any)

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

func (Instance) SetItemSelectable 

func (self Instance) SetItemSelectable(idx int, selectable bool)

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

func (Instance) SetItemText 

func (self Instance) SetItemText(idx int, text string)

Sets text of the item associated with the specified index.

func (Instance) SetItemTextDirection 

func (self Instance) SetItemTextDirection(idx int, direction Control.TextDirection)

Sets item's text base writing direction.

func (Instance) SetItemTooltip 

func (self Instance) SetItemTooltip(idx int, tooltip string)

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

func (Instance) SetItemTooltipEnabled 

func (self Instance) SetItemTooltipEnabled(idx int, enable bool)

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

func (Instance) SetMaxColumns 

func (self Instance) SetMaxColumns(value int)

SetMaxColumns sets the property returned by [GetMaxColumns].

func (Instance) SetMaxTextLines 

func (self Instance) SetMaxTextLines(value int)

SetMaxTextLines sets the property returned by [GetMaxTextLines].

func (*Instance) SetObject 

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) SetSameColumnWidth 

func (self Instance) SetSameColumnWidth(value bool)

SetSameColumnWidth sets the property returned by [IsSameColumnWidth].

func (Instance) SetSelectMode 

func (self Instance) SetSelectMode(value SelectMode)

SetSelectMode sets the property returned by [GetSelectMode].

func (Instance) SetTextOverrunBehavior 

func (self Instance) SetTextOverrunBehavior(value TextServer.OverrunBehavior)

SetTextOverrunBehavior sets the property returned by [GetTextOverrunBehavior].

func (Instance) SetWraparoundItems 

func (self Instance) SetWraparoundItems(value bool)

SetWraparoundItems sets the property returned by [HasWraparoundItems].

func (Instance) SortItemsByText 

func (self Instance) SortItemsByText()

Sorts items in the list by their text.

func (Instance) TextOverrunBehavior 

func (self Instance) TextOverrunBehavior() TextServer.OverrunBehavior

The clipping behavior when the text exceeds an item's bounding rectangle.

func (Instance) Virtual 

func (self Instance) Virtual(name string) reflect.Value

func (Instance) WraparoundItems 

func (self Instance) WraparoundItems() bool

If true, the control will automatically move items into a new row to fit its content. See also HFlowContainer for this behavior.

If false, the control will add a horizontal scrollbar to make all items visible.

type MoreArgs 

type MoreArgs [1]gdclass.ItemList

MoreArgs is a container for Instance functions with additional 'optional' arguments.

func (MoreArgs) AddIconItem 

func (self MoreArgs) AddIconItem(icon Texture2D.Instance, selectable bool) int

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

func (MoreArgs) AddItem 

func (self MoreArgs) AddItem(text string, icon Texture2D.Instance, selectable bool) int

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.

func (MoreArgs) GetItemAtPosition 

func (self MoreArgs) GetItemAtPosition(position Vector2.XY, exact bool) int

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.

func (MoreArgs) GetItemRect 

func (self MoreArgs) GetItemRect(idx int, expand bool) Rect2.PositionSize

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.

func (MoreArgs) Select 

func (self MoreArgs) Select(idx int, single bool)

Select the item at the specified index.

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

type SelectMode 

type SelectMode int //gd:ItemList.SelectMode

const (
	// Only allow selecting a single item.
	SelectSingle SelectMode = 0
	// Allows selecting multiple items by holding Ctrl or Shift.
	SelectMulti SelectMode = 1
	// Allows selecting multiple items by toggling them on and off.
	SelectToggle SelectMode = 2
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.