Home /Modules/ui/SLLayoutDriver.sleela

SLLayoutDriver.sleela

lib/ui/SLLayoutDriver.sleela · 226 line(s) · sleela

<< lib/ui/SLLayoutDriver.sleela
   SLeeLa Standard Library Definition.
   Definition: SLLayoutDriver — the bridge that lets the pure-SLeeLa Standard
     Layout family actually DRIVE real on-screen widgets through the native
     SleelaUI toolkit (the `ui*` SLVM bridge). The Standard Layouts
     (SLStackLayout, SLGridLayout, ... organized by SLLayoutFrame) are the
     PLANNING layer: they compute, in pure SLeeLa, the exact pixel rectangle of
     every component. SLLayoutDriver is the REALIZING layer: it reads that plan
     and configures a native container plus each native child so the live
     toolkit reproduces the plan.

   Why this shape. The SleelaUI toolkit — like GTK or Qt layouts — is a
   container/pack model: you declare structure (a box with an orientation and a
   spacing, or a grid of N columns) and the toolkit solves geometry on every
   backend (X11 / Win32 / Cocoa). There is no "put this widget at absolute x,y"
   call, by design, so a view stays correct when the window resizes. The good
   news: the Standard STACK and GRID layouts use the SAME model as the native
   uiBox / uiGrid containers (orientation + gap, or columns + gap, with
   fixed vs. flexible children). So realizing them is FAITHFUL, not lossy:
     - a column/row stack  -> uiBox(parent, orient, gap)
     - a grid               -> uiGrid(parent, columns, gap)
   and each child is given the plan's size as a minimum-size request
   (uiWidgetSizeRequest), with flexible (size 0) children marked to expand
   (uiWidgetExpand) so they share the leftover space exactly as the planner
   computed.

   This class is native, bridge-backed (it calls `ui*`), so — unlike the pure
   SL*Layout planners — it only runs where a display/toolkit is present. It is
   the twin of the pure-SLeeLa SLLayoutFrame: plan with the Frame, realize with
   the Driver.

   Easy path (plan a settings column, then build it on a real window root):
     SLLayoutFrame f = new SLLayoutFrame(); f.create();
     f.useColumn(8, 12);
     f.add("header", 40);
     f.add("list",   0);          < flexible: fills the rest >
     f.add("footer", 32);
     f.place(0, 0, 320, 600);

     SLLayoutDriver d = new SLLayoutDriver(); d.create();
     int box = d.realizeStack(root, f);   < native uiBox matching the plan >
     < create real controls parented into `box`, in component order ... >
     int header = uiLabel(box, "Settings");
     d.applyComponent(f, 0, header);      < size the header per the plan >
     int list = uiScrolledView(box, 1, 1);
     d.applyComponent(f, 1, list);        < flexible -> expands >
     int footer = uiButton(box, "Close");
     d.applyComponent(f, 2, footer);
   >>
#sleela 2.5
material;
< Family: ui. Realizes a planned SLLayoutFrame onto native ui* widgets. >
class SLLayoutDriver {
  < ---- 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. >>
  String metaVersion = "1.0.0";
  int metaId = 11608;
  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; }

  < uiBox orientation ordinals (mirror SLUIOrientation in the toolkit C ABI). >
  < NOTE the mapping: SLStackLayout.isRow() == true means a horizontal row. >
  < ORIENT_VERTICAL = uiBox vertical (a column); ORIENT_HORIZONTAL = a row. >
  static final int ORIENT_VERTICAL   = 0;
  static final int ORIENT_HORIZONTAL = 1;

  < SLLayoutFrame layout-kind ordinals (mirror SLLayoutFrame.LAYOUT_*). >
  static final int LAYOUT_STACK = 0;
  static final int LAYOUT_GRID  = 1;

  < uiWidgetAlign ordinal for "stretch to fill" (mirror SLUIAlign.FILL). >
  static final int ALIGN_FILL = 3;

  < the last native container handle this driver created (-1 = none) >
  int lastContainer;

  void create() { lastContainer = -1; }

  < The native container handle produced by the most recent realize* call. >
  int container() { return lastContainer; }

  < ---- realize a planned Frame as a native container ---------------------- >
  << Create the native container (uiBox for a stack, uiGrid for a grid) that
     reproduces the Frame's planned layout, parented under `parentHandle`
     (typically a window root from uiWindowRoot). Returns the native container
     handle, or -1 if the Frame is null / not placed / the parent is invalid.
     The caller then creates each real control parented INTO this handle, in the
     same order the components were add()ed to the Frame, and calls
     applyComponent() on each. >>
  int realize(int parentHandle, SLLayoutFrame frame) {
    if (parentHandle < 0 || frame == null) { return -1; }
    if (!frame.isPlaced()) { return -1; }
    if (frame.getLayoutKind() == LAYOUT_GRID) {
      return realizeGrid(parentHandle, frame);
    }
    return realizeStack(parentHandle, frame);
  }

  << Realize a STACK (column/row) Frame as a native uiBox with the same
     orientation and gap. Returns the box handle (also stored as container()). >>
  int realizeStack(int parentHandle, SLLayoutFrame frame) {
    if (parentHandle < 0 || frame == null) { return -1; }
    int orient = frame.isRowLayout() ? ORIENT_HORIZONTAL : ORIENT_VERTICAL;
    int box = uiBox(parentHandle, orient, frame.getGap());
    lastContainer = box;
    return box;
  }

  << Realize a GRID Frame as a native uiGrid with the same column count and
     gap. Returns the grid handle (also stored as container()). >>
  int realizeGrid(int parentHandle, SLLayoutFrame frame) {
    if (parentHandle < 0 || frame == null) { return -1; }
    int grid = uiGrid(parentHandle, frame.getColumns(), frame.getGap());
    lastContainer = grid;
    return grid;
  }

  < ---- size each real child to match the plan ---------------------------- >
  << Apply the Frame's planned rectangle for component `index` to the native
     widget `childHandle`: request the planned pixel size as the widget's
     minimum, and — for a flexible component (planned to grow) — mark it to
     expand and fill so the toolkit lets it share leftover space exactly as the
     planner intended. Safe no-op if arguments are out of range. >>
  void applyComponent(SLLayoutFrame frame, int index, int childHandle) {
    if (frame == null || childHandle < 0) { return; }
    SLLayoutBox box = frame.boxAt(index);
    if (box == null) { return; }
    int w = box.getWidth();
    int h = box.getHeight();
    if (w < 0) { w = 0; }
    if (h < 0) { h = 0; }
    uiWidgetSizeRequest(childHandle, w, h);
    if (isFlexibleComponent(frame, index)) {
      < grow with the container and stretch across the cross axis >
      boolean row = frame.isRowLayout();
      uiWidgetExpand(childHandle, row ? 1 : 0, row ? 0 : 1);
      uiWidgetAlign(childHandle, ALIGN_FILL, ALIGN_FILL);
    }
    < realize the component's QUALITY: the parts the toolkit honors per widget. >
    applyQuality(frame.qualityAt(index), childHandle);
  }

  < ---- realize a component's QUALITY on a native widget ------------------- >
  << Apply the quality descriptor's honorable parts to the live widget: the
     single PRIMARY action becomes the toolkit's suggested (accent) action; a
     DANGER action becomes destructive; a non-interactive component is greyed
     out; a hidden component is removed from view (uiWidgetVisible); a component
     with a margin gets per-edge breathing room (uiWidgetMargin); a component
     with an icon gets a leading symbol/asset (uiWidgetSetIcon). The theme ROLE
     (body/surface/chrome/accent) is a hint the themed renderer uses when drawing
     the surface; the toolkit has no per-widget surface call, so role is honored
     through the window theme, not forced here. Every honored part maps 1:1 to a
     real ui* bridge call. Safe no-op for a null quality or an invalid handle. >>
  void applyQuality(SLComponentQuality q, int childHandle) {
    if (q == null || childHandle < 0) { return; }
    uiWidgetSuggested(childHandle, q.isPrimary() ? 1 : 0);
    uiWidgetDestructive(childHandle, q.isDanger() ? 1 : 0);
    uiWidgetSensitive(childHandle, q.isInteractive() ? 1 : 0);
    < visibility: a hidden component is not drawn and takes no space. >
    uiWidgetVisible(childHandle, q.isVisible() ? 1 : 0);
    < margin: per-edge breathing room around the component, only when asked. >
    if (q.hasMargin()) {
      uiWidgetMargin(childHandle, q.getMarginTop(), q.getMarginRight(),
        q.getMarginBottom(), q.getMarginLeft());
    }
    < icon: an optional leading symbol and/or asset path. >
    if (q.hasIcon()) {
      uiWidgetSetIcon(childHandle, q.getIconAsset(), q.getIconSymbol());
    }
  }

  << Apply the plan to a named component (convenience over applyComponent by
     index). >>
  void applyNamed(SLLayoutFrame frame, String name, int childHandle) {
    if (frame == null) { return; }
    applyComponent(frame, frame.indexOf(name), childHandle);
  }

  < A component is "flexible" when the Frame planned it to grow (stack size 0). >
  < Grid cells are never flagged flexible here; the grid itself sizes cells. >
  boolean isFlexibleComponent(SLLayoutFrame frame, int index) {
    if (frame == null) { return false; }
    if (frame.getLayoutKind() == LAYOUT_GRID) { return false; }
    return frame.isFlexibleAt(index);
  }

  boolean honored() {
    return (lastContainer >= 0 || lastContainer == -1)
      && ORIENT_VERTICAL == 0 && ORIENT_HORIZONTAL == 1;
  }
}