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
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()
Core Lua documentation entry points
