Home /Modules/user-interface/SLLoadingIndicator.sleela

SLLoadingIndicator.sleela

lib/user-interface/SLLoadingIndicator.sleela · 239 line(s) · sleela

<< lib/user-interface/SLLoadingIndicator.sleela
   SLeeLa Standard Library Definition.
   Definition: Defines SLLoadingIndicator — a SleelaUI composite "loading"
     widget that unifies the three activity primitives behind one caption, with
     no new C ABI. It is a horizontal row of {activity visual, caption label}
     that switches between two modes:
       - INDETERMINATE (unknown length): shows an SLThrobber (the water-flow
         field) or an SLSpinner (the accent arc), advanced each frame by the
         window loop / a host phase;
       - DETERMINATE (known length): shows an SLProgressBar filled to a fraction
         in [0,1], with the caption optionally carrying a percentage.
     A task begins indeterminate ("Resolving…"), may switch to determinate once
     a total is known ("Compiling… 60%"), and ends with done()/fail() which hide
     the activity visual and set a final caption. This is the IDE-friendly
     loading indicator built from SLThrobber + SLSpinner + SLProgressBar.
   
   An SLLoadingIndicator IS an SLWidget container (its handle is the row box).
   
   Family: user-interface. Native VM/UI work crosses the explicit `ui*` SLVM
   bridge. >>
#sleela 2.5
material;
class SLLoadingIndicator extends SLWidget {
  < ---- 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 = 11073;
  String metaAuthor = "Kiro Agent";
  String metaDate = "2026-10-16";
  String metaCopyright = "SLeeLa project";
  String metaTrademark = "none";
  String metaCorporation = "none";
  < metaOrigin: National | <nation> | International | Galactic >
  String metaOrigin = "International";
  String metaBirthDate = "2026-10-13";
  < 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; }
  < Mode ordinals. >
  static final int MODE_IDLE          = 0;
  static final int MODE_INDETERMINATE = 1;
  static final int MODE_DETERMINATE   = 2;
  static final int MODE_DONE          = 3;
  static final int MODE_FAILED        = 4;

  < Which indeterminate visual to use. >
  < the water-flow field (default) >
  static final int STYLE_THROBBER = 0;
  < the accent arc on a ring >
  static final int STYLE_SPINNER  = 1;

  < horizontal: [visual] [caption] >
  SLBox row;
  < indeterminate (STYLE_THROBBER) >
  SLThrobber throbber;
  < indeterminate (STYLE_SPINNER) >
  SLSpinner spinner;
  < determinate >
  SLProgressBar bar;
  < the status text >
  SLLabel caption;

  < STYLE_THROBBER | STYLE_SPINNER >
  int style;
  int mode;
  < current determinate fraction [0,1] >
  double fraction;
  < current indeterminate phase [0,1] >
  double phase;
  < append " NN%" to the caption in determinate mode >
  boolean showPercent;
  < the caption text without any appended percentage >
  String baseCaption;

  < Create the indicator inside `parent`. style picks the indeterminate visual; >
  < visualWidth sizes the throbber (ignored for the spinner). >
  void createIn(SLWidget parent, int style0, int visualWidth) {
    style = style0;
    row = new SLBox();
    row.horizontal(parent, 10);
    widget = row.handle();

    < Build all three visuals once; show only the active one. >
    throbber = new SLThrobber();
    throbber.createIn(row, visualWidth > 0 ? visualWidth : 120);
    throbber.setSizeRequest(0, 6);
    throbber.setIntensity(0.6);
    < green water, matching the brand accent >
    throbber.setHue(150.0);

    spinner = new SLSpinner();
    spinner.createIn(row);

    bar = new SLProgressBar();
    bar.createIn(row, 0.0);
    bar.setExpand(true, false);

    caption = new SLLabel();
    caption.createIn(row, "");
    caption.setAlign(ALIGN_START, ALIGN_CENTER);

    mode = MODE_IDLE;
    fraction = 0.0; phase = 0.0; showPercent = true;
    applyMode();
  }

  < ---- lifecycle ---------------------------------------------------------- >

  < Begin an indeterminate task of unknown length. >
  void beginIndeterminate(String text) {
    mode = MODE_INDETERMINATE;
    setCaption(text);
    applyMode();
  }

  < Begin (or switch to) a determinate task; `initial` is the starting [0,1]. >
  void beginDeterminate(String text, double initial) {
    mode = MODE_DETERMINATE;
    setFraction(initial);
    setCaption(text);
    applyMode();
  }

  < Update determinate progress; clamps to [0,1] and refreshes the caption. >
  void setFraction(double value) {
    fraction = clamp01(value);
    if (bar.valid()) { bar.setFraction(fraction); }
    if (mode == MODE_DETERMINATE) { refreshCaption(); }
  }
  double getFraction() { return fraction; }

  < Advance the indeterminate visual (host calls this each frame; phase wraps). >
  void tick(double delta) {
    phase = phase + delta;
    while (phase >= 1.0) { phase = phase - 1.0; }
    if (mode == MODE_INDETERMINATE && style == STYLE_SPINNER && spinner.valid()) {
      spinner.setPhase(phase);
    }
    < The throbber animates itself from the window frame loop; nothing to push. >
  }

  < Finish successfully: hide the activity visual, set a final caption. >
  void done(String text) {
    mode = MODE_DONE;
    if (text != null) { setCaption(text); }
    applyMode();
  }

  < Finish with an error: hide the activity visual, set a failure caption. >
  void fail(String text) {
    mode = MODE_FAILED;
    if (text != null) { setCaption(text); }
    applyMode();
  }

  < Reset to idle (hidden). >
  void reset() {
    mode = MODE_IDLE; fraction = 0.0; phase = 0.0;
    if (bar.valid()) { bar.setFraction(0.0); }
    setCaption("");
    applyMode();
  }

  < ---- query -------------------------------------------------------------- >

  int currentMode() { return mode; }
  boolean busy() { return mode == MODE_INDETERMINATE || mode == MODE_DETERMINATE; }
  boolean finished() { return mode == MODE_DONE || mode == MODE_FAILED; }
  boolean failed() { return mode == MODE_FAILED; }

  < Choose the indeterminate visual (throbber vs spinner) at any time. >
  void setStyle(int style0) { style = style0; applyMode(); }

  < Whether to append a percentage to the determinate caption. >
  void setShowPercent(boolean on) { showPercent = on; refreshCaption(); }

  < Set the base caption text (without any appended percentage). >
  void setCaption(String text) { baseCaption = (text == null) ? "" : text; refreshCaption(); }

  < ---- internals ---------------------------------------------------------- >

  < Show exactly the visual the current mode needs; hide the rest. >
  void applyMode() {
    boolean indet = (mode == MODE_INDETERMINATE);
    boolean det   = (mode == MODE_DETERMINATE);
    if (throbber.valid()) { throbber.setVisible(indet && style == STYLE_THROBBER); }
    if (spinner.valid())  { spinner.setVisible(indet && style == STYLE_SPINNER); }
    if (bar.valid())      { bar.setVisible(det); }
    refreshCaption();
  }

  < Rebuild the caption, appending " NN%" in determinate mode when enabled. >
  void refreshCaption() {
    if (caption == null || !caption.valid()) { return; }
    String text = (baseCaption == null) ? "" : baseCaption;
    if (mode == MODE_DETERMINATE && showPercent) {
      text = text + "  " + percentText(fraction) + "%";
    }
    caption.setText(text);
  }

  < fraction[0,1] -> integer percent 0..100 without a float->int cast. >
  String percentText(double f) {
    double v = clamp01(f);
    int p = 0;
    double acc = 0.0;
    while (acc + 0.01 <= v && p < 100) { acc = acc + 0.01; p = p + 1; }
    return "" + p;
  }

  double clamp01(double v) { if (v < 0.0) { return 0.0; } if (v > 1.0) { return 1.0; } return v; }
}