Skip to content

Latest commit

 

History

History
808 lines (670 loc) · 52.9 KB

rust.md

File metadata and controls

808 lines (670 loc) · 52.9 KB

Rust: gpui syntax, HTML and CSS

The blenderui crate (bindings/rust/) gives Rust programs Blender's UI with the syntax of gpui: views implement Render, elements are built with div().flex().gap_2().child(...), and listeners come from cx.listener(...). On top of gpui's model it supports every HTML element and CSS: <style> sheets, selectors, the cascade, flexbox, grid, tables, inline text that wraps, lists, <details>, and form controls that look like a browser's, or like Blender's real widgets inside styled and as the capitalized Blender components.

The Rust showcase example

Install

blenderui is on crates.io:

cargo add blenderui

or, by hand, blenderui = "0.5" under [dependencies]. (The Dear ImGui crate is blenderui-imgui: cargo add blenderui-imgui.)

Building needs CMake and a C compiler: blenderui-sys compiles the C kit with the cmake crate. On Windows the default Rust target (x86_64-pc-windows-msvc) uses MSVC (Visual Studio Build Tools). To build against another checkout of the C sources, set BUI_SOURCE_DIR.

From the repository:

cd bindings/rust
cargo run --example showcase                        # the window above
cargo run --example showcase -- --screenshot a.png   # render it off-screen to a PNG
cargo run --example counter                         # the README example
cargo test                                          # unit, coverage and headless tests

The workspace uses edition 2024 (Rust 1.88 or newer, the rust-version in bindings/rust/Cargo.toml). On Linux, building also needs the X11 headers (libx11-dev / libX11-devel).

The app model

It follows gpui closely:

gpui blenderui
Application::new().run(|cx| ...) the same; Application::headless() renders off-screen
cx.open_window(options, |window, cx| cx.new(|cx| View)) the same; returns WindowHandle<View>
impl Render for View the same: fn render(&mut self, window, cx) -> impl IntoElement
Entity<T>, WeakEntity<T>, cx.new Copy handles into the app's entity slots: read (returns &T), update, downgrade; cx.release(e) drops a value
Context<T>: notify, listener, entity the same; it derefs to App
WindowOptions { window_bounds, titlebar, .. }, WindowBounds::Windowed(..) the same, plus is_resizable, window_min_size, gpu, window_background (WindowBackgroundAppearance::Transparent), kind (WindowKind::Floating stays on top, PopUp is on top without a frame, LayerShell(LayerShellOptions { layer, anchor, exclusive_zone, keyboard_interactivity }) is a Wayland layer-shell surface) and window_decorations (WindowDecorations::Client: no frame); App::on_window_activation reports focus. A Wayland toplevel cannot stay on top: use LayerShell
cx.set_global, cx.global the same
cx.stop_propagation() the same
use blenderui::prelude::*;

struct Todo { items: Vec<String>, draft: String }

impl Render for Todo {
    fn render(&mut self, _: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        div().p_4().flex().flex_col().gap_2()
            .child(h2().child(format!("{} items", self.items.len())))
            .child(ul().children(self.items.iter().map(|s| li().child(s.clone()))))
            .child(div().flex().gap_2()
                .child(input().id("draft").placeholder("New item").value(self.draft.clone())
                    .on_change(cx.listener(|this, e: &ChangeEvent, _, cx| {
                        this.draft = e.value.clone();
                        cx.notify();
                    })))
                .child(button().child("Add").on_click(cx.listener(|this, _, _, cx| {
                    this.items.push(std::mem::take(&mut this.draft));
                    cx.notify();
                }))))
    }
}

cx.notify() re-renders. Rendering builds a fresh element tree; elements with an .id(...) keep their state across renders (scroll position, a text field's contents, a checkbox you clicked, which <details> are open).

Window gives listeners viewport_size(), scale_factor(), mouse_position(), set_window_title(), focus_id() / focused_id(), is_hovered(id), scroll_offset(id) / set_scroll_offset(id, x, y), refresh() and request_animation_frame() (call it from render to animate; frames are paced to the display, set_vsync(false) lifts the cap). A <title> element sets the window title too.

Markup: rsx! / view!

JSX-style markup, lowered at compile time to the same builder calls (no runtime parsing):

rsx! {
    <div class="flex gap-2 p-4" onClick={|| println!("clicked")}>
        <h1 style="color: red">"Hello, " {name}</h1>
        <input type="checkbox" checked={done} />
        <ul>{for it in items { <li>{it}</li> }}</ul>
        {if done { <p>all done</p> }}
        {match mode { Mode::A => <A/>, Mode::B => <span>b</span> }}
        <Card title="Settings">{...rows}</Card>
    </div>
}

The lowering is uniform, so the whole API is reachable without special cases:

  • Tags: any tag becomes its function (<my-el> becomes Div::new("my-el")).
  • Attributes:
    • name="text" sets an HTML attribute, except class, style and id, which call their methods.
    • name={expr} calls the builder method of that name: w={px(10.)}, hover={|s| s.bg(red())}.
    • onClick becomes .on_click, and closures may omit the (event, window, cx) parameters.
  • Components: a component tag builds its props through a builder, so <Card title="x">..</Card> becomes Card::__builder().title("x").children(..). #[component] generates the builder; a hand-written struct component needs #[derive(Props)]. key={..} on any component ties its hook state to the key.
  • Fragments: <>..</> is a display: contents wrapper.

Tailwind utilities can also be written as bare attributes (UnoCSS calls this "attributify"). They become classes at compile time:

rsx! { <div p-4 w-1/2 bg-[#4772b3] hover:bg-sky-500/50 md:flex -mt-2 text-sm/6 /> }

HTML boolean attributes (disabled, checked, hidden, open ...) stay attributes. Anything that looks like a utility but isn't one is a compile error with suggestions, in rsx! and in tw! alike:

error: rsx!: `bg-sky-50O` is not a Tailwind utility; did you mean `bg-sky-500` or `bg-sky-50` or `bg-sky-100`?
error: rsx!: `hovr:bg-red-500` is not a Tailwind utility; did you mean `hover:bg-red-500` or `odd:bg-red-500`?
error: tw!: `roundd-lg` is not a Tailwind utility; did you mean `rounded-lg` or `rounded-s-lg` or `rounded-e-lg`?

Every Tailwind variant also works as an attribute prefix, chained as deep as you like:

rsx! {
    <button class="px-3 py-1 bg-zinc-800"
            hover:class="bg-sky-600 text-white"        // classes, prefixed
            active:style="transform: scale(0.97)"      // any CSS, as arbitrary properties
            focus-visible:outline="2px solid white"    // one CSS property
            md:dark:hover:class="bg-sky-400"           // chained variants
            hover:bg={rgb(0x4772b3)}>                  // typed value via .hover(|s| ..)
        "Save"
    </button>
}

group-hover:, peer-checked:, data-[state=open]:, aria-expanded:, @md:, 2xl:, max-sm:, *: and every other variant work the same way, because they all go through the Tailwind engine. Typed {expr} values are limited to hover, active and focus; use variant:class or variant:style with every other variant.

Components and hooks (zopra / React / Leptos style)

use blenderui::prelude::*;

#[component]                                   // zopra style: lowercase, &str props
fn profile(username: &str) {
    let (likes, set_likes) = use_state(0);     // `likes()`, `set_likes(..)`: no cx
    use_effect!(move || println!("{} likes", likes()), [likes()]);
    let theme: Theme = use_context();
    rsx! { <div class="p-2" onClick={move || set_likes(likes() + 1)}>{username.to_string()} " " {likes().to_string()}</div> }
}

#[component]                                   // Leptos style
fn Counter(start: i32) {
    let (count, set_count) = signal(start);
    let doubled = Memo::new(move || count.get() * 2);          // recomputed when `count` changes
    Effect::new(move || println!("count is {}", count.get())); // re-runs when `count` changes
    rsx! { <button onClick={move || set_count.update(|c| *c += 1)}>{doubled.get().to_string()}</button> }
}

// in a view: provide_context(Theme(..)); rsx! { <profile username="Ada" /> <Counter start={1} /> }

These are the hooks and their counterparts in other frameworks:

Hook Also known as
use_state(v) zopra / React useState (a getter and a setter closure)
use_signal(v), Signal::new(v) zopra use_signal, Leptos RwSignal
signal(v), create_signal(v) Leptos read and write halves
Memo::new(f), Effect::new(f) Leptos, tracking the signals they read automatically
use_effect(f, deps), use_effect!(f, [a, b]) React / zopra
use_memo(f, deps) React useMemo
provide_context(v), use_context(), try_use_context() Leptos / zopra context

How it behaves:

  • Signals: signals are Copy handles. They don't need cx, and writing one re-renders its window.
  • Hook identity: like React, a hook's state is tied to its call site and to the order in which components render. In lists, give components a key (<Row key={item.id} ../>) so their state follows the item: without keys, removing an item from the middle shifts the state of the ones after it.
  • Components: #[component] turns fn name(props) into a props struct with that name. Uppercase and lowercase names both work in rsx!. The body is a normal block that ends in markup, usually an rsx!.
  • Text children: {expr} in markup takes anything that turns into an element: text (&'static str, String, SharedString), an element or a component. Numbers and borrowed &str props aren't text on their own, so write {count().to_string()} and {label.to_string()}.
  • Optional props: Option<T> props (and children) may be left out in rsx!; they are None. Leaving out any other prop is a compile error naming it (a required prop is missing: ... Row_missing_name). Struct components get the same with #[derive(Props)].
  • Lifetime: a component's state is freed when it stops rendering.
  • Implementation: there is no Rc or RefCell anywhere in it.

Not supported yet: async resources (use_resource) and generic components.

Elements

There is one element type, Div, and a constructor for every element of the WHATWG HTML index: div(), span(), section(), table(), tr(), details(), dialog(), input(), select(), video() ... (113 elements, plus svg() and math() as boxes). Tags only change the defaults: what the user-agent stylesheet gives them and how they are realised.

Kind Elements Realised as
Box div, p, h1-h6, a, span, ul/ol/li, table ..., details, dialog, form ... laid out and painted from CSS
Widget button, input, select, textarea, progress, meter (+ option, optgroup, datalist) Blender's own widgets (below)
Replaced img, video, audio, iframe, embed, object, canvas an intrinsic size; img shows image files or RGBA pixels
Metadata head, title, style, script, meta, link, template ... not rendered (<style> and <title> are read)
Break br, wbr line breaks

Unknown names work too: custom("my-widget") is a box, like a custom element in a browser.

Every element has .child(..), .children(..), .id(..), .class(..), .attr(name, value) and typed attributes: .href, .value, .placeholder, .input_type, .name, .checked, .disabled, .selected, .open, .min, .max, .step, .src, .alt, .title, .colspan. A text field with the live attribute (<input live>) reports every keystroke to on_input and on_change, not only on Enter or blur. FluentBuilder adds .when(cond, |el| ..), .when_some(opt, |el, v| ..) and .map(..). Text children are &'static str, String or SharedString. An Option<T> of any of these is a child too: None renders nothing and leaves its siblings in place, so .child(cond.then(|| div())) and, in rsx!, { cond.then(|| rsx! { <p>"hi"</p> }) } or { maybe_title } are one-liners.

main() (the <main> element) has the same name as your program's fn main. Inside fn main call it as blenderui::html::main().

The document is wrapped in <html><body> unless your root already is one, so body { margin: 0 } and the user-agent defaults behave as in a browser.

Blender styling: styled

Plain elements look like they do in a browser: black text on white, 16 px, #0000ee links, and Chrome's form controls, in Blender's UI font (Inter). Mark an element styled and it, and everything inside it, gets Blender's look instead: the #303030 background, #e6e6e6 13 px UI-font text, blue links, dark code / pre, themed tables, fieldsets and dialogs, and Blender's widgets for the form controls.

body().styled().child(h1().child("Blender look"))     // gpui syntax
rsx! { <div styled class="p-4">"Blender look"</div> } // rsx! / view! (Leptos-style)
div().styled().child(div().attr("styled", "false"))   // opt a subtree back out

Your own CSS still wins over either set of defaults. From JavaScript use el.setAttribute('styled', ''), or <div styled> in JSX.

Dark or light. styled follows Blender's theme, which is Dark by default. Switch every window to Blender's Light preset with Application::new().theme("light"), blenderui::set_theme("light") at run time (open windows redraw), or BUI_THEME=light without code changes. The widgets, panels and the styled sheet all follow; plain HTML keeps the browser's look in both. blenderui::theme_name() and blenderui::theme_color("region_bg") read the active theme.

Blender components

The capitalized components are Blender's widgets, always, inside styled or not: Button, Checkbox, Radio, NumberField (drag to scrub), NumberSlider, TextField, TextArea, ColorSwatch (Blender's color picker), Dropdown and ProgressBar. Each is the element it stands for, so every element method and attribute works on it:

rsx! {
    <NumberSlider min={0.0} max={10.0} value="2.5" onChange={|e: &ChangeEvent| println!("{:?}", e.number)} />
    <Button onClick={|| println!("apply")}>"Apply"</Button>
    <Dropdown><option>"Cube"</option><option>"Sphere"</option></Dropdown>
}
div().child(Checkbox().checked(true)).child(Button().child("Apply"))   // gpui syntax

In JavaScript they're exported from @blender-ui/react (<NumberSlider min={0} max={10} />) and work as tag names with the DOM API (win.createElement('NumberSlider')). The lowercase HTML elements (button, input type="range" ...) look like a browser's controls, and like Blender inside styled. Run cargo run --example forms to see all three side by side.

Styling

Three ways, one cascade:

// 1. gpui / Tailwind methods
div().flex().items_center().gap_2().px_3().py_1().rounded_md().bg(rgb(0x3a3a3a))
    .text_color(white()).shadow_md().hover(|s| s.bg(rgb(0x4772b3)))

// 2. CSS blocks, checked at compile time (a misspelled property doesn't compile)
div().style(css!("border-left: 3px solid #4772b3; padding: 4px 8px"))

// 3. CSS built at run time
div().css("grid-template-columns", format!("repeat({n}, 1fr)"))
     .style(format!("width: {w}px"))

// 4. stylesheets, anywhere in the tree
style().child(".card:hover > h4 { color: #e6a23c } @media (max-width: 600px) { nav { display: none } }")

Styled methods (~1,300, generated from Tailwind's scales): spacing and sizing on the spacing scale (p_4, mx_auto, w_64, h_full, w_1_3, size(px(20.0)), gap_x_2), display and position (flex, grid, block, hidden, absolute, inset_0, z_index), flexbox (flex_col, flex_1, items_center, justify_between, flex_wrap), grid (grid_cols(3), col_span(2)), color (bg, text_color, border_color, opacity), borders and corners (border_1, border_t_2, rounded_lg, rounded_full), shadows (shadow_sm ... shadow_2xl), text (text_sm ... text_6xl, font_bold, italic, underline, uppercase, truncate, leading_tight, whitespace_nowrap), overflow (overflow_y_scroll) and cursors (cursor_pointer). Colors: rgb(0xRRGGBB), rgba(0xRRGGBBAA), hsla(h, s, l, a), named helpers, or any CSS color string.

State styles: .hover(|s| ..), .active(|s| ..) and .focus(|s| ..) take a refinement with the same methods (they are CSS :hover / :active / :focus rules for that element).

Selectors: type, *, #id, .class, attributes ([a], =, ~=, |=, ^=, $=, *=), combinators (descendant, >, +, ~), and pseudo-classes: :hover, :active, :focus, :focus-within, :focus-visible, :checked, :disabled, :enabled, :link, :any-link, :required, :optional, :read-only, :read-write, :open, :placeholder-shown, :first-child, :last-child, :only-child, :first-of-type, :last-of-type, :nth-child(), :nth-last-child(), :nth-of-type(), :nth-last-of-type(), :empty, :root, :not(), :is(), :where(). @media with width and height conditions is evaluated against the window.

Cascade: user-agent sheet, then author sheets, then inline declarations (methods, .css, .style), then state refinements; !important wins over all of them, and specificity and order decide within a level. inherit, initial, unset and revert are understood (they copy or reset the text, color, size and display properties). Custom properties (--name) inherit, and var() (with fallbacks, var(--missing, 20px)) and env() are substituted, also inside other functions (calc(var(--gap) * 2)). Units: px, em, rem, %, vw, vh, vmin, vmax, ch, ex, pt, pc, in, cm, mm, Q, and calc(), min(), max(), clamp().

Layout

Layout is computed with taffy:

  • Block flow with margins, padding, borders, box-sizing, min/max sizes and aspect-ratio.
  • Inline content becomes line boxes: text breaks into words that wrap, inline elements (b, a, code, mark ...) style their words, and inline-blocks and widgets sit on the line. white-space (normal, nowrap, pre, pre-wrap, pre-line), text-align, text-indent, letter-spacing, word-spacing, vertical-align: sub | super, text-transform and text-overflow: ellipsis apply. text-overflow works as in CSS: on a block whose overflow-x is not visible (usually with white-space: nowrap, Tailwind's truncate), a line wider than the content box is cut to it and ends with … (clip just cuts it); with overflow: visible it does nothing.
  • Flexbox and grid: every property of both modules, including grid-template-areas, named lines, repeat(), minmax(), fr, auto-fill / auto-fit, spans and line placement.
  • Tables: columns are as wide as their widest content and line up across rows; a table with an auto width shrinks to its columns (up to its container), like a browser's auto layout. table-layout: fixed takes the first row's widths. colspan, border-spacing, border-collapse, caption-side and empty-cells apply.
  • Positioning: relative, absolute, fixed (laid out like absolute, placed against the window), inset properties, z-index for painting and hit testing, and every 2D transform (translate, scale, rotate, skew, matrix, transform-origin, the individual rotate / scale / translate properties).
  • Bidirectional text: Hebrew and Arabic runs are reordered inside left-to-right text (a compact Unicode Bidirectional Algorithm), direction: rtl and unicode-bidi: bidi-override apply.
  • Scroll snapping: scroll-snap-type (x / y / both, mandatory / proximity) and scroll-snap-align on the children.
  • Overflow: hidden / clip clip, scroll / auto scroll with the wheel (Shift for horizontal) and show overlay scrollbars.
  • Lists: list-style-type (disc, circle, square, decimal, lower-alpha, upper-roman ...), list-style-position, <ol start>.
  • <details> / <summary>: clicking the summary toggles the details (.open(true) sets the initial state); <dialog> shows with .open(true).

Form controls

Outside styled, form elements look and behave like Chrome's (its colors and shapes, typed number fields with spin buttons, a range thumb that jumps to the click). Inside styled, and as the capitalized Blender components, they are Blender's widgets, with Blender's interaction (drag to scrub numbers, Ctrl+Z, double-click to type, Escape to cancel):

HTML Blender widget ChangeEvent
button() with text, input().input_type("submit" | "button" | "reset") button on_click
input(): text, password (masked), email, search, url, tel, date ... text field value
input().input_type("number") number field number, value
input().input_type("range") slider number, value
input().input_type("checkbox") checkbox checked
input().input_type("radio") (grouped by name) radio button checked
input().input_type("color") color swatch (opens Blender's picker) value as #rrggbb
select() with option() / optgroup() dropdown menu number (index), value (text)
textarea() multi-line text editor value
progress(), meter() progress bar (display only)

on_input and on_change both fire when the value changes. Values you pass (.value(..), .checked(..)) are pushed to the widget only when they change between renders, so a field the user is typing in is not reset; bind it to your state (as in the todo example) to control it. A button() holding elements other than text is laid out as an ordinary box (style it with CSS) and still gets on_click.

Events

Listener Event Bubbles
on_click ClickEvent { down, up } (press and release on the element) yes
on_mouse_down(button, ..), on_any_mouse_down MouseDownEvent { button, position, modifiers, click_count } yes
on_mouse_up(button, ..) MouseUpEvent yes
on_mouse_move MouseMoveEvent { position, pressed_button, modifiers } yes
on_hover bool: entered / left no
on_scroll_wheel ScrollWheelEvent { position, delta, modifiers } yes
on_key_down, on_key_up KeyDownEvent { keystroke: Keystroke { key, key_char, modifiers } } yes (from the focused element)
on_change, on_input ChangeEvent { value, checked, number } yes

Positions are logical pixels. Clicking an element focuses it; key events go to the focused element and bubble up. cx.stop_propagation() stops bubbling.

Selecting text

Text in elements is selectable like on a web page: press and drag (across words, lines, elements and paragraphs), double-click a word, triple-click a block, Shift+click to extend, Ctrl+A for all, Ctrl+C to copy (Cmd on macOS), Esc or a click on empty space to clear. The highlight is the theme's selection color; over selectable text the pointer is the I-beam unless an element sets its own cursor. A drag that selected text is not a click. user-select: none | auto | text | all (and select-none, select-auto, select-text, select-all; -webkit-user-select is an alias) decides what takes part: none is skipped and a press on it starts nothing, all is taken whole by one click, auto follows the parent as in CSS UI 4. Block boundaries are newlines in the copied text and whitespace is as rendered. Text fields and the other form controls keep their own selection and keys; canvases and the painted lists (vlist, chat_list) are not selectable, and a drag does not autoscroll.

On the Window (listeners get it): selected_text() -> Option<String>, select_all(), clear_selection(), on_selection_change(|text, window, app| ..) (fires for the user's changes) and read_clipboard() / write_clipboard(text). examples/selectable.rs is a page of paragraphs; tests/selection.rs drives it headlessly with simulate_drag, simulate_click and simulate_key_with.

Images

<img src> and CSS background images read every format the kit reads (PNG, JPEG, WebP, GIF, BMP, TGA, QOI, Radiance HDR, PNM, SVG). Layout takes the size from the file's header; the pixels decode on the kit's worker threads at the size drawn and the image appears when ready (App::draw waits for them, so headless pixels are deterministic). Image::open / Image::decode decode synchronously, Painter::image_file / image_file_cover draw a file in a canvas, CellRender::Image is a data-table image column and Record::media a chat message's picture. blenderui::image_stats() and set_image_budget see and size the shared cache. Animated GIF and WebP play (paused while off screen); <img frame="2"> holds a frame, set_reduced_motion(true) holds them all, and Animation steps one yourself (Image::update_texture for Dear ImGui). See Images.

<video src="intro.mp4" loop poster="intro.jpg" /> plays a video file (autoplay with sound, muted for a silent one; autoplay="false" holds the first frame; an element that leaves the tree stops its sound): the OS decodes it at the size drawn, only while it shows. Keep a blenderui::Video to control it (play, pause, seek, set_rate, time, duration, on_state) and pass it with video().video(rc.clone()) or Painter::video. Cargo features (png, jpeg, video, gpu, ... from features.json, all default) drop what an app doesn't use. See Video.

Painting your own content

canvas(|bounds, painter| ..) is gpui's canvas(): it paints with a Painter in logical pixels, clipped to its box.

canvas(|b, p| {
    p.fill(b, rgb(0x232323));
    p.quad(b, 6.0, rgba(0x4772b380), rgb(0x4772b3), 1.0);       // rounded rect + border
    p.line(&[(b.origin.x, b.origin.y), (b.origin.x + 80.0, b.origin.y + 40.0)], white(), 2.0);
    p.oval(Bounds { origin: point(10.0, 10.0), size: size(20.0, 20.0) }, red(), black(), 1.0);
    p.text(b.origin.x + 4.0, b.origin.y + 4.0, "hello", 13.0, white());
})
.w(px(200.0)).h(px(100.0))

Painter also has polygon, arc (pie slices), image (scaled) and with_clip. Images: img().src("file.png") (PNG, decoded once and cached) or img().image_rgba(w, h, pixels).

Data tables and long lists

DataTable is a virtualized table with the API of gpui-component's, drawn the way Blender draws its spreadsheet editor (space_spreadsheet): fixed row height, first_row = scroll_y / row_height, only the visible rows and the columns that intersect the region, drawn straight into the painter. A frame costs O(visible cells) at any row count, allocates nothing in its own drawing, and sorting or filtering produces a row index list (Blender's IndexMask) without copying data.

use blenderui::table::{Column, DataTable, TableDelegate, TableState};

impl CellSource for People {
    fn cell(&self, row: usize, col: usize) -> Cell<'_> { Cell::U64(row as u64) } // called for visible cells only
}
impl TableDelegate for People {
    fn columns_count(&self, _: &App) -> usize { 2 }
    fn rows_count(&self, _: &App) -> usize { 1_000_000 }
    fn column(&self, ix: usize, _: &App) -> Column { Column::new("id", "ID").sortable().fixed_left() }
}
let table = cx.new(|cx| TableState::new(People, window, cx));
// in render: DataTable::new(&table).stripe(true).on_select(|row, _, _| ...)

Features: sticky header and pinned columns, resize and move by dragging headers, click to sort, row (multi, Shift/Ctrl, Ctrl+A), cell and column selection, keyboard navigation, Ctrl+C as TSV, stripes, a row-number column, loading and empty states, load_more, Blender dark and light themes. The logic lives once, in the dependency-free blenderui-table crate (visible-range math and column culling, index masks and typed parallel sorts, lazy typed cells formatted without allocation, selection, keyboard navigation, column layout, a text-run cache, and the painting through a PaintSink trait). blenderui's table module is one adapter around it (Host, PaintSink, element); bindings/rust/blenderui-table-gpui is the same for real gpui, with gpui-component's names and a render_td escape hatch, outside the main workspace (it builds gpui). On real gpui, 1,000,000 x 20, it takes 1.45 ms per scrolled frame against gpui-component 0.9.0's 4.75 ms (see the website page "Data tables" for the method). uniform_list(id, count, |range, window, cx| ...) (gpui's signature) builds only the visible items of a list of real elements, from the same range math. Measured on 1,000,000 x 20: 0.1 ms to build, 1.1 ms per scrolled frame, about 22 ms for a header-click sort; see examples/bench_table.rs and the website page "Data tables". Not built yet in blenderui: element cells (render_td, available on gpui), a popup context menu, multi-cell ranges, JavaScript and Python wrappers.

The shadcn Data Table

blenderui::shadcn puts the API of shadcn/ui's Data Table (TanStack Table's ColumnDef, table state and row models) on the same painted table, in rsx! and builder syntax: <DataTable columns={columns} data={data} /> / DataTable::new(columns, data), ColumnDef::accessor_key / accessor_fn (the row type implements Record), select_column() and actions_column(), use_table(), and the helper components DataTableColumnHeader, DataTablePagination, DataTableViewOptions and DataTableToolbar. Sorting, column and global filters, pagination, row selection and column visibility are TanStack's state, uncontrolled or controlled with on_..._change callbacks, over row models that are index lists. A shadcn cell: ({ row }) => <JSX /> becomes a typed CellRender (text with a number format, checkbox, badge, progress, row actions) that the table paints straight from the data, so a steady frame still allocates nothing; there is no flexRender. The logic is in blenderui_table::tanstack (core, no framework); the components are in blenderui/src/shadcn/. Names, limits and numbers are on the website page "shadcn Data Table", and examples/site_shadcn_table.rs is the payments table of the recipe.

Variable-height lists

blenderui::vlist is a virtualized view for any app (feeds, logs, file lists, cards, chats) whose items have different heights (wrapped text, images), optimal from 100 items to 10M and beyond with one design. BUI keeps the engine; an app writes its own items on the public API, and the chat (ChatStyle) is one shipped look. The logic lives once, in the dependency-free blenderui-vlist crate (on blenderui-paint, which also holds the PaintSink trait, the theme Palette and the bounded TextCache that blenderui-table uses):

  • HeightIndex: blocks of up to 1024 items under a Fenwick tree with spare slots on both sides. A block is Uniform (a count and a height), Estimated (a count and the text bytes it holds; nothing per item) or Measured (u32 prefix sums, 1/64 px, plus an exactness bit per item). A list of one block skips the tree. Offset to item and item to offset are O(log blocks) plus a binary search in a block; a height change is O(log blocks); adding or prepending a page adds blocks without shifting. Heights are fixed-point integers, so ten million rows of 60 px stay exact. Memory follows what was scrolled through.
  • Anchor-based scrolling (ListView): the position is (item, offset inside it), or the end of the list (stick_to_bottom, open at the newest item). Heights changing above the viewport, prepended history and edits can't move what is on screen; resize keeps the reader's place; jump_to re-aims until the target is measured; the scrollbar thumb comes from the estimate (Estimator, calibrated by every measurement).
  • Measuring (Measurer, TextLayout): Blender's textview_wrap_offsets in pixels, with an ASCII advance table, cached per (text, width, size), a per-frame time budget while flinging (unmeasured items draw as skeletons), idle prefetch in the scroll direction, and image heights carried in the record.
  • Sources (ItemSource): VecSource and log::LogSource, a file-backed append-only log (16-byte records plus a text arena, positioned reads), so 10M messages need a few MB of RAM; ensure_loaded and cancel for asynchronous loading.
use blenderui::vlist::{chat_list, synth, theme_palette, ChatList, ListState, Options};

let opts = Options { start_at_end: true, ..Options::default() };
let chat = cx.new(|cx| ListState::new(ChatList::from_messages(synth::messages(0, 1_000_000), theme_palette(), 760.0, 436.0, opts), cx));
// in render: chat_list(&chat)            // click selects a whole message
// elsewhere: chat.update(cx, |s, _| s.push(message));   // follows while at the bottom

For items that are not messages, build a List from your own ItemSource, Measurer and ItemPainter and show it with variable_list(&state). A Record carries an id, time and sender values and flags bits (FLAG_PLACEHOLDER is the engine's, FLAG_USER << n is free), text, an image and opaque data bytes your look decodes (stored in the page's buffer, no allocation per item); ItemPainter::hit returns an item-local part id for a press, delivered by VariableList::on_item_hit(|item, part, list| ..) next to on_item_click; Measurer::estimator has a default. Everything a look needs (PaintSink, Palette, Rect, Rgba, Lines, Record, ...) is re-exported from blenderui::vlist. Items are painted, not elements: no buttons or text fields inside an item. examples/vlist_cards.rs is a non-chat feed of task cards and tests/vlist_custom.rs runs a custom look headlessly. bindings/rust/blenderui-vlist-gpui is the same list for real gpui (outside the main workspace); its benchmark against gpui's list and gpui-component's virtual_list is in bench/. Measured numbers and the method are on the website page "Variable-height lists". Not built yet: selecting text across messages, a background measuring thread, damage regions, JavaScript and Python wrappers.

blenderui::shadcn also has VirtualList (count and an item closure that writes each item's text, so ten million rows cost a screenful) and ChatList, with TanStack Virtual's names: estimate_size, overscan, get_item_key, on_range_change, and scroll_to_index / scroll_to_offset / measure_element on the ListHandle that use_virtual_list() returns. They sit on ListState and ItemSource (the new CountSource and RowStyle in blenderui-vlist), so the file-backed source works under them. See the website page "Virtual list API" and examples/site_shadcn_list.rs.

Headless rendering and tests

Application::headless() runs the same code without a native window (and is what you get on platforms without one). Drive it from the run closure:

Application::headless().run(|cx| {
    let win = cx.open_window(WindowOptions::default(), |_, cx| cx.new(|_| Counter { count: 0 }))
        .unwrap();
    let b = cx.element_bounds(win.id, "plus").unwrap();         // the element with .id("plus")
    cx.simulate_click(win.id, b.origin.x + 2.0, b.origin.y + 2.0);
    assert_eq!(win.root().read(cx).count, 1);
    let (w, h, pixels) = cx.draw(win.id);                       // 0x00RRGGBB, device pixels
});

Also simulate_mouse_move, simulate_scroll, simulate_key(text, keysym), simulate_key_with (Ctrl, Shift), simulate_click_with, and simulate_press, simulate_release and simulate_drag(from, to) for a held button. The kit has global state, so one Application runs at a time per process (run takes a lock; parallel tests queue up).

Coverage

From cargo test --test parity -- --nocapture:

Area Coverage
HTML elements (WHATWG index) 113 / 113 constructible, plus svg / math roots; 9 are Blender widgets
CSS properties 275 change layout or rendering; 135 more parse but have no effect
W3C property index (745 properties) 261 rendered (35%), 129 parsed without effect (17%), 355 not recognized (48%): most of these are drafts, speech, paged media and SVG
CSS 2.1, screen properties 90 / 90 rendered, 90 / 90 parsed
Flexbox 12 / 12
Grid 23 / 23 (including grid-template-areas and named lines)
Tailwind CSS v4 Classes compile on first use (v4 theme, variants, arbitrary values); tw! checks them at compile time

Beyond properties, the engine supports:

  • Values: every CSS math function (calc, min, max, clamp, round, mod, rem, trigonometry, pow, hypot ...) with mixed units, every length unit, and var() / env().
  • Colors: CSS Color 4/5: oklch, lab, color(), color-mix(), relative colors and light-dark().
  • Selectors: Selectors Level 4 (:has(), :is(), :where(), :nth-child(of S) ...), nesting, and ::before / ::after with content.
  • At-rules: @media (Media Queries 4 ranges), @supports, @layer and @scope.
div().class(tw!("grid grid-cols-3 gap-4 md:grid-cols-6 hover:bg-sky-500/50"))
div().style("width: calc(100% - 2 * var(--gap)); background: color-mix(in oklch, var(--brand) 60%, white)")

Every CSS 2.1 screen property renders.

Effects work on the element's pixels: filter and backdrop-filter (blur, brightness, contrast, grayscale, hue-rotate, invert, opacity, saturate, sepia, drop-shadow), mix-blend-mode (all 16 modes and plus-lighter), clip-path (inset(), circle(), ellipse(), polygon(), reference boxes), mask / mask-image (gradients and PNGs, alpha or luminance, with size, position and repeat) and rotate / skew / scale / matrix transforms. The element's subtree is drawn offscreen with the canvas' own drawing code, filtered, clipped, masked and resampled (bilinear, like Blender's image transform), then composited back with the W3C formulas; the result is cached, so a page that doesn't change costs nothing. border-image (gradients and PNGs, slice, width, outset, stretch / repeat / round / space, fill) draws the nine slices.

Also rendered: every border-style and outline-style (dashed, dotted, double, groove, ridge, inset, outset, following rounded corners with Blender's corner tessellation), text-decoration-style (including wavy), -thickness and text-underline-offset, background-clip / background-origin (border-box, padding-box, content-box), background-attachment: fixed, clip: rect() on absolutely positioned boxes, counters (counter-reset / -increment / -set with counter() and counters() in content), empty-cells, list-style-image, word-break: break-all, overflow-wrap: anywhere | break-word and tab-size.

Also supported: background-image: url() (every image format) with background-size / -position (-x / -y) / -repeat, object-fit / object-position, logical border longhands (border-inline-width ...), text-wrap-mode, white-space-collapse, scale, @container size queries (container-type, container-name), @font-face (local font files) and @property initial values.

How much is left, against all 745 properties in the W3C index:

Properties Share
Change layout or rendering 261 35%
Parsed, no effect yet 129 17%
Not recognized 355 48%

The 355 unrecognized properties break down as:

Group Properties
Draft border and corner shapes (corner-shape, border-*-clip ...) ~78
SVG fill, stroke and markers ~40
Gap decorations (row-rule-* ...) 38
Speech and aural 31
Animation triggers and scroll-driven animation 26
Paged media, regions, rhythm and others ~25
Everything else ~100

The everyday screen CSS is much further along: Flexbox 12/12, Grid 23/23 and CSS 2.1 90/90. The largest remaining gaps among common properties are 3D transforms, OpenType font features and multi-column layout.

Animations and transitions run like a browser's: @keyframes (percent lists, from / to, inside @media, per-keyframe animation-timing-function), every animation-* longhand and the shorthand (lists of animations, negative delays, infinite, every direction, fill mode and play state), and transition / transition-* (all or property lists, transition-behavior: allow-discrete; an interrupted transition starts from its current value, and one sent back to where it came from takes only as long as it ran). Easing: linear, ease*, cubic-bezier(), steps() with every jump position, step-start / -end and linear() points. Lengths, percentages, numbers, colors (in premultiplied sRGB), box-shadow, text-shadow, transform (function by function), rotate, scale, filter / backdrop-filter (function by function), visibility and z-index interpolate; other properties flip at 50%. A window renders frames only while something moves: finished or paused animations cost no CPU. Headless windows run on a virtual clock that App::advance_clock moves, so tests step animations exactly.

Not done yet:

  • Parsed, not applied: OpenType font features (font-feature-settings, font-variant-numeric ...): the text engine has no shaping, and Blender's text library doesn't either. Multi-column layout (columns), writing-mode, scroll-padding / scroll-margin.
  • 3D transforms: perspective, rotateX / rotateY, matrix3d have no effect; 2D transforms don't change hit testing (clicks use the untransformed box).
  • Animations: no animationend / transitionend events, no animations on ::before / ::after, and an element starts transitions only when it already had a transition in the previous frame (e.g. not when transition appears only under :hover on the first hover). Lengths mixing units that resolve differently (50% to 100px, auto) flip at 50% instead of going through calc().
  • @container timing: queries use the container's size from the previous layout; when it changes, the window renders once more.
  • Effects: filter: url(#svg), clip-path: path(), and mix-blend-mode across stacking contexts (it blends with what was painted before it).
  • The rest of the W3C property index: 355 entries this engine doesn't know, mostly drafts, speech, paged media and SVG.
  • all: counted as parsed-only. Its CSS-wide keywords (all: initial, inherit, unset, revert) reset an element's computed style; there's nothing else it can take.
  • Box sizing: the default is border-box (like Tailwind's preflight), not CSS's content-box.

GPU effects

A canvas can run your own pixel shader on the GPU: ShaderEffect::new(name, glsl_source, n_inputs, n_floats) declares it, painter.effect(bounds, &effect, &texture_ids, &floats, Some(&fallback_image)) draws it in paint order, and effect.error() returns the compile log. The source is GLSL with a small compat set (vec4 effect(vec2 p), box_size, U[i], input_color(i, texel)), compiled at run time by Direct3D 11 and OpenGL; the software renderer draws the fallback. See GPU effects and examples/gpu_effect.rs.

Performance vs gpui

The same UI on blenderui (GPU renderer and default software raster), gpui-fast 0.1.13 and gpui 0.2.2: a window of N rounded, labelled cells that all change every frame. Ryzen 7 5800U laptop at 60 Hz, all apps back to back in one session. bindings/rust/bench has the full table and how to re-run it.

blenderui GPU blenderui CPU gpui-fast gpui
1000 / 3000 animated cells 60 / 59.9 fps 60 / 57.6 fps 49.2 / 31.5 fps 36.4 / 19.9 fps
CPU per frame, 100 / 1000 / 3000 cells 1.2 / 4.7 / 11.6 ms 4.6 / 10.2 / 22.0 ms 2.7 / 20.5 / 31.9 ms + GPU 4.7 / 27.7 / 50.5 ms + GPU
RAM (working set) 28-40 MB + 19-22 MB GPU 21-30 MB, no GPU 45-65 MB + 19-24 MB GPU 40-77 MB + 16-21 MB GPU
First frame after launch ~5 ms ~5 ms ~200 ms ~220 ms
Idle CPU 0 % 0-0.9 % 0-0.4 % 0.9-1.4 %

The GPU renderer

Application::new().gpu(true).run(|cx| { /* every window on the GPU */ });
// or one window:
cx.open_window(WindowOptions { gpu: Some(true), ..Default::default() }, build);
// window.is_gpu() turns true a few frames in, once the device is ready

BUI_GPU=1 / 0 overrides both. It is Direct3D 11 on Windows and OpenGL 3.3 on Linux. Elsewhere, or without a device, windows stay on the software raster. Every primitive becomes one instance of a single shader, following Blender's instanced widget-base batches. Text runs and images are cached in atlases. Frames render into a persistent target, so only damaged regions redraw. Both renderers produce the same pixels (the gpu_parity test).

The software raster draws in parallel bands (BUI_RASTER_THREADS=1 forces one thread). BUI_PROFILE=1 prints per-phase frame times for either renderer.

Text

Text uses Blender's UI font, Inter, embedded in the library, so it looks the same on every platform. The default family (and sans-serif, system-ui or an unknown family) is Inter. Named families such as "Segoe UI" or monospace load from the platform's fonts. BUI_FONT=path.ttf overrides the default face, and you can register more faces:

blenderui::add_font("Brand", false, false, include_bytes!("Brand-Regular.ttf"));

With .gpu(true), glyphs are drawn straight from their outlines using Eric Lengyel's Slug algorithm: one quad per glyph, exact coverage computed in the pixel shader, and no glyph bitmaps. The alternative is a per-glyph bitmap atlas (Blender's approach): about half the GPU work, but bitmaps per size. Choose with:

Slug (default) Glyph atlas
Build time slug feature (default) default-features = false
Run time Application::new().slug(true) / blenderui::set_slug(true) .slug(false) / set_slug(false)
Environment (overrides) BUI_SLUG=1 BUI_SLUG=0

The gdi-text feature uses Windows' GDI engine and system fonts.

Limitations

  • Floats place block boxes, but text does not wrap around them. Right-to-left text is reordered (bidi) but not shaped (no Arabic joining).
  • Fonts: font-family picks a face per element (registered, @font-face, installed or generic monospace / serif); there is no per-glyph fallback between faces of a list.
  • Effects and animation: see "Not done yet" under Coverage.
  • Transforms: every 2D transform draws, but hit testing uses the untransformed box; 3D transforms have no effect.
  • Inline boxes paint their background per word; borders and padding on inline elements (<kbd>, <code>) are not drawn.
  • Widgets draw above page content, so a z-indexed box (a <dialog>) over a form field does not cover the field.
  • Images: an animation inside a CSS effect layer (filters, masks, 3D transforms) shows its first frame. video, audio, iframe show a placeholder.
  • Windows are native on Windows (Win32), Linux (X11) and macOS (Cocoa, new, tried by hand so far on three Macs (two Apple Silicon, one Intel); it needs the main thread). The GPU renderer runs on Windows and Linux.
  • text-align: justify aligns left. Table columns are sized from their widest single-line content, a simpler version of browsers' auto layout.

How it works

 Render::render ─► element tree (one Div type for every tag)
        │
  cascade: UA sheet ▸ <style> sheets ▸ inline ▸ :hover/:active/:focus ▸ !important
        │          one handler table applies every property
  box tree: blocks, line boxes of words, flex/grid items, tables as flex
        │
  taffy layout ─► absolute boxes, clips, scroll offsets
        │
  paint ─► one display list on a kit canvas      form controls ─► kit widget nodes,
        │  (rects, rounded rects, text, images)                 placed at their boxes
        ▼
  C kit: input, hit testing, Blender widget drawing, damage rendering, Win32 / X11 window
  • blenderui-sys is the raw FFI over kit/include/BUI_kit.h; its build script builds the C kit with CMake and links it statically.
  • Every style source (methods, css!, .css, .style, sheets, the user-agent sheet, state refinements) becomes CSS declarations applied by one table of property handlers, so a property has exactly one implementation.
  • Compile time: the property table is a const. Style methods and css! resolve property names to indices when the program compiles (a typo is a compile error), typed methods (.w(px(40.0)), .bg(rgb(..))) build their value token directly, and fixed values (.flex(), .shadow_md(), css! values) are tokenized once per program.
  • No Rc / RefCell: a frame is a set of flat arenas (boxes, element data, taffy nodes) linked by index, owned by the window and reused every frame. Computed styles live in a per-window store, shared by every element with the same inputs. Listeners are owned Boxes; while one runs, the frame is moved out of the window so it can take &mut Window. Entities are Copy handles into an app-owned slot map; the app itself lives on Application::run's stack. Small per-element lists (matched rules, declarations) stay on the stack. The only shared ownership left is Arc<Image> for image pixels.
  • Reuse across frames: render() builds a fresh element tree each frame, but the work behind it is reused. Matched selectors are memoized by an element fingerprint (what selectors can see: tag, id, attributes, position, state, ancestors, previous siblings). Computed styles are shared by input. The taffy tree persists and is reconciled by key, so only changed subtrees are laid out again. Widget nodes are reconciled by key too.
  • Rendering happens on the next turn of the native message loop after events.