Virtual lists
A virtual list only declares the rows the viewport can see. Its cost tracks the viewport and never the item count, so a million rows scroll as cheaply as ten.


In the galleryVirtual Listvirtual_listListlist
ui::list_begin
list_begin opens a virtual view and returns how many rows to declare, starting at first. Every row must be row_h tall. Declare them, then call list_end. The list keeps its offset in double precision and only hands the solver the part inside the first row, so no float grows with the item count. One row above the viewport stays declared as overscan. In a column the list grows to fill the space and never goes below three rows. In a row it grows sideways.
The last argument, reveal, is a row index. When it is below count, the list scrolls just enough to show that row whole in the same frame, which is how a keyboard cursor stays in view. The default, 0xffffffff, reveals nothing.
#include "isolenui/ui/ui.h"
// list_begin returns how many rows to declare starting at first, the cost of
// the call tracks the viewport, never the item count, so a million row list
// is as cheap to scroll as a ten row one. every row must be row_h tall
static void event_log(ui::ctx* u, const char* const* rows, uint32_t row_count)
{
uint32_t first = 0;
const float row_h = 28.0f;
const uint32_t visible =
ui::list_begin(u, "event-log", row_count, row_h, &first);
for (uint32_t i = 0; i < visible; ++i) {
const uint32_t index = first + i;
ui::key(u, uint64_t(index));
ui_box(u, ui::row().height(row_h).items(lay_align_centre))
{
ui::text(u, rows[index], ui::mono(u));
}
}
ui::list_end(u);
}- first
- 0
- count
- 10
- lead
- 0 px
- trail
- 27,999,720 px
- total
- 28,000,000 px
- offset
- 0 px
lay_virtual this page computes with a port of lay_virtualize.Rows you measure, ui::list_open
list_open(u, s, total, offset, lead, pin) is the variable height form. You work out which rows are visible, usually with lay_virtualize_prefix below, then open the list with the full content height total, the scroll offset read from scroll_of, and lead, the distance from the top of the content to the first row you declare. The list is named by the key before it and closed with list_end. It returns false when the tree dropped it, for being too deep or too full. Then declare no rows, but still call list_end, since it pairs like open and close.
A list_pin moves the declared rows together after the solve, so a row whose height changed does not make the list jump. The point along row row, zero its top and one its bottom, lands y px down the view. row counts from the first row declared, and pin_first or pin_last keeps the first or last row from leaving a gap at that edge. A chat keeps its newest message on the bottom edge this way.
#include "isolenui/ui/ui.h"
// rows of different heights the caller measured, prefix[i] is where row i
// starts and prefix[count] is the total
static void messages(ui::ctx* u, const char* const* text, const float* prefix, uint32_t count)
{
ui::key(u, "messages");
const uint64_t id = ui::next_id(u);
const float view_h = ui::rect_of(u, id).h;
const ui::scroll_pos at = ui::scroll_of(u, id);
const lay_virtual v = lay_virtualize_prefix(view_h, float(at.y), count, prefix, 1u);
// while at the bottom, the newest row's bottom edge lands on the view's
// bottom, the row index counts from the first row declared
const ui::list_pin pin = { count - 1u - v.first, view_h, 1.0f, ui::pin_last };
const ui::list_pin* hold = at.max_y - at.y < 1.0 ? &pin : nullptr;
// false when the tree dropped it, list_end is still paired like close
if (ui::list_open(u, ui::col().grow().gap(0.0f), prefix[count], at.y, prefix[v.first], hold)) {
for (uint32_t i = v.first; i < v.first + v.count; ++i) {
ui::key(u, uint64_t(i));
ui_box(u, ui::col().height(prefix[i + 1u] - prefix[i]).pad(8.0f))
{
ui::text(u, text[i]);
}
}
}
ui::list_end(u);
}Underneath
Both helpers work without ui.h and return a lay_virtual. It holds first and count, the lead and trail space around the declared slice, the total extent, and the clamped offset.
lay_virtualizetakes a fixed extent and a gap and divides, which is constant time.lay_virtualize_prefixtakes an ascending prefix sum with one more entry than there are items, zero first and the total last. It finds the range with two binary searches, which is logarithmic.
#include "isolenui/ui/layout2.h"
// fixed row height, O(1): the first visible row and how many fit are both
// plain division, no search of any kind
static lay_virtual visible_fixed_rows(float scroll_offset, float viewport_h)
{
return lay_virtualize(viewport_h, scroll_offset, 10000u, 24.0f, 0.0f, 2u);
}
// variable row height, O(log n): prefix holds one ascending offset per item
// plus a trailing total, zero first, so two binary searches find the range
static lay_virtual visible_variable_rows(const float* row_heights,
uint32_t row_count, float scroll_offset,
float viewport_h, float* prefix_out,
uint32_t prefix_cap)
{
prefix_out[0] = 0.0f;
for (uint32_t i = 0; i < row_count && i + 1u < prefix_cap; ++i) {
prefix_out[i + 1u] = prefix_out[i] + row_heights[i];
}
return lay_virtualize_prefix(viewport_h, scroll_offset, row_count,
prefix_out, 2u);
}