Home /Modules/gui/ARCHITECTURE.md

ARCHITECTURE.md

lib/gui/ARCHITECTURE.md · 402 line(s) · markdown

SLeeLa lib/gui — the SLeeLa-facing GUI vocabulary

Revision: 0.1 Family: gui

lib/gui is the SLeeLa-facing consequence of the top-level gui/ work. The gui/ directory holds the Java host, the native C ABI bridge (gui/native/sleela_gui_bridge.{h,cpp}), and the 1..14 document-change listener; lib/gui is the .sleela contract a SLeeLa program uses to express that same model. The two are kept in correspondence: every class here mirrors a concept documented in gui/INTEGRATION.md and gui/DOCUMENT_LISTENER.md.

The division of authority

The architecture is intentionally asymmetric (see gui/INTEGRATION.md):

Java is a native desktop host for SLeeLa, not a second business-logic implementation.

Classes

ClassMirrors (in gui/)Role
SLGuiBackendSleelaGui.create(backend)toolkit-neutral backend selector: swing / javafx (alias fx) / native
SLGuiWindowSleelaGuiwindow intent: show, setText, and the refresh(id, revision) document sink
SLGuiActionSleelaGuiRuntime.action / SleelaGui.onActiona named action bound to a SLeeLa operation; take-the-latch activation
SLGuiMenuBarhost menu-bar surfaceordered menu-bar state, visibility, focus, and active-menu navigation
SLGuiMenuhost menu surfacemenu visibility/open state, active item navigation, and selection bounds
SLGuiMenuItemhost menu-item surfaceenabled/checkable/checked/separator state, icon + shortcut metadata, and one-shot activation latch
SLGuiDocumentSleelaDocumentimmutable watched-document snapshot: id, path, OS revision (lastModified:size / absent)
SLGuiDocumentListenerDocumentListenerthe 1..14 document watch; OS-driven refresh; revision coalescing
SLGuiRuntimeSleelaGuiRuntimePath 2 — SLeeLa intent drives the window directly
SLGuiHostSleelaGuiHostPath 1 — a Java host ties actions/changes to SLeeLa operations
SLGuiBridgesleela_gui_bridge.hPath 3 — the shared native ABI (create/call/refresh/destroy)
SLGuiIntegrationgui/INTEGRATION.mdthe recommended three-path posture

A runnable, self-contained walkthrough is lib/gui/version-mual/gui-demo.sleela (the GUI .sleela impl now lives in lib/gui/version-mual/, with an identical copy in lib/gui/version-gual/; lib/gui/ keeps these docs).

All five versioned lines now carry SLGuiMenuBar, SLGuiMenu, and SLGuiMenuItem model classes. These are toolkit-neutral state contracts: SLeeLa owns labels, action names, enabled/checked state, focus/navigation state, and activation latches; the Java/native host owns actual drawing, pointer/keyboard events, accessibility integration, and any native-menu API calls.

The widget factories recognize menubar/menu-bar, menu, menuitem/menu-item, and menuseparator/menu-separator. The factory currently constructs these using existing box/button/separator primitives, which gives a portable custom-widget fallback. SLGuiBackend.supportsNativeMenus() reports whether a backend is eligible to request native menus (javafx/fx or native); this capability flag is not a claim that every host has already wired native menu rendering. The Swing fallback remains custom-rendered.

SLGuiMenuItem.activate() refuses disabled items, separators, and items without a named action; valid activations toggle checkable state and set a one-shot latch for the host/runtime to consume with takeActivation(). The host must dispatch the configured action name/operation, close the menu after ordinary activation, and preserve keyboard focus/navigation semantics.

Versioned lines: version-mual (1.0) and version-gual (2.0)

The GUI .sleela impl is carried in two parallel lines under lib/gui/:

The lines are source-compatible: each higher line keeps every entry point of the one below and adds its surface on top (1.0 → +settings → +visual effects → +professional components → +military hardening).

Scrolling + screen-aware sizing (all lines)

Two line-agnostic helpers ship in every version line (1.0 → 5.0):

SLGuiApp wires both in: boot() primes a SLGuiScreenFit from the live display and feeds the desktop size to SLGuiWindowState (military); `bootFitted(appId, title, tier)` opens the app, queries the real screen, and sizes the window to it; screenFit() and scrollbarFor(viewport, content, horizontal) expose the two helpers. The real screen comes from the new uiScreenWidth(app) / uiScreenHeight(app) built-ins (C ABI slui_screen_size), surfaced on the shared SLUserInterface facade as screenWidth() / screenHeight(); a headless host reports 0 and SLGuiScreenFit falls back to a modeled 1920×1080. SLGuiWidgetFactory registers the scrollbar/vscroll (vertical) and hscroll (horizontal) tags. A runnable walkthrough is each line's gui-scroll-screenfit-demo.sleela.

Automatic scrollbars on overflow — the ScrolledView (all lines)

SLGuiScrollbar is the geometry brain; the native slui::ScrolledView (in user-interface/) is the muscle that makes scrolling automatic. It is a real container widget that measures its content, clips it to the viewport, and reveals a scrollbar on its own when the content overflows — so a component dimensionally larger than its frame scrolls instead of spilling off-screen.

So the earlier "overflow never auto-scrolls" limitation is resolved: the native viewport clips + scrolls + shows bars automatically, SLGuiScrollbar remains the pure geometry model behind it, and the SLeeLa layer makes it available both as an explicit element and as an overflow attribute on any container.

Double / triple buffering for smooth resize (all lines)

How a painted frame reaches the screen is now a selectable presentation buffering mode in the native toolkit, so a resize/redraw lands cleanly instead of tearing:

A runnable walkthrough is example/gui-buffering-resize.sleela.

Fade transitions + notification surfaces (all lines)

Four line-agnostic fade / transition surfaces ship in every version line (1.0 → 5.0). They answer the three ways UI fading is named: the component that fades (toast/snackbar, modal/overlay, skeleton/placeholder, transition wrapper), the action of fading (an enter/exit transition — tween + easing + dissolve), and the CSS surface it maps to (opacity, transition, @keyframes). Each is a pure, integer-only model with honored() / report() and a toStyle() that flattens into the descriptor the SLGuiMount reconciler copies onto the widget; SLeeLa owns the curve, timing, and lifecycle, and the host paints the pixels at the opacity the model reports.

SLGuiApp exposes them as transition(), toast(message), modal(title), and skeleton(shape, lines). SLGuiWidgetFactory registers the toast/snackbar, modal/dialog/overlay, skeleton/placeholder, and transition/fade container tags. A runnable walkthrough is each line's gui-transitions-demo.sleela. (In the 3.0+ lines these complement the per-node SLGuiEffects fade knob: SLGuiEffects sets a static opacity/fade target on a node, while SLGuiTransition et al. are full self-contained enter/exit tweens with a lifecycle.)

Events, DHTML-style DOM, and scripting

On top of the integration layer, lib/gui provides the backing API for dynamic interfaces — action callbacks, a browser-DOM-style document, and a scripting engine. SLeeLa owns the meaning of events and the document; the host raises activations and mirrors the DOM onto SleelaUI widgets.

ClassRole
SLGuiEventTypeThe event catalogue (click/input/change/keydown/…).
SLGuiEventA dispatched event with preventDefault/stopPropagation.
SLGuiHandlerA bound callback (type, target, operation), take-the-latch.
SLGuiEventBusThe dispatcher: addEventListener, phased dispatch.
SLGuiNodeA DOM element: attributes, inline style, children, visibility.
SLGuiDomThe document: getElementById, createElement, onClick, …
SLGuiScriptCommandOne script instruction (verb + operands).
SLGuiScriptThe command-list engine that drives the DOM/events.

The full contract and a runnable walkthrough (lib/gui/version-mual/gui-events-demo.sleela) are in EVENTS-DOM-SCRIPTING.md.

The three integration paths

Path 1  Java host    -> SLeeLa logic   (SLGuiHost)
Path 2  SLeeLa intent -> Java GUI       (SLGuiRuntime)
Path 3  shared native ABI bridge        (SLGuiBridge)

They are complementary, not mutually exclusive; the preferred long-term setup enables all three (SLGuiIntegration.recommended()).

Document-change listener (1..14, OS-driven)

Any path can enable the document-change listener option: watch 1 to 14 documents and refresh the running window whenever any changes on an OS call. Detection is OS-driven (a WatchService over inotify / ReadDirectoryChangesW / kqueue/FSEvents), not polling; an OS event that does not move a document's revision fingerprint (lastModifiedMillis:size) is coalesced away. The 1..14 bound is a hard contract, enforced in SLGuiDocumentListener.withinBound() and mirrored in the native ABI (SLGUI_MIN_DOCUMENTS / SLGUI_MAX_DOCUMENTS).

Watched documents (1..14)
        |
        v
OS notification (WatchService.poll)
        |
        v
revision moved?  --no--> coalesced (no refresh)
        | yes
        v
SLGuiWindow.refresh(id, revision)   (marshaled onto the toolkit thread)

Building and verifying

SLeeLa — MEARVK LLC — 2026