VirtualListElement record
Scroll-windowed variable list: renders a small fixed Pool of K rows (K ≈ viewport rows + a few margin rows) over a logical list of Count() items that may be FAR larger than K. The framework sizes a scroll content spacer to Count()*RowHeight, tracks the scroll offset, computes the first visible logical index, calls OnWindow(first) BEFORE pulling any slot values (so the plugin’s row Funcs resolve item first+slotIndex), positions the pool rows at their logical offset, and SetActive-shows only rows whose logical index < Count(). Rows are uniform fixed-height (RowHeight) UNLESS VariableHeight is set — see below. Use for large pickers; the small ListElement (eager full pool) stays for short lists. Height is the viewport height.
public record VirtualListElement : IEquatable<HudElement>Public Members
Section titled “Public Members”| name | description |
|---|---|
| VirtualListElement(…) | Scroll-windowed variable list: renders a small fixed Pool of K rows (K ≈ viewport rows + a few margin rows) over a logical list of Count() items that may be FAR larger than K. The framework sizes a scroll content spacer to Count()*RowHeight, tracks the scroll offset, computes the first visible logical index, calls OnWindow(first) BEFORE pulling any slot values (so the plugin’s row Funcs resolve item first+slotIndex), positions the pool rows at their logical offset, and SetActive-shows only rows whose logical index < Count(). Rows are uniform fixed-height (RowHeight) UNLESS VariableHeight is set — see below. Use for large pickers; the small ListElement (eager full pool) stays for short lists. Height is the viewport height. |
| Count { get; set; } | |
| FixedHeight { get; set; } | Optional — pin the viewport to exactly Height (like FixedHeight). By default the viewport is FLEXIBLE: it starts at Height and takes a share of any spare height in its column. Set this for a list that must keep its size inside a fixed-size layout. Default false = unchanged. An init property (binary-compatible); needs framework ≥2.30.0. |
| Height { get; set; } | |
| OnAtBottomChanged { get; set; } | Optional — invoked on the main thread whenever the list’s “at the bottom” state FLIPS, and once with the initial state after the list first lays out (and again after a window rebuild). “At the bottom” is exactly the decision StickToBottom uses to keep the view pinned on an append, so the two never disagree: within a couple of px of the bottom, and content that fits inside the viewport counts as at the bottom. Typical use: a chat “↓ N new messages” bar shown while the reader is scrolled up. Reported only for a VariableHeight + StickToBottom list (never invoked otherwise). The state is read once per window refresh, so a flip reaches the callback up to one refresh late. Default null = unchanged. An init property (binary-compatible). |
| OnReorder { get; set; } | Optional — turns on drag-and-drop REORDERING of the list’s items, with the same gesture and semantics as OnReorder: a press on a row that moves past ~6 screen px starts a drag (the row dims, a ghost follows the cursor, an accent bar marks the insertion point between rows); dropping fires OnReorder(from, to) with REMOVE-THEN-INSERT semantics over the FULL item index space (0..Count()-1, not pool-slot indices), so the consumer does var x = list[from]; list.RemoveAt(from); list.Insert(to, x);. It never fires for a no-op drop. Esc, or a drop outside the list’s viewport, cancels. A press released before the threshold is an ordinary click; after a real drag the click is swallowed. Holding the drag near the top or bottom edge of the viewport (within about one row) AUTO-SCROLLS the list, faster the closer to the edge, so an item can be moved past the visible rows; the dragged item keeps its identity while its pool slot is recycled. The list does not reflow mid-drag — the consumer reorders its data and the list re-pulls. Uniform rows only: ignored when VariableHeight is set. Default null = not reorderable (the list behaves exactly as before). An init property (binary-compatible); a plugin that sets it needs framework ≥2.29.0. |
| OnWindow { get; set; } | |
| Pool { get; set; } | |
| ResetScroll { get; set; } | When non-null, polled each refresh — returning true resets the scroll offset (to the top, or to the bottom when StickToBottom is set) and, in VariableHeight mode, forgets the measured-height model (row ↔ data-index associations have changed, e.g. a filter switch), so heights re-measure from the next shown frame. |
| RowHeight { get; set; } | |
| RowId { get; set; } | Optional stable per-ROW identity (data index → a reasonably-collision-free id for the MESSAGE/item currently at that index), used ONLY in VariableHeight mode to keep the measured-height cache honest when the data source re-maps indices WITHOUT changing Count. A latched height is keyed by data index; if the consumer’s backing store is a rolling buffer that front-drops at capacity (e.g. a capped chat ring), every new item shifts every index by one while Count stays constant, so a cached height silently belongs to a different item than the index now points at — a tall row’s slot inherits a short row’s latch and overflows. When supplied, the list re-verifies a latched row’s height the moment the identity under it changes and drops the latch only if the height is grossly wrong (an item whose replacement happens to be the same height keeps its latch, so no needless re-flow); a row whose identity is unchanged is still skipped with no re-measure, so scrolling stays cheap. Null (default) = today’s behaviour exactly (a latched row is never re-measured). Fed the SAME data index the pool slots resolve (window-independent), NOT a pool-slot offset. An init property (binary-compatible). |
| RowRevision { get; set; } | Optional per-row CONTENT revision (data index → a number the consumer changes whenever that row’s content changes in a way that can change its height — e.g. a chat message swapping to its translation, or a status line appearing under it). VariableHeight mode only. A row’s measured height is normally latched for good; when its revision differs from the one it was latched under, the list re-measures that one row IN PLACE (it stays on screen at its old height meanwhile — no blank, no park) and commits the new height once two consecutive readings agree, then re-flows the rows below (a bottom-pinned StickToBottom view stays pinned; otherwise the topmost visible row holds still). Return the same value (e.g. 0) for rows that never change. Independent of RowId (identity) — use both together. Default null = unchanged. An init property (binary-compatible). |
| ScrollToBottomRequest { get; set; } | Optional counter token: when the returned value CHANGES (vs the value seen when the list was built — a fresh/rebuilt list never jumps on its own), the list scrolls to the newest row and, with StickToBottom, re-engages the bottom pin, so rows below that were not yet measured (and grow the content as they latch their real heights) are followed until the view settles on the true bottom. Keep an int, increment it in the click/send handler, and bind ScrollToBottomRequest = () => _seq. Without StickToBottom it is a one-shot jump to the current (estimated) bottom. Honoured in VariableHeight mode only. Default null = unchanged. An init property (binary-compatible). |
| StableSlots { get; set; } | Optional — keep each data row in the SAME pool slot for as long as it stays in the window (VariableHeight mode only). Normally pool slot k shows row first + k, so whenever first moves by one — every append to a bottom-pinned StickToBottom list that is longer than the pool, and every scroll step — EVERY slot is rebound to a different row (new text, new avatar, a bubble width re-solve each). With this set, row l lives in slot l % Pool.Count: a one-row shift recycles only the slot whose row left the window, and every other slot keeps its content untouched. OnWindow still reports first; the row Funcs must then resolve slot k through StableSlotRow(first, k, Pool.Count) instead of first + k. Default false = unchanged. An init property (binary-compatible). |
| StickToBottom { get; set; } | Newest-at-bottom behaviour (chat log): the list starts scrolled to the BOTTOM, and when the user is already at the bottom a grown Count (a new row appended) keeps them pinned there; if they have scrolled up, an append does NOT yank them down — their position is preserved. Only governs the SCROLL position (when the content exceeds the viewport); short content sits top-aligned like any scroll. Default false = start at the top. An init property (binary-compatible). Independent of VariableHeight, though the two are used together for a wrapping chat history. |
| VariableHeight { get; set; } | Opt into VARIABLE-height rows: each pooled slot is MEASURED (uGUI preferred height, exactly as a BubbleElement/ContentSizeFitter fits itself) after it is bound to a data index, and the list keeps a per-index height model + cumulative offsets instead of assuming uniform rows. Un-measured rows use RowHeight as a baseline estimate (a running average of the measured rows once any exist), so the scrollbar is approximately right immediately and refines as rows scroll into view. Positioning uses the cumulative offsets; the content height is derived from the model. Default false = the original uniform path, byte-identical for existing consumers. The pool must still be sized to cover the viewport (≈ viewport ÷ the SHORTEST row + a buffer) — a pool smaller than the on-screen row count leaves a gap, same as the uniform list. An init property (not a ctor param) so the record stays binary-compatible. |
See Also
Section titled “See Also”- record HudElement
- namespace Stellar.Abstractions.Services