SLLayoutFrame.sleela
lib/ui/SLLayoutFrame.sleela · 289 line(s) · sleela
<< lib/ui/SLLayoutFrame.sleela
SLeeLa Standard Library Definition.
Definition: SLLayoutFrame โ the basic UI interface and the organizing root.
A Frame is a named rectangle that owns ONE layout (any SL*Layout from the
standard family) and a set of named COMPONENTS. Every component exists in
excellent reference to the Frame: you add a component, the Frame hands it to
its layout, and place() gives each component its exact rectangle RELATIVE TO
the Frame. So the Frame organizes -- it is the place components live and the
origin they are measured from.
This is the pure-SLeeLa, beginner-first organizing Frame (no native handle; it
always checks and runs). It complements -- and is distinct from -- the native,
bridge-backed container lib/user-interface/SLFrame (which `extends SLWidget`
and bottoms out in `uiFrame`); that one is a drawn widget, this one is the
component-organizing root of the standard layout family.
Easy path (a Frame with a vertical layout and three named components):
SLLayoutFrame f = new SLLayoutFrame(); f.create();
f.title("Settings");
f.useColumn(8, 12); < give it a stack layout: gap 8, pad 12 >
f.add("header", 40); < a 40px component >
f.add("list", 0); < flexible: fills the rest >
f.add("footer", 32);
f.place(0, 0, 320, 600); < the Frame's own rectangle >
SLLayoutBox list = f.boxOf("list"); < that component's rect, vs the Frame >
>>
#sleela 2.5
material;
< Family: ui. The basic UI interface: the Frame that organizes components via a layout. >
class SLLayoutFrame {
< ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
<< Eleven catalogued attributes with getter/setter pairs. >>
String metaVersion = "1.0.0";
int metaId = 11607;
String metaAuthor = "Kiro Agent";
String metaDate = "2026-10-25";
String metaCopyright = "SLeeLa project";
String metaTrademark = "none";
String metaCorporation = "none";
< metaOrigin: National | <nation> | International | Galactic >
String metaOrigin = "International";
String metaBirthDate = "2026-10-25";
< metaScienceRating: maturity/robustness on a 1..10 scale >
int metaScienceRating = 8;
< metaNationalSchedule: a real, citable instrument or "none" >
String metaNationalSchedule = "none";
String getMetaVersion() { return metaVersion; }
void setMetaVersion(String v) { metaVersion = v; }
int getMetaId() { return metaId; }
void setMetaId(int v) { metaId = v; }
String getAuthor() { return metaAuthor; }
void setAuthor(String v) { metaAuthor = v; }
String getDate() { return metaDate; }
void setDate(String v) { metaDate = v; }
String getCopyright() { return metaCopyright; }
void setCopyright(String v) { metaCopyright = v; }
String getTrademark() { return metaTrademark; }
void setTrademark(String v) { metaTrademark = v; }
String getCorporation() { return metaCorporation; }
void setCorporation(String v) { metaCorporation = v; }
String getOrigin() { return metaOrigin; }
void setOrigin(String v) { metaOrigin = v; }
String getBirthDate() { return metaBirthDate; }
void setBirthDate(String v) { metaBirthDate = v; }
int getScienceRating() { return metaScienceRating; }
void setScienceRating(int v) { metaScienceRating = v; }
String getNationalSchedule() { return metaNationalSchedule; }
void setNationalSchedule(String v) { metaNationalSchedule = v; }
< which standard layout governs this Frame's children >
static final int LAYOUT_STACK = 0;
static final int LAYOUT_GRID = 1;
static final int MAX_COMPONENTS = 128;
< A Frame never opens smaller than this, no matter how few components it has: >
< the absolute assumed floor for a usable starting window. >
static final int MIN_FRAME_W = 160;
static final int MIN_FRAME_H = 120;
< presentation mode: NORMAL uses the assumed/explicit size; FULLSCREEN fills >
< the supplied screen rectangle. >
static final int MODE_NORMAL = 0;
static final int MODE_FULLSCREEN = 1;
String frameTitle;
int kind;
< the Frame's own rectangle (origin + size), set by place() >
int fx; int fy; int fw; int fh;
< the governing layout (exactly one; chosen by a useXxx() call) >
SLStackLayout stack;
SLGridLayout grid;
< the named components the Frame organizes, in add order >
String[] names;
< each component's quality (role + emphasis + interactivity), parallel to names >
SLComponentQuality[] qualities;
int count;
< 1 once place() has arranged the layout >
int placed;
< presentation mode: MODE_NORMAL or MODE_FULLSCREEN, set by how it was placed >
int mode;
void create() {
frameTitle = "";
kind = LAYOUT_STACK;
fx = 0; fy = 0; fw = 0; fh = 0;
stack = new SLStackLayout(); stack.create();
grid = null;
names = new String[MAX_COMPONENTS];
qualities = new SLComponentQuality[MAX_COMPONENTS];
count = 0;
placed = 0;
mode = MODE_NORMAL;
}
void title(String t) { if (t != null) { frameTitle = t; } }
String getTitle() { return frameTitle; }
< ---- choose the layout that organizes the components -------------------- >
< A vertical stack (gap, uniform padding). The 90% case. >
void useColumn(int gap, int pad) {
kind = LAYOUT_STACK;
stack = new SLStackLayout(); stack.create(); stack.column(); stack.gap(gap); stack.pad(pad);
grid = null;
}
< A horizontal stack. >
void useRow(int gap, int pad) {
kind = LAYOUT_STACK;
stack = new SLStackLayout(); stack.create(); stack.row(); stack.gap(gap); stack.pad(pad);
grid = null;
}
< A grid (columns, gap, uniform padding). >
void useGrid(int columns, int gap, int pad) {
kind = LAYOUT_GRID;
grid = new SLGridLayout(); grid.create(); grid.columns(columns); grid.gap(gap); grid.pad(pad);
}
< ---- add components (each referenced to the Frame through the layout) --- >
< Add a named component with a main-axis size (0 = flexible, stack only). The >
< Frame remembers the name and hands the size to its layout. Returns the >
< component's index, or -1 if the Frame is full. >
int add(String name, int sizePx) {
if (count >= MAX_COMPONENTS) { return -1; }
if (kind == LAYOUT_GRID) { grid.add(); }
else { stack.add(sizePx); }
names[count] = name;
SLComponentQuality q = new SLComponentQuality(); q.create();
qualities[count] = q;
int idx = count; count = count + 1;
return idx;
}
int size() { return count; }
< ---- per-component quality (role + emphasis + interactivity) ------------ >
< The quality descriptor for component `index` (never null for a valid >
< index; defaults to body/normal/enabled until the caller customizes it). >
SLComponentQuality qualityAt(int index) {
if (index < 0 || index >= count) { return null; }
return qualities[index];
}
< The quality descriptor for a named component, or null if unknown. >
SLComponentQuality qualityOf(String name) {
int idx = indexOf(name);
if (idx < 0) { return null; }
return qualities[idx];
}
< Replace a component's quality wholesale (ignored for an unknown index). >
void setQualityAt(int index, SLComponentQuality q) {
if (index < 0 || index >= count || q == null) { return; }
qualities[index] = q;
}
< the index of a named component, or -1 if the Frame never heard of it >
int indexOf(String name) {
if (name == null) { return -1; }
int i = 0;
while (i < count) { if (names[i] == name) { return i; } i = i + 1; }
return -1;
}
< ---- place the Frame, which arranges every component relative to it ----- >
void place(int x, int y, int w, int h) {
fx = x; fy = y;
fw = (w < 0) ? 0 : w; fh = (h < 0) ? 0 : h;
if (kind == LAYOUT_GRID) { grid.arrange(fx, fy, fw, fh); }
else { stack.arrange(fx, fy, fw, fh); }
mode = MODE_NORMAL;
placed = 1;
}
< ---- assumed size: how large this Frame must START, from its components -- >
<< The assumed minimum WIDTH for this Frame: the natural width of its
governing layout (derived from the components' sizes, gaps, and padding),
never less than MIN_FRAME_W. This is the "it has so many components so wide
that the starting size must be at least so large" rule, made explicit. >>
int assumedWidth() {
int nat = (kind == LAYOUT_GRID) ? grid.naturalWidth() : stack.naturalWidth();
return (nat < MIN_FRAME_W) ? MIN_FRAME_W : nat;
}
<< The assumed minimum HEIGHT for this Frame: the natural height of its
governing layout, never less than MIN_FRAME_H. >>
int assumedHeight() {
int nat = (kind == LAYOUT_GRID) ? grid.naturalHeight() : stack.naturalHeight();
return (nat < MIN_FRAME_H) ? MIN_FRAME_H : nat;
}
<< Place the Frame at `(x, y)` using its ASSUMED size โ the starting size
computed from the components it holds. This is the initialization sizing:
call it instead of place() when you want the Frame to open at least as
large as its contents require, without hand-computing a width/height. >>
void placeAssumed(int x, int y) {
place(x, y, assumedWidth(), assumedHeight());
}
<< Place the Frame FULL SCREEN: it fills the supplied screen rectangle
(`screenW` x `screenH` at `x, y`) rather than its assumed size. The screen
extent is supplied by the caller/host because this pure-SLeeLa Frame has no
native display handle to query; a native host passes its real screen size.
The Frame is never placed smaller than its assumed size, so a tiny screen
still shows every component. >>
void placeFullscreen(int x, int y, int screenW, int screenH) {
int w = (screenW < assumedWidth()) ? assumedWidth() : screenW;
int h = (screenH < assumedHeight()) ? assumedHeight() : screenH;
fx = x; fy = y; fw = w; fh = h;
if (kind == LAYOUT_GRID) { grid.arrange(fx, fy, fw, fh); }
else { stack.arrange(fx, fy, fw, fh); }
mode = MODE_FULLSCREEN;
placed = 1;
}
< True when this Frame was placed in full-screen mode. >
boolean isFullscreen() { return mode == MODE_FULLSCREEN; }
< The presentation mode: MODE_NORMAL or MODE_FULLSCREEN. >
int getMode() { return mode; }
<< To place the Frame FULL SCREEN at the host's REAL primary-display size,
discovered per-OS by the Ballum display subsystem, call
SLBallumScreenFit.fitFrame(frame, x, y) in lib/ballum. The screen-size
bridge lives on the Ballum side so this lib/ui package stays pure (no native
dependency); pass the real pixels to placeFullscreen(x, y, w, h) directly if
you already know them. >>
< ---- read a component's rectangle, in reference to the Frame ------------ >
SLLayoutBox boxOf(String name) {
int idx = indexOf(name);
if (idx < 0) { return null; }
if (kind == LAYOUT_GRID) { return grid.boxOf(idx); }
return stack.boxOf(idx);
}
SLLayoutBox boxAt(int index) {
if (index < 0 || index >= count) { return null; }
if (kind == LAYOUT_GRID) { return grid.boxOf(index); }
return stack.boxOf(index);
}
< ---- read the plan (for a native realizer such as SLLayoutDriver) ------- >
< Which standard layout governs this Frame: LAYOUT_STACK or LAYOUT_GRID. >
int getLayoutKind() { return kind; }
< True when the governing layout is a horizontal row stack. >
boolean isRowLayout() { return kind == LAYOUT_STACK && stack != null && stack.isRow(); }
< The gap (px) the governing layout uses between adjacent children/cells. >
int getGap() {
if (kind == LAYOUT_GRID) { return (grid == null) ? 0 : grid.getGap(); }
return (stack == null) ? 0 : stack.getGap();
}
< The column count for a grid Frame (1 for a stack Frame). >
int getColumns() {
if (kind == LAYOUT_GRID && grid != null) { return grid.getColumns(); }
return 1;
}
< True if component `index` is flexible (stack size 0). Grid cells are never >
< flexible here โ the grid sizes its own cells. >
boolean isFlexibleAt(int index) {
if (kind == LAYOUT_GRID) { return false; }
return (stack != null) && stack.isFlexibleAt(index);
}
< the Frame's own rectangle, for a host to draw its border/title >
int getX() { return fx; }
int getY() { return fy; }
int getWidth() { return fw; }
int getHeight() { return fh; }
boolean isPlaced() { return placed == 1; }
boolean honored() {
boolean kindOk = kind == LAYOUT_STACK || kind == LAYOUT_GRID;
boolean lay = (kind == LAYOUT_GRID) ? grid.honored() : stack.honored();
boolean modeOk = mode == MODE_NORMAL || mode == MODE_FULLSCREEN;
return kindOk && lay && modeOk && count >= 0 && count <= MAX_COMPONENTS && fw >= 0 && fh >= 0;
}
}