class UIList

package smidr.widgets

extends UIComponent

implements IUIFocusable

@:build(openfl.utils._internal.AssetsMacro.initBinding())@:autoBuild(openfl.utils._internal.AssetsMacro.initBinding())

A virtualized, selectable list. Only the visible rows (+2) exist as display objects; they are recycled by modulo slot mapping, so scrolling by one row rebinds exactly one row and a 100k-entry list costs the same as a 20-entry one. Rows are fixed-height (the constraint that keeps the window math O(1)).

Data is provider-driven: setProvider(count, label) for huge/lazy datasets or setItems(array) for convenience. Custom row content subclasses UIListRow and overrides bind(), supplied through rowFactory.

Input: mouse wheel + scrollbar thumb drag everywhere; on mobile (touchScroll) dragging anywhere scrolls with fling momentum — a drag past the threshold steals the press so no row click fires. Clicking focuses the list; Up/Down move the selection, Enter fires onActivate (as does a double click).

Constructor

@:value({ rowHeight : 0 })new(width:Float, height:Float, rowHeight:Float = 0)

Parameters:

width

layout width (the scrollbar lives inside it)

height

the visible viewport height

rowHeight

base (unscaled) row height; 0 picks the platform default

Variables

@:value(0)read onlyitemCount:Int = 0

Total data entries.

read onlymaxScroll:Float

The furthest scrollY can go.

read onlyrowHeightBase:Float

Base (unscaled) row height.

@:value(0)read onlyscrollY:Float = 0

Current scroll offset in pixels (0..maxScroll).

@:value(-1)read onlyselectedIndex:Int = -1

The selected row index, or -1.

@:value(false)touchScroll:Bool = false

Drag-anywhere scrolling with fling momentum (default on for mobile).

@:value(40)wheelStep:Float = 40

Pixels per wheel notch.

@:value(null)onActivate:Int ‑> Void = null

Fired on double click / Enter on the selected row.

@:value(null)onSelect:Int ‑> Void = null

Fired when the selection changes (click or arrow keys).

@:value(null)rowFactory:UIList ‑> UIListRow = null

Creates one pooled row; null uses the default single-label UIListRow.

Methods

capturesKeyboard():Bool

inlinelabelOf(index:Int):String

The display label for an index (used by the default row's bind).

Parameters:

index

the entry index

Returns:

the label ("" without a provider)

onFocusGained():Void

onFocusLost():Void

onKeyDown(keyCode:Int, charCode:Int, ctrl:Bool, shift:Bool, alt:Bool):Bool

refresh():Void

Rebinds every visible row in place (call after mutating the underlying data without changing the count).

scrollTo(index:Int):Void

Scrolls the minimum distance to bring an index fully into view.

Parameters:

index

the entry to reveal

@:value({ reveal : false })select(index:Int, reveal:Bool = false):Void

Programmatically selects an index without firing onSelect.

Parameters:

index

the entry to select, or -1 to clear

reveal

true also scrolls the row into view

inlinesetItems(items:Array<String>):Void

Convenience data source from an array (see setProvider).

Parameters:

items

the row labels

setProvider(count:Int, label:Int ‑> String):Void

Sets the data source (row labels resolved lazily; nothing is built up front). Clamps the selection and scroll, then rebinds the visible window.

Parameters:

count

the total number of entries

label

resolves the display label for an index

setScroll(value:Float):Void

Scrolls to an absolute offset (clamped) and rebinds the visible window.

Parameters:

value

the target offset in pixels

Inherited Variables

Defined by UIComponent

@:value(true)enabled:Bool = true

Disabled widgets ignore the pointer and typically render dimmed.

@:value(0)read onlyh:Float = 0

Layout height in UI units.

@:value(MouseCursor.BUTTON)hoverCursor:MouseCursor = MouseCursor.BUTTON

Native cursor while hovering (interactive widgets; null keeps the arrow).

@:value(false)read onlyhovered:Bool = false

true while the cursor is over this widget.

@:value(null)onClick:() ‑> Void = null

Fired on a completed click (press + release on this widget).

@:value(null)onHover:() ‑> Void = null

Fired when the cursor first enters this widget (hover-driven descriptions/previews).

@:value(null)onRightClick:() ‑> Void = null

Fired on a right mouse press over this widget (context menus).

@:value(false)read onlypressed:Bool = false

true while a press that started here is held.

@:value(null)tooltip:String = null

Optional tooltip text (already-localized or a fixed string).

@:value(null)tooltipShortcut:String = null

Optional right-aligned shortcut hint rendered in the tooltip.

@:value(0)read onlyw:Float = 0

Layout width in UI units (independent of DisplayObject's content-derived width).

Inherited Methods

Defined by UIComponent

invalidate():Void

Schedules a repaint for the next frame (cheap; deduplicated).

resize(width:Float, height:Float):Void

Sets the layout size and repaints when it changed.

Parameters:

width

the new layout width in UI units

height

the new layout height in UI units