Home /Modules/ui/SLComponentQuality.sleela

SLComponentQuality.sleela

lib/ui/SLComponentQuality.sleela · 227 line(s) · sleela

<< lib/ui/SLComponentQuality.sleela
   SLeeLa Standard Library Definition.
   Definition: SLComponentQuality — the per-COMPONENT QUALITY descriptor that
     completes the standard layout model. A layout already gives every component
     its exact SIZE and pixel-perfect PLACEMENT (SLLayoutBox: x/y/w/h); this
     class gives every component its intended QUALITY: which theme role it reads
     as, how strongly it is emphasised, and whether it is currently interactive.
     So a component is fully described by QUALITY + SIZE + PLACEMENT.

   Quality is expressed in the vocabulary the standard themes already define
   (SLStandardTheme's role tokens), so it maps cleanly to a flavor (blue / gray
   / black / white) and to what the native toolkit can honor per widget:
     - ROLE   : which surface/text the renderer draws the component as --
                BODY (default content), SURFACE (a raised panel), CHROME
                (title/menu bar), or ACCENT (the one interactive accent).
     - EMPHASIS: NORMAL, PRIMARY (the single suggested action -> the toolkit's
                uiWidgetSuggested), or DANGER (destructive -> uiWidgetDestructive).
     - interactive: whether the component is enabled (sensitive) right now
                (-> uiWidgetSensitive).
     - visible   : whether the component is shown or hidden right now
                (-> uiWidgetVisible). A hidden component takes no space.
     - margin    : per-edge breathing room around the component in px
                (-> uiWidgetMargin).
     - icon      : an optional leading symbol/asset for the component
                (-> uiWidgetSetIcon).

   Pure SLeeLa (no native handle); it always checks and runs. The native
   realizer (SLLayoutDriver) reads a component's quality and applies every part
   the toolkit can honor per widget (emphasis, sensitivity, visibility, margin,
   icon); the role is a hint the themed renderer uses when it draws the surface.
   Each new axis maps 1:1 to a real ui* bridge call, so the count of quality
   aspects the standard model can faithfully deliver grows without inventing any
   capability the native toolkit lacks. >>
#sleela 2.5
material;
< Family: ui. Per-component quality: role + emphasis + interactivity. >
class SLComponentQuality {
  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  << Eleven catalogued attributes with getter/setter pairs. >>
  String metaVersion = "1.0.0";
  int metaId = 11609;
  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; }

  < ROLE: which theme surface/text the component reads as. >
  static final int ROLE_BODY    = 0;
  static final int ROLE_SURFACE = 1;
  static final int ROLE_CHROME  = 2;
  static final int ROLE_ACCENT  = 3;

  < EMPHASIS: normal, the single primary action, or a destructive action. >
  static final int EMPHASIS_NORMAL  = 0;
  static final int EMPHASIS_PRIMARY = 1;
  static final int EMPHASIS_DANGER  = 2;

  int role;
  int emphasis;
  < 1 = enabled/interactive, 0 = disabled (greyed out) >
  int interactive;
  < 1 = shown, 0 = hidden. A hidden component takes no space and is not drawn. >
  int visible;
  < Margin (breathing room) around the component, in px, per edge. >
  int marginTop;
  int marginRight;
  int marginBottom;
  int marginLeft;
  < Optional leading icon: a named theme symbol (e.g. "save", "trash") and/or an >
  < asset path. Empty strings mean "no icon". >
  String iconSymbol;
  String iconAsset;

  < Default quality: body role, no emphasis, interactive, shown, no margin, >
  < no icon. >
  void create() {
    role = ROLE_BODY;
    emphasis = EMPHASIS_NORMAL;
    interactive = 1;
    visible = 1;
    marginTop = 0;
    marginRight = 0;
    marginBottom = 0;
    marginLeft = 0;
    iconSymbol = "";
    iconAsset = "";
  }

  < ---- role (fluent one-call setters, beginner-friendly) ------------------ >
  void asBody()    { role = ROLE_BODY; }
  void asSurface() { role = ROLE_SURFACE; }
  void asChrome()  { role = ROLE_CHROME; }
  void asAccent()  { role = ROLE_ACCENT; }
  void setRole(int r) { if (r >= ROLE_BODY && r <= ROLE_ACCENT) { role = r; } }
  int getRole() { return role; }

  < ---- emphasis ----------------------------------------------------------- >
  void normal()  { emphasis = EMPHASIS_NORMAL; }
  void primary() { emphasis = EMPHASIS_PRIMARY; }
  void danger()  { emphasis = EMPHASIS_DANGER; }
  void setEmphasis(int e) { if (e >= EMPHASIS_NORMAL && e <= EMPHASIS_DANGER) { emphasis = e; } }
  int getEmphasis() { return emphasis; }
  boolean isPrimary() { return emphasis == EMPHASIS_PRIMARY; }
  boolean isDanger()  { return emphasis == EMPHASIS_DANGER; }

  < ---- interactivity ------------------------------------------------------ >
  void enable()  { interactive = 1; }
  void disable() { interactive = 0; }
  void setInteractive(boolean on) { interactive = on ? 1 : 0; }
  boolean isInteractive() { return interactive == 1; }

  < ---- visibility --------------------------------------------------------- >
  < A hidden component is not drawn and (in a stack) collapses to take no space; >
  < the native realizer honors it with uiWidgetVisible. >
  void show() { visible = 1; }
  void hide() { visible = 0; }
  void setVisible(boolean on) { visible = on ? 1 : 0; }
  boolean isVisible() { return visible == 1; }

  < ---- margin (breathing room around the component, per edge, in px) ------ >
  < Uniform margin on all four edges. >
  void margin(int px) {
    int m = (px < 0) ? 0 : px;
    marginTop = m; marginRight = m; marginBottom = m; marginLeft = m;
  }
  < Independent per-edge margins (negatives clamped to 0). >
  void setMargins(int top, int right, int bottom, int left) {
    marginTop    = (top < 0) ? 0 : top;
    marginRight  = (right < 0) ? 0 : right;
    marginBottom = (bottom < 0) ? 0 : bottom;
    marginLeft   = (left < 0) ? 0 : left;
  }
  int getMarginTop()    { return marginTop; }
  int getMarginRight()  { return marginRight; }
  int getMarginBottom() { return marginBottom; }
  int getMarginLeft()   { return marginLeft; }
  < True when any edge has a non-zero margin. >
  boolean hasMargin() {
    return marginTop > 0 || marginRight > 0 || marginBottom > 0 || marginLeft > 0;
  }

  < ---- icon (optional leading symbol / asset) ----------------------------- >
  < Set a named theme symbol (e.g. "save", "trash", "search"). >
  void icon(String symbol) { iconSymbol = (symbol == null) ? "" : symbol; }
  < Set an asset-path icon (e.g. a file the host loads). >
  void iconFromAsset(String assetPath) { iconAsset = (assetPath == null) ? "" : assetPath; }
  < Clear any icon. >
  void clearIcon() { iconSymbol = ""; iconAsset = ""; }
  String getIconSymbol() { return iconSymbol; }
  String getIconAsset()  { return iconAsset; }
  < True when a symbol or asset icon has been set. >
  boolean hasIcon() {
    return (iconSymbol != null && iconSymbol != "")
        || (iconAsset != null && iconAsset != "");
  }

  < The role name, in the theme's own vocabulary. >
  String roleName() {
    if (role == ROLE_SURFACE) { return "surface"; }
    if (role == ROLE_CHROME)  { return "chrome"; }
    if (role == ROLE_ACCENT)  { return "accent"; }
    return "body";
  }
  < The emphasis name. >
  String emphasisName() {
    if (emphasis == EMPHASIS_PRIMARY) { return "primary"; }
    if (emphasis == EMPHASIS_DANGER)  { return "danger"; }
    return "normal";
  }

  < A one-line account of the quality, for logs/inspection. >
  String describe() {
    String s = "quality:" + roleName() + "/" + emphasisName()
      + (interactive == 1 ? "/enabled" : "/disabled")
      + (visible == 1 ? "/shown" : "/hidden");
    if (hasMargin()) {
      s = s + "/margin[" + marginTop + "," + marginRight + ","
        + marginBottom + "," + marginLeft + "]";
    }
    if (hasIcon()) {
      s = s + "/icon(" + (iconSymbol != "" ? iconSymbol : iconAsset) + ")";
    }
    return s;
  }

  boolean honored() {
    return role >= ROLE_BODY && role <= ROLE_ACCENT
      && emphasis >= EMPHASIS_NORMAL && emphasis <= EMPHASIS_DANGER
      && (interactive == 0 || interactive == 1)
      && (visible == 0 || visible == 1)
      && marginTop >= 0 && marginRight >= 0
      && marginBottom >= 0 && marginLeft >= 0
      && iconSymbol != null && iconAsset != null;
  }
}