Items, lists and trees
A row with an icon, a title, a line under it and a trailing note, and the virtual list and the lazy tree built from rows like it.


In the galleryItemitemListlistTree Viewtree_view
They live in isolenui/kit/data.h and come in through isolenui/kit/kit.h. See the component kit.
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"
#include <stdio.h>
struct node {
const char* name;
uint64_t parent;
};
// ids start at one, zero is the root
static const node nodes[] = {
{}, { "src", 0u }, { "docs", 0u }, { "kit", 1u }, { "ui.cpp", 1u }, { "data.h", 3u },
};
static const uint32_t node_count = sizeof(nodes) / sizeof(nodes[0]);
struct files {
const char* const* names;
uint32_t count;
uint32_t cursor;
uint64_t picked;
};
static void fill(uint32_t i, ui::item_spec* out, void* user)
{
const files* f = static_cast<const files*>(user);
out->title = f->names[i];
out->description = i ? "file" : nullptr;
out->section = i == 0u;
}
static uint32_t children(uint64_t parent, uint64_t* out, uint32_t cap, void*)
{
uint32_t n = 0u;
for (uint64_t id = 1u; id < node_count; ++id) {
if (nodes[id].parent == parent) {
if (n < cap) {
out[n] = id;
}
++n;
}
}
// the full count even past cap, the tree calls again with room
return n;
}
static bool has_children(uint64_t id, void*)
{
return children(id, nullptr, 0u, nullptr) != 0u;
}
static const char* label(uint64_t id, char*, uint32_t, void*)
{
return nodes[id].name;
}
static void browser(ui::ctx* u, files* f)
{
ui::item_spec open = {};
open.title = "open folder";
open.trailing = "ctrl o";
if (ui::item(u, open)) {
printf("open\n");
}
// extra parts go in the trailing slot before the item closes
bool hit = false;
ui::item_spec sync = {};
sync.title = "sync";
sync.description = "last run an hour ago";
ui_item(u, sync, hit)
{
ui::badge(u, "new", ui::tone::accent);
}
if (hit) {
printf("sync\n");
}
// only rows in view are filled, strings need to live for the fill call
if (ui::list_view(u, "files", f->count, fill, f, &f->cursor, true)) {
printf("open %s\n", f->names[f->cursor]);
}
ui::tree_source src = {};
src.children = children;
src.has_children = has_children;
src.label = label;
ui::tree_event ev = {};
if (ui::tree_view(u, "tree", src, &f->picked, &ev)) {
printf("open %s\n", nodes[ev.id].name);
}
if (ev.toggled) {
printf("%s %s\n", nodes[ev.id].name, ui::tree_is_open(u, "tree", ev.id) ? "open" : "closed");
}
}item_spec
| Field | Default | Meaning |
|---|---|---|
icon | GFX_NONE | An svg before the title. |
title | null | The main line. It is also the key of an item or item_begin row. List rows are keyed by index. |
description | null | A smaller dim line under the title. It makes the row taller. |
trailing | null | Small dim text at the end, such as a shortcut. |
selected | false | Sets state_checked. |
disabled | false | Disables the row. |
section | false | A heading in small bold dim text. It is not a row, takes no input and returns false. |
A zeroed item_spec is the default. A row is the theme's row_h tall, or row_h plus small_px plus 6 with a description.
item
item(u, spec) paints the whole row as one canvas. It returns true on a click, or on Enter or Space while it has focus. Tab reaches it, but a click does not take focus.
item_begin(u, spec) builds the row from boxes instead, and returns the same thing. Whatever you declare before item_end lands after the trailing text, so badges and buttons fit there. Always call item_end. The ui_item(u, spec, hit) block macro sets hit and pairs them.
list_view
list_view(u, label, count, fill, user, &cursor, described) is a virtual list of items. It calls fill(index, &spec, user) for each row in view, starting from a zeroed spec. It returns true on Enter, Space or a double click, with cursor on the row. Pass null for cursor and the list keeps its own. described makes every row two lines tall.
- Keys. The list is one tab stop. Up and Down move a row, Home and End go to the ends, and Page Up and Page Down move by the rows in view less one. Section rows are skipped, looking at most 64 rows ahead. The cursor scrolls into view.
- Pointer. A press moves the cursor and a double click activates.
- Look. The cursor row and rows with
selectedcarrystate_checked. - Size. The frame grows to fit, at least 3 rows and at most every row.
The strings in a filled spec are copied as the row is painted, so they only need to live until fill returns.
tree_view
tree_view(u, label, src, &selected, &ev) shows a tree from a tree_source. It returns true on Enter or a double click. selected is written with the node under the cursor each frame. Set it from code and the cursor moves there when that node is shown. Pass null and the tree keeps its own.
tree_source field | Meaning |
|---|---|
version | Bump it when the tree changes, and the shown rows are rebuilt. |
children | Writes the children of parent into out, up to cap, and returns the full count even past cap. The tree then calls again with room. Parent 0 is the root. |
has_children | Whether a node gets an open mark. Without it every node gets one, and a node that opens empty loses it. |
label | A node's text, written into buf or returned from your own memory. It only needs to live until the call returns. |
icon | Optional. An svg for a node, told whether the node is open. |
user | Passed to every callback. |
Since 0 is the root, node ids should not be 0. tree_event reports activated, toggled, and id, the node that was toggled or else the node under the cursor.
- Keys. Enter activates. Space opens or closes a node with children. Right opens a node, or moves into an open one. Left closes a node, or climbs to its parent. Up, Down, Home, End and the page keys move.
- Type ahead. With focus, printable ASCII typed within 0.8 s of the last key builds a prefix of up to 31 characters and jumps to the next label that starts with it, without case. One key pressed again steps through the labels that start with it.
- Pointer. A press on the open mark toggles. A press elsewhere moves the cursor, and a double click off the mark activates.
tree_open(u, label, id, open) opens or closes a node from code, and tree_is_open(u, label, id) asks. Both find the tree by its label. Each level indents by three quarters of row_h.
Staying cheap
The list and the tree sit on a virtual list, so only rows in view are filled, asked for a label and declared, and each row is one painted canvas.
The tree is lazy. It keeps a flat list of the shown rows and asks for children only of open nodes. Opening or closing a node splices that one subtree in or out, and the whole list is rebuilt only when version changes. The open set is a hash set. Levels past 256 stay closed with a warning.
The list and the tree keep their state in the store under their label until ctx_destroy, so a fixed set of labels keeps the store bounded.
Right to left
The painted rows of item, the list and the tree run left to right in any direction, and the tree indents from the left. item_begin is made of boxes, so it follows the row mirroring in direction and bidi.
kit.conf line. The row look comes from role_row and state_checked. See states.