Home /Modules/ui/LAYOUT.md

LAYOUT.md

lib/ui/LAYOUT.md · 201 line(s) · markdown

The Standard UI Layout family (lib/ui)

A small, consistent, professional set of layout classes designed for people of all skill levels. The canonical definitions live here in lib/ui and are usable from anywhere in /lib (including lib/user-interface and lib/gui) — class names are global in /lib, so they are defined in exactly one place to stay unambiguous.

Every class is pure SLeeLa (no native handle required), computes real device-pixel rectangles into SLLayoutBox[], carries the Metadata Class metapattern, and checks + runs on the stock compiler.

The family

ClassWhat it doesEasiest call
SLLayoutBoxone computed rectangle (x, y, w, h) — the shared output unitb.describe()
SLStackLayouta single row or column (the 90% case); add(0) = flexibles.column(); s.add(40); s.add(0); s.arrange(...)
SLGridLayoutan evenly divided rows × cols gridg.columns(3); g.add(); g.arrange(...)
SLDockLayoutdock to edges (top/bottom/left/right) + one fill() centred.top(32); d.fill(); d.arrange(...)
SLAbsoluteLayoutpixel-exact x/y/w/h placementa.add(10,10,120,24); a.arrange(...)
SLLayoutKitbeginner-first facade — one call returns the right layoutkit.column(8,12) / kit.grid(3,10,10) / kit.dock()
SLLayoutFramethe organizing root — owns a layout + named components; every component is placed in reference to the Framef.useColumn(8,12); f.add("body",0); f.place(...)

The Frame organizes (components in reference to the basic UI interface)

A Frame is the basic UI interface and the organizing root: it owns one layout and a set of named components, and every component exists in excellent reference to the Frame — its rectangle is computed by the Frame's layout and measured from the Frame's own origin. Add components by name, place the Frame once, and read each component's rectangle back by name.

SLLayoutFrame f = new SLLayoutFrame(); f.create();
f.title("Settings");
f.useColumn(8, 12);          < the Frame's layout: a padded vertical stack >
f.add("header", 40);         < a 40px component >
f.add("body",   0);          < flexible: fills the rest >
f.add("footer", 32);
f.place(0, 0, 320, 600);     < the Frame's own rectangle; children arrange to it >

SLLayoutBox body = f.boxOf("body");   < that component's rect, relative to the Frame >

Choose the Frame's layout with useColumn / useRow / useGrid. The Frame is where components live; the layout is how they are arranged within it.

For beginners (start here)

SLLayoutKit kit = new SLLayoutKit(); kit.create();

< a vertical page: a 40px header, then a body that fills the rest >
SLStackLayout page = kit.column(8, 12);   < gap 8, padding 12 >
page.add(40);        < header, fixed >
page.add(0);         < body, flexible (0 = share the leftover space) >
page.arrange(0, 0, 360, 640);

SLLayoutBox header = page.boxOf(0);
SLLayoutBox body   = page.boxOf(1);

For professionals

Use the concrete classes directly for full control (grid columns, dock order, exact rects). Every layout validates its inputs (clamps negatives, bounds gaps) and exposes honored() for a consistency re-check. Sizes flow in device pixels; pair with SLMeasure (unit conversion) when you need physical/relative units.

Relationship to the other layout surfaces

The standard family is the recommended default for everyday placement.

Driving real native widgets (SLLayoutDriver)

The Standard Layouts are the planning layer: pure SLeeLa that computes the exact pixel rectangle of every component (SLLayoutFrame + the SL*Layout family). SLLayoutDriver is the realizing layer: it takes a placed SLLayoutFrame and configures live SleelaUI widgets through the ui* bridge so the real, on-screen toolkit reproduces the plan.

Why it is faithful, not lossy

SleelaUI — like GTK or Qt layouts — is a container/pack model: you declare structure (a box with an orientation and spacing, or a grid of N columns) and the toolkit solves geometry on every backend (X11 / Cocoa / Win32). There is no "place this widget at absolute x,y" call, by design, so a view stays correct when the window resizes. The Standard stack and grid layouts use that same model, so realizing them is exact:

Plan (SLLayoutFrame)Realized native container
useColumn(gap, pad)uiBox(parent, 0 /*vertical*/, gap)
useRow(gap, pad)uiBox(parent, 1 /*horizontal*/, gap)
useGrid(cols, gap, pad)uiGrid(parent, cols, gap)

Each real control is sized from the plan with uiWidgetSizeRequest(w, h), and a flexible component (added with size 0) is marked uiWidgetExpand + uiWidgetAlign(FILL, FILL) so it shares the leftover space exactly as the planner computed.

Usage

< 1. PLAN in pure SLeeLa (always checks and runs, headless included) >
SLLayoutFrame f = new SLLayoutFrame(); f.create();
f.useColumn(8, 12);
f.add("header", 40);     < fixed 40px >
f.add("body",   0);      < flexible: fills the rest >
f.add("footer", 32);     < fixed 32px >
f.place(0, 0, 320, 600);

< 2. REALIZE onto a real window root (needs a display) >
SLLayoutDriver d = new SLLayoutDriver(); d.create();
int box = d.realize(root, f);         < one uiBox matching the plan >

int header = uiLabel(box, "Settings");
d.applyNamed(f, "header", header);    < sized from the plan >

int body = uiScrolledView(box, 1, 1);
d.applyNamed(f, "body", body);        < flexible -> expands to fill >

int footer = uiButton(box, "Close");
d.applyNamed(f, "footer", footer);

SLLayoutDriver is native, bridge-backed (it calls ui*), so unlike the pure planners it runs only where a display/toolkit is present. The runnable demo lib/ui/layout-driver-demo.sleela shows the full flow and degrades gracefully on a headless host (it prints the computed plan and exits).

Reading the plan from a realizer

SLLayoutFrame now exposes its plan so any realizer (or inspector) can read it: getLayoutKind(), isRowLayout(), getGap(), getColumns(), and isFlexibleAt(index), alongside the existing boxAt(index) / boxOf(name) rectangles. The underlying SLStackLayout gained getGap() and isFlexibleAt(index); SLGridLayout gained getGap().

Describing a component's quality (SLComponentQuality)

A layout gives every component its exact size and pixel-perfect placement (SLLayoutBox: x/y/w/h). SLComponentQuality completes the picture with each component's quality, so a component is fully described by quality + size + placement.

Quality is expressed in the standard themes' own vocabulary, so it maps cleanly to a flavor (blue/gray/black/white) and to what the native toolkit can honor per widget:

Every component added to an SLLayoutFrame gets a default quality (body / normal / enabled) you can customize by name:

SLLayoutFrame f = new SLLayoutFrame(); f.create();
f.useColumn(8, 12);
f.add("title", 40);
f.add("list", 0);
f.add("save", 36);
f.place(0, 0, 320, 600);

f.qualityOf("title").asChrome();
f.qualityOf("list").asSurface();
f.qualityOf("save").asAccent(); f.qualityOf("save").primary();

< now fully described: quality + size + placement >
< e.g. "save" -> quality:accent/primary/enabled + [12,508 296x36] >

When realized by SLLayoutDriver, every honorable part is applied to the live widget, each mapping 1:1 to a real ui* bridge call: primary -> uiWidgetSuggested, danger -> uiWidgetDestructive, disable() -> uiWidgetSensitive, hide() -> uiWidgetVisible, a margin -> uiWidgetMargin, and an icon -> uiWidgetSetIcon. The role is a hint the themed renderer uses when drawing the surface (the toolkit has no per-widget surface call, so role is honored through the window theme).

lib/ui/verify-pixel-perfect.sleela is a runnable self-check (47 assertions) proving exact placement/size (column, row, grid) and the full quality descriptor (role + emphasis + interactivity + visibility + margin + icon).