Home /Modules/user-interface/README.md

README.md

lib/user-interface/example/README.md · 258 line(s) · markdown

/example — worked, runnable SLeeLa examples

This folder holds hands-on, self-contained starting points you can read, run, and adapt. It now covers three things:

  1. One GUI example per lib/gui version line — the full spread of known UI lines, from the 1.0 baseline to the 5.0 military build. Each one renders a real, on-screen window through SleelaUI (SLeeLa's own native C/C++ toolkit) via the ui* SLVM bridge, and each is now interactive: the buttons actually function. Instead of calling the toolkit's own uiAppRun() (which just waits for the window to close), each example runs its own event loop — every turn it pumps the toolkit and then polls each control's one-shot activation latch (uiWidgetTakeActivated) and reacts, so clicking a button switches the visible panel (uiWidgetVisible) and updates the status line (uiWidgetSetText) live. The MUAL editor's document panel is a uiScrolledView, so its long watch-list scrolls and a scrollbar appears automatically on overflow — the newest GUI feature. All five GUI examples share the permanent Wi-Fi identity Wifi through uiWidgetSetIcon, using user-interface/icons/wifi.png as the primary lossless raster asset. wifi.svg is retained for scalable vector rendering and wifi.jpeg for compatibility; the connectivity action and popup behavior remain the same across all five examples.
  2. A full set of science examples — runnable SLeeLa programs on the science subject libraries (math, physics, chemistry, astrophysics, sociology) and BODI XML projects for every executable runner discipline, all grounded in the real churn/ datasets. These live in example/science/.
  3. A worked XLT CPU-model sheet.
FileWhat it is
gui-mual-text-editor.sleelaGUI MUAL (1.0 baseline) — interactive: the Editor / Documents / About buttons switch the visible panel, Save / New update the status line, and the Documents panel is a uiScrolledView whose 1..14 watch-list scrolls with an automatic scrollbar on overflow.
gui-gual-settings-console.sleelaGUI GUAL (2.0) — interactive: clicking an accepted backend (javafx / swing / native) selects it live (suggested highlight + status), while qt is refused on click (fail-closed configureStrict). Clamped knobs ride live sliders/toggles/combo.
gui-thual-effects-showcase.sleelaGUI THUAL (3.0) — interactive: Confirm fires the audio cue and advances the schene (rotating the live throbber hue a quarter-turn per the memo key epoch); Toggle fade fades the primary action in/out.
gui-dual-media-studio.sleelaGUI DUAL (4.0) — interactive: the Play / Pause / Stop transport and Record / Stop controls change the player + recorder state live, all codec-gated (the UI only offers media it can play).
gui-military-command-console.sleelaGUI MILITARY (5.0) — interactive and fail-closed: Run is locked until Authorize is clicked (then it executes under authority), and Reset clears authority and re-locks Run — SLGuiAdminAuthority made tangible. Metal/blue surface, strong branding, taxonomy, crypto selector, certificate store.
gui-military-window.sleelaGUI MILITARY (5.0) — the designed command console as a real, on-screen window (the original native ui* showcase these examples now all follow).
gui-buffering-resize.sleelaDouble / triple buffering — a resizable window that selects a presentation buffering mode (uiWindowSetBuffering) so a resize lands atomically with no tearing; buttons switch single/double/triple live. Also a validated SLGuiSettings.bufferingMode knob (2.0+).
run-gui-examples.shRuns all five version-line examples plus the military-window and buffering-resize demos.
run-gui-military.shRuns just the military-line command console (self-contained ui* program — no dep files needed).
science/Science examples for every discipline — runnable SLeeLa programs (*.sleela) on the subject libraries and BODI XML projects. See science/README.md.
threadripper-workstation.xltAn XLT (.xlt) CPU-model sheet — declaratively authors a CPU, board, tiered memory, capabilities, and a program to run on the assembled machine.

Shared GUI Color Theme

The four lib/gui version-line demos each use one of the toolkit's four Standard Pattern theme presets (built into SleelaUI as SLUIThemeId values, applied with uiThemePreset(id) — no per-colour overrides). MILITARY keeps its own metal/blue branded palette and is left unchanged.

DemoStandard PatternPreset idCharacter
MUALWHITE4Light surfaces, dark text, blue accent
GUALBLACK5Deep black surfaces, light text
THUALBLUE6Blue-tinted surfaces, light text
DUALGRAY7Neutral mid-gray surfaces, light text
MILITARY(own)—Metal/blue branded palette, unchanged

Each preset is a flat, one-accent palette defined in user-interface/src/slui_theme.cpp; a host selects one by id and tunes only the family metrics (radius, control height).

Frame, overflow, and the floating Wi-Fi popup

Three toolkit behaviours these demos rely on:

Native operating-system title-bar tinting is platform/window-manager dependent; the preset's chrome token is applied to the toolkit's own header surface.


1. GUI examples — one per lib/gui version line

SLeeLa's GUI vocabulary ships as five source-compatible version lines (see lib/gui/ARCHITECTURE.md); each higher line keeps every entry point of the one below and adds its surface on top:

LineDirSLPackage.version()Surface it adds
MUALversion-mual1.0The original 25-class baseline: backend selector, window intent, actions, the 1..14 document listener, and the three integration paths.
GUALversion-gual2.0A hardened, settings-first posture: one validated SLGuiSettings, a fail-closed configureStrict() backend, a clamped-resize window, and a backpressure-aware listener.
THUALversion-thual3.0A clean visual-effects layer: SLGuiEffects (glow/shine/shadow/metal/rotation/fade/audio), a scheduled-rotation "schene" tied to a memo key epoch, SLGuiBranding, and SLGuiAudioCues.
DUALversion-dual4.0A rich professional component set: SLGuiAudioRecorder, SLGuiVideoCanvas, SLGuiUrlBar, SLGuiLayout, SLGuiGraphics, and a codec-aware media gate (SLGuiCodecs).
MILITARYversion-military5.0-militaryThe 4.0 surface hardened: metal/blue aesthetic + 3D-lit frame, Component-vs-Container taxonomy, icons, a crypto selector, an X.509-style certificate store, and window key-listeners.

Running the GUI examples

A built sleela binary is required — ./scripts/build-linux.sh (or make -C impl) produces one at impl/build/sleela.

These examples now draw real windows. Each one is self-contained (an inline model + main using only ui* built-ins) and paints its scene through SleelaUI — the project's own native C/C++ toolkit — via the ui* SLVM bridge (OP_UI_CALL → user-interface/ C ABI → X11 / Cocoa / Win32), the same path as gui-military-window.sleela. On a host with a display they open a window and render the widgets; with no display (headless/CI) each prints a one-line "no display" notice and exits 0.

Run the five version-line examples plus the two additional native-window demos at once:

./example/run-gui-examples.sh

or one at a time:

export SLEELA_SHEET="$PWD/SHEET.sheet"
export SLEELA_SHA256_MANIFEST="$PWD/security/sha256-manifest.json"
./impl/build/sleela run example/thual/gui-thual-effects-showcase.sleela

A display is needed to see the window. On Linux that means an X server (DISPLAY set) plus the runtime libs the toolkit links (libX11, libfreetype, libfontconfig); macOS/Windows use the native backend. Without one, the programs still run and exit cleanly — they just report "no display".

The SHA-256 security gate is fail-closed. sleela refuses to run unless SLEELA_SHA256_MANIFEST points at the trusted manifest, and it also needs SLEELA_SHEET. Both wrappers set these for you.

The MILITARY (5.0) command console runs the same way; its wrapper is just a convenience:

./example/run-gui-military.sh
# or, equivalently:
./impl/build/sleela run example/military/gui-military-command-console.sleela

2. Science examples — SLeeLa programs and BODI XML, for every discipline

example/science/ holds two kinds of science example, both grounded in the real, sourced churn/ datasets, each with a recorded expected-output evidence file:

SLeeLa programs (*.sleela) — on the science subject libraries

Runnable .sleela programs on the science subject libraries (import math;, import chemistry;, …): Mathematics, Physics, Chemistry, Astrophysics, Sociology.

./example/science/run-science-sleela.sh    # run all five
# or: cd example/science && make sleela-check

BODI XML projects (*.xml) — on the BODI XML runner

One deterministic BODI XML project per executable runner discipline:

cd api/bodi && make                # builds bodi-xml-runner
cd ../../example/science
make                               # run every XML example, print witnesses
make check-all                     # check BOTH the XML and .sleela examples

See science/README.md for the full tables and data provenance.


3. threadripper-workstation.xlt — an XLT CPU model

An .xlt sheet declaratively authors a CPU model: a chosen SKU plus the board, memory, refresh cadence, storage, and bus parts that assemble it. No setters and no new keyword — each part is declared once, in order, and the document's orthogonality is what guarantees the model's integrity.

This example goes end to end: it picks a Threadripper SKU on a DDR5 board, splits memory into two tiers (DDR4 for usual activities, DDR5 for accuracy-critical work), requests the native-compute capabilities (gpu, dma, nativeram), and then politely runs a program on the machine it assembled — all from one document.

Build the compiler and compile the model:

make -C impl/xlt                                   # produces impl/xlt/build/xltc
./impl/xlt/build/xltc example/xlt/threadripper-workstation.xlt

xltc reports SUCCESS with a build list, or a congruence explaining why a part could not be resolved. For the directive reference (capabilities, memory tiers, program/grant), see lib/xlt/README.md.

Note: the exact SKU/memory/bus names must resolve in the model registry. If a part name reports a congruence on your tree, swap it for one used in the shipped examples under lib/xlt/examples (e.g. "SLAMDEPYC9575F", "ddr5_6400", "pcieGen5x16").

Cross-Platform Launchers

Each GUI folder includes a dedicated launcher for Linux and macOS (run-*-gui.sh), Windows PowerShell (run-*-gui.ps1), and Windows Command Prompt (run-*-gui.cmd). From the repository root, the launchers locate the built SLeeLa executable and set the default sheet and SHA-256 manifest environment variables.

Run all five GUI examples:

Set SLEELA_BIN to override executable discovery. The GUI examples require a desktop session for their native windows; the scripts do not install the compiler or GUI dependencies.

Source-of-Truth Rule: The five GUI examples and SLGuiTheme.sleela define the palette directly in SLeeLa source code. The SLGuiApp implementations apply those tokens to the live window theme. Do not depend on external theme files, environment variables, or generated settings to select these colors; editing the source palette is the authoritative change.

Expandable Menubar Showcase

The dedicated menus/ example demonstrates a horizontal File/Edit/View/Help menubar, single-open dropdowns, nested Recent Files and Panels groups that expand/collapse, and menu-item status feedback. Run it with ./impl/build/sleela run example/menus/gui-menubar-expandable.sleela; the unified GUI runners also include it.

Connectivity status control

The five interactive GUI examples (dual, gual, mual, thual, and military) include a clickable 📶 Wi-Fi control at the lower-right of the status bar. It opens a connectivity panel with scan, connect, disconnect, settings, connection-details, and close actions. The panel closes when the icon is toggled, an action is selected, or another example control is activated. Until an SLVM-to-native Wi-Fi host bridge is bound, network-changing actions report that limitation rather than claiming to change the real radio.


SLeeLa

<p align="center"><img src="images/sleela/sleela-wordmark.svg" alt="SLeeLa — The Now. The Ingredient." width="560"></p> <p align="center"><img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela-programming-language-002.jpg" alt="SLeeLa Marketing Logo" width="560"></p>