On this page

Grid

A grid opens with ui::open_grid or the ui_grid macro and takes a lay_grid_spec. The spec is built by chaining columns, rows, areas, gap and flow.

Track text

Tracks use a CSS-style grammar, and lengths are logical units with or without px. You can use %, fr, auto, min-content, max-content, minmax(lo, hi), fit-content(px), repeat(n, ...), repeat(auto-fill, ...) and repeat(auto-fit, ...). Auto-fill keeps every track that fits even when it is empty. Auto-fit collapses the empty ones. Text that cannot be read sets lay_template::bad and the byte offset in bad_at.

The spec is copied when the grid opens, so a stack spec works. A static const spec built once keeps the text parse off the frame entirely. lay_tracks, lay_tr, lay_minmax and the breadth helpers build the same templates without text.

grid_tracks.cpp
#include "isolenui/ui/ui.h"

// the track text is parsed once into a static spec, not on every frame, the
// comment on lay_grid_open is explicit about that cost
static void card_grid(ui::ctx* u, uint32_t card_count)
{
    static const lay_grid_spec spec = lay_grid_spec{}
        .columns("repeat(auto-fit, minmax(180px, 1fr))")
        .rows("min-content")
        .auto_rows(lay_tr(lay_min_content()))
        .gap(16.0f);

    ui_grid(u, ui::col().grow().pad(16.0f), &spec)
    {
        for (uint32_t i = 0; i < card_count; ++i) {
            ui::key(u, uint64_t(i));
            ui_box(u, ui::col().pad(12.0f).round(8.0f).bg("#161616"))
            {
                ui::textf(u, ui::body(u), "card %u", i);
            }
        }
    }
}

// a status bar mixing every track kind the grammar knows: a fixed icon, a
// percent held column, whatever the label needs, the widest of the values
// column's own content, a value capped at 160px, and the rest as free space
static void status_bar(ui::ctx* u)
{
    static const lay_grid_spec spec = lay_grid_spec{}
        .columns("32px 20% auto max-content fit-content(160px) 1fr")
        .rows("40px")
        .gap(8.0f);

    ui_grid(u, ui::row().grow(), &spec)
    {
        ui_box(u, ui::col()) { ui::text(u, "*", ui::caption(u)); }
        ui_box(u, ui::col()) { ui::text(u, "backend", ui::caption(u)); }
        ui_box(u, ui::col()) { ui::text(u, "vulkan", ui::body(u)); }
        ui_box(u, ui::col()) { ui::text(u, "60 fps", ui::body(u)); }
        ui_box(u, ui::col()) { ui::text(u, "4096 mb free", ui::caption(u)); }
        ui_box(u, ui::col()) { ui::spacer(u); }
    }
}

// auto-fill keeps every track the grid can fit, even ones nothing is placed
// in, unlike auto-fit which collapses the empty ones away
static void thumbnail_strip(ui::ctx* u, uint32_t thumb_count)
{
    static const lay_grid_spec spec = lay_grid_spec{}
        .columns("repeat(auto-fill, 96px)")
        .rows("96px")
        .gap(8.0f);

    ui_grid(u, ui::row().grow(), &spec)
    {
        for (uint32_t i = 0; i < thumb_count; ++i) {
            ui::key(u, uint64_t(i));
            ui_box(u, ui::col().round(6.0f).bg("#181818")) {}
        }
    }
}

// a fixed sidebar plus a flexible body, the sidebar never grows past 320px
static void sidebar_layout(ui::ctx* u)
{
    static const lay_grid_spec spec = lay_grid_spec{}
        .columns("minmax(200px, 320px) 1fr")
        .rows("1fr")
        .gap(0.0f);

    ui_grid(u, ui::row().grow(), &spec)
    {
        ui_box(u, ui::col().bg("#111111"))
        {
            ui::text(u, "sidebar", ui::caption(u));
        }
        ui_box(u, ui::col().grow())
        {
            ui::text(u, "content", ui::body(u));
        }
    }
}

Areas, lines and dense flow

Named areas read like a small picture of the page. Rows are split by /, a . is an empty cell, and each name must form a rectangle. A child joins an area with area("name"). It can also be placed by line with column(a, b) and row(a, b), where lines count from one and a negative line counts back from the far edge, or it can be sized with span(cols, rows). flow(lay_flow_row, true) turns on dense packing, which backfills holes that wider items leave.

Named grid areasinteractive illustration
template
lay_grid_spec{}
  .columns("220px 1fr")
  .rows("56px 1fr 32px")
  .areas("head head / side body / side foot")
area("head")
area("side")
area("body")
area("foot")
Every name in the area text has to form a rectangle. Pixel tracks are drawn at 60 percent so the picture fits.
grid_areas.cpp
#include "isolenui/ui/ui.h"

// named areas read like a little picture of the page, a dot is an empty cell
static void app_shell(ui::ctx* u)
{
    static const lay_grid_spec spec = lay_grid_spec{}
        .columns("220px 1fr")
        .rows("56px 1fr 32px")
        // rows split on a slash, a newline is only whitespace to the parser
        .areas("head head / side body / side foot")
        .gap(0.0f);

    ui_grid(u, ui::col().grow(), &spec)
    {
        ui_box(u, ui::row().area("head").bg("#141414")) { ui::text(u, "isolen", ui::head(u)); }
        ui_box(u, ui::col().area("side").bg("#101010")) { ui::text(u, "nav", ui::caption(u)); }
        // the body is the part that scrolls, the head, side and foot hold still
        ui_box(u, ui::view().area("body").pad(16.0f)) { ui::text(u, "body", ui::body(u)); }
        ui_box(u, ui::row().area("foot").bg("#141414")) { ui::text(u, "status", ui::caption(u)); }
    }
}

// explicit line placement plus a span, dense packing fills the hole a
// two wide tile would otherwise leave open
static void dense_tiles(ui::ctx* u)
{
    static const lay_grid_spec spec = lay_grid_spec{}
        .columns("repeat(4, 1fr)")
        .rows("repeat(3, 96px)")
        .flow(lay_flow_row, true)
        .gap(8.0f);

    ui_grid(u, ui::col().grow(), &spec)
    {
        ui_box(u, ui::col().span(2, 1).bg("#181818")) { ui::text(u, "wide", ui::caption(u)); }
        for (uint32_t i = 0; i < 6; ++i) {
            ui::key(u, uint64_t(i));
            ui_box(u, ui::col().bg("#141414")) { ui::textf(u, ui::caption(u), "%u", i); }
        }
        // ui::style::column only takes plain ints, unlike lay_style::column
        // which also takes lay_line, so the ends of the row are 1 and -1
        ui_box(u, ui::col().column(1, -1).bg("#101010"))
        {
            ui::text(u, "full row", ui::caption(u));
        }
    }
}

Last updated 23 October 2026