Home /Modules/gui/EVENTS-DOM-SCRIPTING.md

EVENTS-DOM-SCRIPTING.md

lib/gui/EVENTS-DOM-SCRIPTING.md · 131 line(s) · markdown

SLeeLa lib/gui — events, DHTML-style DOM, and scripting

Revision: 0.1 · Family: gui

This is the backing API for dynamic SleelaUI interfaces: action callbacks / onClick, a browser-DOM-style document model with live manipulation, and a small scripting engine that drives it. It extends the original lib/gui integration layer (window / action / 1..14 document watch) without changing its posture: SLeeLa owns the meaning of events and owns the document; the host raises activations and mirrors the DOM onto real SleelaUI widgets.

The three sub-layers

1. Events & callbacks

ClassRole
SLGuiEventTypeThe event catalogue (click, input, change, keydown, pointerdown, submit, toggle, custom, …) with stable ordinals and canonical names.
SLGuiEventOne dispatched event: type, target id, value/key/pointer payload, plus preventDefault() and stopPropagation() (exactly like a browser event).
SLGuiHandlerOne registered callback: (type, target, operation), with once/capture, and the take-the-latch activation SLGuiAction uses.
SLGuiEventBusThe dispatcher: addListener/removeListener, phase-ordered dispatch (capture → target/bubble), stopPropagation honoring, once sweeping.

2. DHTML-style DOM

ClassRole
SLGuiNodeA DOM element: tag, id, text, parent/children, an attribute map, an inline style map, visibility/enabled, and an optional live widget handle.
SLGuiDomThe document: createElement, getElementById, appendChild, removeChild, setText/setAttribute/setStyle, show/hide, getElementsByTag, querySelectorByAttr, and addEventListener + onClick/onInput/onChange/onKeyDown/onSubmit. Owns an SLGuiEventBus.

3. Scripting

ClassRole
SLGuiScriptCommandOne instruction: a verb (create, append, text, attr, style, show, hide, enable, on, fire, call, remove, nop) + up to four operands.
SLGuiScriptThe engine: an ordered command list run against an SLGuiDom, with the call verb crossing the native boundary via SLGuiBridge. Deliberately not a general interpreter — a bounded, auditable verb list that can do no more than the DOM API already allows.

How a callback flows

host raises activation ─▶ SLGuiEvent(type, target, value)
                          │
                          ▼
          SLGuiDom.dispatchEvent ─▶ SLGuiEventBus.dispatch
                          │  (capture → target/bubble, stopPropagation-aware)
                          ▼
          matching SLGuiHandlers fire ─▶ bound SLeeLa operation
                          │
                          ▼
      SLeeLa mutates the DOM (setText / setStyle / hide / …)
                          │
                          ▼
      host walks dirty SLGuiNodes ─▶ updates live SleelaUI widgets

Minimal usage

SLGuiDom dom = new SLGuiDom(); dom.init();
dom.createRoot("window", "app");
SLGuiNode save = dom.appendElement("app", "button", "save");
save.setText("Save");

dom.onClick("save", "doSave");          // bind a callback
dom.fire(SLGuiEventType.CLICK, "save", ""); // host raises; dispatcher routes it

Scripted equivalent:

SLGuiScript s = new SLGuiScript(); s.init(dom);
s.create("button", "save", "app");
s.text("save", "Save");
s.on("save", "click", "doSave");
s.fire("save", "click", "");
s.run();

A runnable walkthrough of all three sub-layers is lib/gui/version-mual/gui-events-demo.sleela (the GUI .sleela impl moved to lib/gui/version-mual/, copied to lib/gui/version-gual/).

The support structure (DOM ↔ toolkit wiring)

The event/DOM/scripting layer is SLeeLa-owned and host-agnostic. The support structure is the concrete wiring that projects it onto real /lib/user-interface widgets and feeds interactions back:

ClassRole
SLGuiWidgetFactoryThe one place that maps a node tag → a SleelaUI constructor (uiBox/uiButton/uiLabel/uiEntry/…) and says which tags are interactive and what event they raise.
SLGuiMountThe reconciler: mounts the DOM depth-first (parent before child), keeps an id → widget-handle map, and on each pass applies every dirty node's text/visibility/sensitivity/accent/size to its widget, then clears the flag. The SLeeLa→toolkit half.
SLGuiHostAdapterPolls each mounted interactive widget's activation latch (uiWidgetTakeActivated) and raises the matching SLGuiEvent (CLICK/SUBMIT/TOGGLE, carrying the widget's live value) into the bus. The toolkit→SLeeLa half.
SLGuiAppThe top-level object: opens the app + window, owns the DOM + mount + host adapter + script engine, and runs the loop (pump → poll activations → mount new nodes → reconcile).
            SLeeLa-owned                         host / toolkit
         ┌───────────────┐   reconcile (dirty)  ┌──────────────────┐
         │   SLGuiDom     │ ───── SLGuiMount ───▶ │ SleelaUI widgets │
         │  (SLGuiNode)   │                       │ (ui* built-ins)  │
         │   SLGuiEventBus │ ◀─── SLGuiHostAdapter ─ (uiWidgetTake-  │
         └───────────────┘    dispatch events     │   Activated)     │
                 ▲                                 └──────────────────┘
                 │ SLGuiApp owns + runs the loop

Minimal support-structure usage

SLGuiApp app = new SLGuiApp();
if (app.boot("com.mearvk.App", "App", 640, 420)) {
  SLGuiNode save = app.add("root", "button", "save");
  save.setText("Save");
  app.onClick("save", "doSave");   // bind a callback
  app.run();                       // mount, show, loop (poll + reconcile)
}

A runnable walkthrough is lib/gui/version-mual/gui-app-demo.sleela.

Relationship to the toolkit

The DOM nodes name SleelaUI concepts (window, box, button, label, entry, …). SLGuiMount mounts each node onto the matching /lib/user-interface widget and pushes dirty-node changes to it; SLGuiHostAdapter raises SLGuiEvents when the user interacts. The event bus and DOM stay the single SLeeLa-owned source of truth, consistent with the lib/gui division of authority.

SLeeLa — MEARVK LLC — 2026