Lua:Class:Listview

{} Class

class ListView : WinControl

The ListView class represents a list view control.

A ListView inherits from WinControl, Control, Component, and Object. It can display rows, columns, icons, and virtual data. It also supports custom drawing through several draw-related event handlers.

Inheritance

Class	Inherits From	Description
ListView	WinControl	A list view control that can display items, columns, and images.
WinControl	Control	Base class for windowed controls.
Control	Component	Base class for visual controls.
Component	Object	Base class for components.

Creation

<> Lua API Reference

function createListView(owner) : ListView

Creates a ListView object that belongs to the given owner.

The owner can be any object inherited from WinControl.

Function Parameters

Parameter	Type	Description
owner	WinControl	The owner of the list view. This can be any object inherited from WinControl.

Returns

ListView — The created ListView object.

Properties

Property	Type	Description
Columns	ListColumns	The ListColumns object of the list view. This property is read-only.
Items	ListItems	The ListItems object of the list view.
ItemIndex	Integer	The currently selected index in the Items object. Returns -1 if nothing is selected.
Selected	ListItem	The currently selected ListItem. Returns nil if nothing is selected.
TopItem	ListItem	The first visible item in the list view.
VisibleRowCount	Integer	The number of rows currently visible.
Canvas	Canvas	The Canvas object used to render the list view. This property is read-only.
AutoWidthLastColumn	Boolean	When true, the last column resizes when the control resizes.
HideSelection	Boolean	When true, the selection will not hide when the focus leaves the control.
RowSelect	Boolean	When true, the whole row is selected instead of only the first column.
OwnerData	Boolean	When true, the list view calls the OnData function for every line being displayed. Use Items.Count to set the number of virtual lines.
LargeImages	ImageList	The image list used for large item images.
SmallImages	ImageList	The image list used for small item images.
StateImages	ImageList	The image list used for state images.
OnData	Function	Called when a list view with OwnerData set to true renders a line.
OnCustomDraw	Function	Called for custom drawing of the list view.
OnCustomDrawItem	Function	Called for custom drawing of a list item.
OnCustomDrawSubItem	Function	Called for custom drawing of a list subitem.

Events

Event	Function Signature	Description
OnData	function(sender, ListItem)	Called when a list view with OwnerData set to true renders a line.
OnCustomDraw	function(sender, rect, DefaultDraw)	Called for custom drawing of the list view. The rect table contains Top, Left, Bottom, and Right fields. The function can return a new DefaultDraw value.
OnCustomDrawItem	function(sender, ListItem, state, DefaultDraw)	Called for custom drawing of a list item. The state table contains custom draw state flags. The function can return a new DefaultDraw value.
OnCustomDrawSubItem	function(sender, ListItem, SubItemIndex, state, DefaultDraw)	Called for custom drawing of a list subitem. The state table contains custom draw state flags. The function can return a new DefaultDraw value.

Custom Draw Rect Fields

Field	Type	Description
Top	Integer	The top edge of the drawing rectangle.
Left	Integer	The left edge of the drawing rectangle.
Bottom	Integer	The bottom edge of the drawing rectangle.
Right	Integer	The right edge of the drawing rectangle.

Custom Draw State Fields

Field	Type	Description
cdsSelected	Boolean or nil	True when the item is selected.
cdsGrayed	Boolean or nil	True when the item is grayed.
cdsDisabled	Boolean or nil	True when the item is disabled.
cdsChecked	Boolean or nil	True when the item is checked.
cdsFocused	Boolean or nil	True when the item is focused.
cdsDefault	Boolean or nil	True when the item is in the default state.
cdsHot	Boolean or nil	True when the item is hot or hovered.
cdsMarked	Boolean or nil	True when the item is marked.
cdsIndeterminate	Boolean or nil	True when the item is in an indeterminate state.

Methods

Method	Return Type	Description
clear()	void	Clears the list view.
getColumns()	ListColumns	Returns the ListColumns object of the list view.
getItemAt(x, y)	ListItem	Returns the ListItem at the given coordinates. Returns nil if there is no item at the given position.
getItems()	ListItems	Returns the ListItems object of the list view.
getItemIndex()	Integer	Returns the currently selected index in the Items object.
setItemIndex(index)	void	Sets the current item index.
getCanvas()	Canvas	Returns the Canvas object used to render the list view.
beginUpdate()	void	Tells the list view to stop updating while changes are being made.
endUpdate()	void	Applies all updates made between beginUpdate and endUpdate.

Examples

local form = createForm()
form.Caption = "ListView Example"
form.Width = 500
form.Height = 300

local listview = createListView(form)
listview.Parent = form
listview.Align = alClient
listview.RowSelect = true
listview.AutoWidthLastColumn = true

local columns = listview.getColumns()

local column = columns.add()
column.Caption = "Name"
column.Width = 200

column = columns.add()
column.Caption = "Value"
column.Width = 200

local items = listview.getItems()

local item = items.add()
item.Caption = "Health"
item.SubItems.add("100")

item = items.add()
item.Caption = "Mana"
item.SubItems.add("50")

form.show()

local form = createForm()
form.Caption = "ListView Selection Example"
form.Width = 500
form.Height = 300

local listview = createListView(form)
listview.Parent = form
listview.Align = alClient
listview.RowSelect = true
listview.AutoWidthLastColumn = true

local columns = listview.getColumns()

local column = columns.add()
column.Caption = "Name"
column.Width = 200

column = columns.add()
column.Caption = "Value"
column.Width = 200

local item = listview.Items.add()
item.Caption = "First item"
item.SubItems.add("First value")

item = listview.Items.add()
item.Caption = "Second item"
item.SubItems.add("Second value")

listview.ItemIndex = 0

if listview.Selected ~= nil then
  print("Selected item: " .. listview.Selected.Caption)
end

form.show()

local form = createForm()
form.Caption = "Virtual ListView Example"
form.Width = 500
form.Height = 300

local listview = createListView(form)
listview.Parent = form
listview.Align = alClient
listview.RowSelect = true
listview.OwnerData = true
listview.AutoWidthLastColumn = true

local columns = listview.getColumns()

local column = columns.add()
column.Caption = "Index"
column.Width = 120

column = columns.add()
column.Caption = "Text"
column.Width = 300

listview.Items.Count = 1000

listview.OnData = function(sender, item)
  item.Caption = "Row " .. tostring(item.Index)

  if item.SubItems.Count == 0 then
    item.SubItems.add("")
  end

  item.SubItems[0] = "Virtual item " .. tostring(item.Index)
end

form.show()

local form = createForm()
form.Caption = "ListView Update Example"
form.Width = 500
form.Height = 300

local listview = createListView(form)
listview.Parent = form
listview.Align = alClient
listview.RowSelect = true
listview.AutoWidthLastColumn = true

local columns = listview.getColumns()

local column = columns.add()
column.Caption = "Item"
column.Width = 200

column = columns.add()
column.Caption = "Number"
column.Width = 200

listview.beginUpdate()

for i = 1, 100 do
  local item = listview.Items.add()
  item.Caption = "Item " .. tostring(i)
  item.SubItems.add(tostring(i))
end

listview.endUpdate()

form.show()

Main Pages

Core Lua documentation entry points

◆ Lua
◆ Script Engine