Basalt/docs/objects/List.md

Lists are objects that allow you to create a collection of entries from which the user can make a selection.

In addition to the Object and VisualObject methods, lists also have the following methods:

addItem	Adds a new item into the list
removeItem	Removes an item from the list
editItem	Changes an already existing item in the list
getItem	Returns an item by its index
getItemCount	Returns the item count
setOptions	Updates the list options
getOptions	Returns the entire list as a table
selectItem	Selects an item
clear	Makes the entire list empty
getItemIndex	Returns the currently active item index
setOffset	Changes the list offset
getOffset	Returns the current offset
setScrollable	Makes the list scrollable
setSelectionColor	Changes the default bg and fg when the user selects an item
getSelectionColor	Returns default bg and fg selection color
isSelectionColorActive	Returns if it is using selection color

A item-table in lists looks like the following example:

item = {
  text="1. Entry",  -- the text its showing
  bgCol=colors.black,  -- the background color
  fgCol=colors.white -- the foreground color
  args = {} -- custom args you want to pass, which you will be able to access in for example onChange events
}

Example

Lua:

local main = basalt.createFrame()
local aList = main:addList()
aList:addItem("Item 1")
aList:addItem("Item 2", colors.yellow)
aList:addItem("Item 3", colors.yellow, colors.green)

aList:onChange(function(self, item)
  basalt.debug("Selected item: ", item.text)
end)

XML:

<list>
  <item><text>Item 1</text></item>
  <item><text>Item 2</text><bg>yellow</bg></item>
  <item><text>Item 3</text><bg>yellow</bg><fg>green</fg></item>
  <onChange>
    basalt.debug("Selected item: ", item.text)
  </onChange>
</list>