ListView

Wire name listview

A single-column list of selectable rows.

l=new listview children={
	new item caption="Alpha"
	new item caption="Beta"
	new item caption="Gamma"
} selected=0

---

Properties

Property	Type	Default	Meaning
alternate_rows	flag	false	Ledger-band non-selected rows. Same switch as ledger; prefer ledger.
ledger	flag	false	Alternate non-selected rows in the ledger colors.
selected	int	-1	Selected row index (-1 = none).

Plus the common properties.

Rows are children of the shared virtual item type, whose caption is the row text. The same item builds a TreeView and a ComboBox; nesting items is a tree's business, and a list rejects it.

Events

activate — A row was activated — double-clicked, or Enter on the selection.

Field	Type	Meaning
trinket	uint	The list's object ID.
selected	int	Index of the activated row.

change — The selection moved.

Field	Type	Meaning
trinket	uint	The list's object ID.
selected	int	Index of the newly selected row, or -1 for none.

change is the selection moving — by arrow key, by click, or by an application set. activate is the user choosing a row: double-click, or Enter on the selection. A list that opens something wants activate; a list that drives a detail pane beside it wants change.

Getting selected right

selected indexes rows that have to exist already, and properties apply in the order they are written. Out of order it does not error — it quietly lands somewhere else:

new listview selected=2 children={new item caption="A"; new item caption="B"; new item caption="C"}
  ->  selected = 0

new listview children={new item caption="A"; new item caption="B"; new item caption="C"} selected=2
  ->  selected = 2

Both build the same three rows. Only the second honours the index you asked for, and there is no error at build time — just the wrong row highlighted later.

Writing children first is enough in one statement. Where the same list is built more than once, a template settles it for good, because a template's children are applied before any instance's properties:

template Sizes=listview children={
	new item caption="Small"
	new item caption="Medium"
	new item caption="Large"
}
lv=new Sizes selected=2

The order is now the template's business rather than each caller's.

The same applies to ComboBox and TreeView.

Selection

-1 means nothing is selected, and an empty list reports -1. A client's handle mirrors the value, so reading it is local:

l := ui.ListView("l")
l.Selected()          // the replica's index
l.Select(2)           // write through
l.OnChange(func(i int) { … })

Keys and mouse

	Does
Up Down	Move the selection.
Home End	First / last row.
PageUp PageDown	A screenful.
Return	Activate the selection.
Click	Select.
Double-click	Activate.

It takes focus by Tab and by click.

Appearance

ledger and alternate_rows are the same switch. Either one bands the non-selected rows in the scheme's ledger colors — the green-bar look — and the selection keeps its own colors either way.

They are not two features that combine. They write the same state, so the last one written wins:

new listview ledger !alternate_rows children={new item caption="A"}
  ->  banding off

Prefer ledger. It is the name TreeView uses, and the only one of the two that says what the banding looks like. alternate_rows is kept so existing scripts keep working.

See also

TreeView — nesting, columns, sorting, in-place editing · ComboBox — the same list, collapsed · Common Properties