Home /Modules/gui/SLGuiApp.sleela

SLGuiApp.sleela

lib/gui/version-military/SLGuiApp.sleela · 379 line(s) · sleela

<< lib/gui/version-military/SLGuiApp.sleela
   SLeeLa Standard Library Definition.
   Definition: Defines SLGuiApp — the top-level support structure that ties the
     whole /lib/gui dynamic stack together into one object: it opens a SleelaUI
     application and window (via /lib/user-interface), owns the SLeeLa DOM
     (SLGuiDom), the reconciler (SLGuiMount) that projects the DOM onto widgets,
     the host adapter (SLGuiHostAdapter) that raises widget activations back as
     events, and an optional script engine (SLGuiScript). Its run loop pumps the
     toolkit event loop, polls widget activations into the event bus, re-mounts
     any newly-created nodes, and reconciles dirty nodes each turn. This is the
     "basic support structure" a program (or the IDE) builds on: construct the
     DOM declaratively or by script, bind callbacks, and call run().
   
   Family: gui. SLeeLa owns the DOM, dispatch, and script execution; SleelaUI
   owns presentation; this object is the wiring between them. >>
#sleela 2.5
material;
class SLGuiApp {
  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  << Eleven catalogued attributes with getter/setter pairs, so a GUI, loader,
     or catalog can read and (where appropriate) override this record.
     Values are faithful to the subject's real origin where publicly known. >>
  String metaVersion = "1.0.0";
  int metaId = 11416;
  String metaAuthor = "Kiro Agent";
  String metaDate = "2026-10-20";
  String metaCopyright = "SLeeLa project";
  String metaTrademark = "none";
  String metaCorporation = "none";
  < metaOrigin: National | <nation> | International | Galactic >
  String metaOrigin = "International";
  String metaBirthDate = "2026-10-16";
  < metaScienceRating: maturity/robustness on a 1..10 scale >
  int metaScienceRating = 9;
  < 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; }
  < Choose DEFAULT, WHITE, BLUE, BLACK, or GRAY here for this GUI family. >
  static final int THEME_PRESET = SLTheme.DEFAULT;
  SLUserInterface ui;
  SLWindow window;
  SLGuiDom dom;
  SLGuiMount mount;
  SLGuiHostAdapter host;
  SLGuiScript script;
  < 3.0 logo/brand identity painted into the chrome >
  SLGuiBranding branding;
  < 3.0 activation-audio cue registry >
  SLGuiAudioCues audio;
  < 4.0 codec registry (mirror of /codecs) GUI can see >
  SLGuiCodecs codecs;
  < 4.0 HTML/CSS/JS renderer (quick-responsive) >
  SLGuiHtmlRenderer html;
  < 5.0 Component vs Container taxonomy >
  SLGuiKind kinds;
  < 5.0 cryptography selector component >
  SLGuiCryptoSelector crypto;
  < 5.0 public-key certificate store >
  SLGuiCertificateStore certs;
  < 5.0 window-state + key listeners (fold/restore) >
  SLGuiWindowState winState;
  < sizes the window from the actual screen size >
  SLGuiScreenFit screenFitter;
  < nominal per-loop tick for scheduled effects >
  int frameMillis;
  int ready;

  < Open the application + window and stand up the DOM/mount/host wiring. >
  < Returns true when the toolkit came up (false on a headless host). >
  boolean boot(String appId, String title, int width, int height) {
    ui = new SLUserInterface();
    ui.configure(appId);
    if (!ui.open()) { ready = 0; return false; }

    < Enforce the physical screen as a hard upper bound even when callers >
    < use boot() directly instead of bootFitted(). Keep a small decoration/ >
    < taskbar margin where possible; never let a requested size win over screen. >
    int screenW = ui.screenWidth();
    int screenH = ui.screenHeight();
    if (screenW > 0) {
      int maxWindowW = screenW - 32;
      if (maxWindowW < 1) { maxWindowW = screenW; }
      if (width <= 0 || width > maxWindowW) { width = maxWindowW; }
    }
    if (screenH > 0) {
      int maxWindowH = screenH - 64;
      if (maxWindowH < 1) { maxWindowH = screenH; }
      if (height <= 0 || height > maxWindowH) { height = maxWindowH; }
    }

    SLTheme theme = new SLTheme();
    < Source-selected preset is the single palette source for native widgets. >
    < To choose another look, set THEME_PRESET to SLTheme.WHITE, BLUE, BLACK, or GRAY. >
    theme.preset(THEME_PRESET);
    theme.setRadius(8);
    theme.setControlHeight(32);
    window = ui.openWindow(title, width, height, theme.handle());

    dom = new SLGuiDom(); dom.init();
    < The document root mirrors the window's existing root container. >
    dom.createRoot("window", "root");

    mount = new SLGuiMount(); mount.init(dom, window.rootHandle());
    host = new SLGuiHostAdapter(); host.init(dom, mount);
    script = new SLGuiScript(); script.init(dom);

    < 3.0 surfaces: a brand identity and the activation-audio cue registry. >
    branding = new SLGuiBranding(); branding.configure("");
    audio = new SLGuiAudioCues(); audio.configure();
    < 4.0 surfaces: the codec registry (so GUI components can SEE what /codecs >
    < supports) and the quick-responsive HTML/CSS/JS renderer, which shares the >
    < same codec registry for its media gate. >
    codecs = new SLGuiCodecs(); codecs.configure();
    html = new SLGuiHtmlRenderer(); html.configure();
    < 5.0 military surfaces: the Component/Container taxonomy, the cryptography >
    < selector, the public-key certificate store, and the window-state machine >
    < (resize/minimize/fullscreen/fold-to-side + double-click restore). >
    kinds = new SLGuiKind();
    crypto = new SLGuiCryptoSelector(); crypto.configure();
    certs = new SLGuiCertificateStore(); certs.configure();
    winState = new SLGuiWindowState(); winState.configure(0, 0, width, height);
    < Feed the window-state machine the ACTUAL desktop size (0 when headless, >
    < which SLGuiWindowState then keeps as its 1920x1080 fallback). >
    winState.setDesktop(ui.screenWidth(), ui.screenHeight());
    < A screen-fit helper, primed with the real screen for later re-sizing. >
    < moderate >
    screenFitter = new SLGuiScreenFit(); screenFitter.configure(1);
    screenFitter.setScreen(ui.screenWidth(), ui.screenHeight());
    < Strong, facile, professional branding is on by default in the military line. >
    branding.setPlacement(branding.PLACE_HEADER); branding.setScalePct(110);
    < ~60 fps nominal tick for scheduled rotation/fade >
    frameMillis = 16;

    ready = 1;
    return true;
  }

  < Open the application and size the window to the ACTUAL screen / resolution, >
  < at a support tier (0=basic, 1=moderate, 2=advanced; see SLGuiScreenFit). >
  < Queries uiScreenWidth/uiScreenHeight through the facade; a headless host >
  < falls back to a modeled 1920x1080. Returns true when the toolkit came up. >
  boolean bootFitted(String appId, String title, int tier) {
    SLUserInterface probe = new SLUserInterface();
    probe.configure(appId);
    if (!probe.open()) { ready = 0; return false; }
    SLGuiScreenFit fit = new SLGuiScreenFit();
    fit.configure(tier);
    fit.setScreen(probe.screenWidth(), probe.screenHeight());
    fit.fit();
    < reopened inside boot() with the resolved size >
    probe.close();
    boolean ok = boot(appId, title, fit.width(), fit.height());
    if (ok) { screenFitter = fit; }
    return ok;
  }

  < The screen-fit helper (primed with the real screen). Call setScreen()/fit() >
  < to recompute, then read width()/height()/x()/y() for a resize or re-center. >
  SLGuiScreenFit screenFit() { return screenFitter; }

  < Build an IMPLIED scrollbar model for a scrolled surface. `horizontal` >
  < selects the axis; `viewport`/`content` are the extents on that axis. The >
  < returned SLGuiScrollbar yields orient()/valuePermille()/pagePermille() to >
  < paint with uiScrollBar (or an SLScrollBar), and tracks the scroll offset. >
  SLGuiScrollbar scrollbarFor(int viewport, int content, boolean horizontal) {
    SLGuiScrollbar sb = new SLGuiScrollbar();
    sb.configure(horizontal ? 1 : 0, viewport, content);
    return sb;
  }

  < Presentation buffering for the live window: 0=single, 1=double (the >
  < toolkit default, flicker-free resize), 2=triple (smoother rapid resize). >
  < Pass SLGuiSettings.getBufferingMode() here to honor the configured knob. >
  void setBuffering(int mode) { if (window != null) { window.setBuffering(mode); } }
  int buffering() { return (window != null) ? window.buffering() : 0; }

  < Add a SCROLLED VIEWPORT node to the DOM under `parentId`. Its children >
  < become the scroll content and native scrollbars appear AUTOMATICALLY when >
  < that content is larger than the viewport. Pin the viewport smaller than its >
  < content (e.g. style "min-height") to force scrolling. Equivalent to adding a >
  < "scrolled" element; returns the node so the caller can append content to it. >
  SLGuiNode addScrolled(String parentId, String id) {
    return dom.appendElement(parentId, "scrolled", id);
  }
  < Add a plain container that scrolls on overflow by setting its `overflow` >
  < intent (auto|scroll|always|hidden). SLGuiMount promotes it to a native >
  < scrolled viewport. Returns the node for appending content. >
  SLGuiNode addOverflowBox(String parentId, String id, String overflow) {
    SLGuiNode n = dom.appendElement(parentId, "box", id);
    if (n != null && overflow != null) { n.setAttribute("overflow", overflow); }
    return n;
  }


  < ---- fade / transition helpers ------------------------------------------ >
  < A reusable enter/exit fade primitive (the shared tween). Returns a default >
  < 200ms ease-out fade-in the caller can retarget with fadeIn/fadeOut/between. >
  SLGuiTransition transition() {
    SLGuiTransition t = new SLGuiTransition(); t.configure();
    return t;
  }
  < A TOAST / SNACKBAR: a small self-dismissing notification that fades in, >
  < dwells, and fades out. Driven by tick(); read opacityPct() to paint it. >
  SLGuiToast toast(String message) {
    SLGuiToast t = new SLGuiToast(); t.configure(message);
    return t;
  }
  < A MODAL / OVERLAY: a dialog that fades in over a darkened backdrop (scrim). >
  SLGuiModal modal(String title) {
    SLGuiModal m = new SLGuiModal(); m.configure(title);
    return m;
  }
  < A SKELETON SCREEN / PLACEHOLDER: a shimmering loading placeholder that >
  < dissolves to reveal real content (shape 0=text/1=card/2=avatar/3=list). >
  SLGuiSkeleton skeleton(int shape, int lines) {
    SLGuiSkeleton s = new SLGuiSkeleton(); s.configure(shape, lines);
    return s;
  }


  < ---- 5.0 military surfaces access --------------------------------------- >
  SLGuiKind taxonomy() { return kinds; }
  SLGuiCryptoSelector cryptoSelector() { return crypto; }
  SLGuiCertificateStore certificateStore() { return certs; }
  SLGuiWindowState windowState() { return winState; }

  < Is a tag a container or a component (the explicit taxonomy)? >
  boolean isContainer(String tag) { return kinds.isContainer(tag); }
  boolean isComponent(String tag) { return kinds.isComponent(tag); }

  < Attach an icon to a node — ONLY when the node's tag is icon-eligible >
  < (buttons, menu items, clickables). Returns false otherwise (fail-closed), >
  < so icons land exactly where they belong. >
  boolean setIcon(String nodeId, SLGuiIcon icon) {
    SLGuiNode n = dom.getElementById(nodeId);
    if (n == null || icon == null) { return false; }
    if (!kinds.iconEligible(n.getTag())) { return false; }
    n.setIcon(icon);
    return true;
  }

  < ---- 4.0 codecs + HTML renderer access ---------------------------------- >
  < The codec registry every GUI media component can consult. >
  SLGuiCodecs codecRegistry() { return codecs; }
  SLGuiHtmlRenderer htmlRenderer() { return html; }
  < Convenience capability questions for GUI implementations. >
  boolean canPlayCodec(String codecName) { return codecs.playable(codecName); }
  boolean canPlayExtension(String ext) { return codecs.playableExtension(ext); }
  int supportedCodecs() { return codecs.playableCount(); }

  < ---- 3.0 branding + audio access ---------------------------------------- >
  SLGuiBranding brand() { return branding; }
  SLGuiAudioCues audioCues() { return audio; }
  void setFrameMillis(int ms) { if (ms > 0) { frameMillis = ms; } }

  < Apply a brand logo + accent in one call (host paints it into the chrome). >
  void setLogo(String asset, String accent) {
    branding.setLogo(asset);
    if (accent != null) { branding.setColors(accent, null); }
  }

  < Give a node an effects bundle and (optionally) an activation cue, then >
  < flatten it into the node's style for the next reconcile. >
  SLGuiEffects effectsFor(String nodeId) {
    SLGuiNode n = dom.getElementById(nodeId);
    if (n == null) { return null; }
    SLGuiEffects e = n.effects();
    return e;
  }

  boolean isReady() { return ready == 1; }

  < ---- document access ---------------------------------------------------- >

  SLGuiDom document() { return dom; }
  SLGuiScript scripting() { return script; }
  SLWindow hostWindow() { return window; }

  < Convenience: append an element to a parent in the DOM (then mount+show on >
  < the next loop turn, or immediately via refresh()). >
  SLGuiNode add(String parentId, String tag, String id) {
    return dom.appendElement(parentId, tag, id);
  }

  < Bind a click callback (DHTML onClick) by node id. >
  SLGuiHandler onClick(String id, String operation) { return dom.onClick(id, operation); }

  < Run a UI script against the DOM (build + bind + fire), then refresh. >
  int runScript() {
    int n = script.run();
    refresh();
    return n;
  }

  < ---- the loop ----------------------------------------------------------- >

  < Mount everything, show the window, then run the toolkit event loop: >
  < pump -> poll activations -> mount new nodes -> reconcile. Returns the >
  < process-style exit code. >
  int run() {
    if (ready == 0) { return 1; }
    mount.mountAll();
    window.show();
    while (ui.active()) {
      int dispatched = ui.pump(true);
      if (dispatched < 0) { break; }
      < widget activations -> SLGuiEvents -> handlers >
      host.poll();
      < tick scheduled ("schene") rotations/fades >
      advanceEffects(frameMillis);
      < pick up nodes added by handlers/scripts >
      mount.mountNew();
      < push dirty DOM state onto widgets >
      mount.reconcile();
      window.requestRedraw();
    }
    return 0;
  }

  < Advance every node's scheduled effects by `elapsedMillis`: scheduled >
  < rotations turn (and their bound memorandum key epoch rotates with them), >
  < and the host interpolates fades. Returns how many nodes moved this tick. >
  int advanceEffects(int elapsedMillis) {
    if (ready == 0) { return 0; }
    int moved = 0;
    int n = dom.size();
    for (int i = 0; i < n; i = i + 1) {
      SLGuiNode node = dom.nodeAt(i);
      if (node != null && node.hasEffects()) {
        if (node.tickEffects(elapsedMillis)) { moved = moved + 1; }
      }
    }
    return moved;
  }

  < A single synchronous refresh (mount new + reconcile) without the loop, >
  < for building a UI up front or driving it from a test/host step. >
  void refresh() {
    if (ready == 0) { return; }
    mount.mountNew();
    mount.reconcile();
  }

  < Pump one turn (pump + poll + refresh); returns events raised this turn. >
  int step(boolean block) {
    if (ready == 0) { return 0; }
    ui.pump(block);
    int raised = host.poll();
    refresh();
    window.requestRedraw();
    return raised;
  }

  void quit(int code) { if (ui != null) { ui.quit(code); } }
  void shutdown() { if (ui != null) { ui.close(); } ready = 0; }
}