SLGuiScrollbar.sleela
lib/gui/version-dual/SLGuiScrollbar.sleela · 191 line(s) · sleela
<< lib/gui/version-dual/SLGuiScrollbar.sleela
SLeeLa Standard Library Definition.
Definition: Defines SLGuiScrollbar โ the IMPLIED scrollbar
model for a scrolled surface, in BOTH axes (vertical and horizontal). It is
a pure model: given a viewport extent and the content extent on an axis, it
decides whether a scrollbar is IMPLIED (content overflows the viewport),
and computes the two normalized [0,1] values the toolkit's drawn scroll bar
needs โ `page` (the fraction of content the viewport shows, i.e. the thumb
size) and `value` (the thumb position from the current scroll offset). It
also resolves a visibility policy (auto / always / never) so a host can
show the bar only when scrolling is actually implied. SLeeLa owns the
geometry + policy; the host paints it with `uiScrollBar(parent, orient,
value, page)` and feeds scroll gestures back through `scrollBy` / `scrollTo`.
Family: gui. The companion of SLGuiLayout for overflow; the drawn bar is the
existing SleelaUI scroll-bar control โ this class is the implied geometry. >>
#sleela 2.5
material;
class SLGuiScrollbar {
< ---- 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 = 11389;
String metaAuthor = "Kiro Agent";
String metaDate = "2026-10-19";
String metaCopyright = "SLeeLa project";
String metaTrademark = "none";
String metaCorporation = "none";
< metaOrigin: National | <nation> | International | Galactic >
String metaOrigin = "International";
String metaBirthDate = "2026-10-19";
< 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; }
< Axis ordinals (mirror SLUIOrientation: VERTICAL=0, HORIZONTAL=1). >
static final int AXIS_VERTICAL = 0;
static final int AXIS_HORIZONTAL = 1;
< Visibility policy for an implied scrollbar. >
< shown only while content overflows >
static final int SHOW_AUTO = 0;
< always shown (reserves the gutter) >
static final int SHOW_ALWAYS = 1;
< never shown (overflow still scrolls) >
static final int SHOW_NEVER = 2;
< AXIS_VERTICAL / AXIS_HORIZONTAL >
int axis;
< SHOW_* >
int policy;
< visible extent on this axis (px) >
int viewport;
< total content extent on this axis (px) >
int content;
< current scroll offset from the start (px), clamped >
int offset;
< drawn gutter thickness (px) >
int thicknessPx;
< Fixed-point scale for the normalized [0,1] value/page (SLeeLa ints only): >
< we report value/page in PERMILLE (0..1000) so callers can divide by 1000.0 >
< to get the [0,1] double the toolkit wants, with no float fields here. >
static final int UNIT = 1000;
int clamp(int v, int lo, int hi) {
if (v < lo) { return lo; }
if (v > hi) { return hi; }
return v;
}
< Install safe defaults for an axis; a zero/negative extent is treated as 0. >
void configure(int whichAxis, int viewportPx, int contentPx) {
axis = (whichAxis == AXIS_HORIZONTAL) ? AXIS_HORIZONTAL : AXIS_VERTICAL;
policy = SHOW_AUTO;
viewport = (viewportPx > 0) ? viewportPx : 0;
content = (contentPx > 0) ? contentPx : 0;
offset = 0;
thicknessPx = 12;
}
void setPolicy(int p) { if (p >= SHOW_AUTO && p <= SHOW_NEVER) { policy = p; } }
void setThickness(int px) { if (px > 0) { thicknessPx = clamp(px, 4, 64); } }
< The host reports a new viewport (on resize) and/or content (on relayout). >
void setViewport(int px) { if (px > 0) { viewport = px; } clampOffset(); }
void setContent(int px) { content = (px > 0) ? px : 0; clampOffset(); }
< The maximum scrollable offset (0 when content fits the viewport). >
int maxOffset() {
int over = content - viewport;
return (over > 0) ? over : 0;
}
void clampOffset() { offset = clamp(offset, 0, maxOffset()); }
< ---- scroll gestures (the host raises these) ---------------------------- >
void scrollTo(int px) { offset = clamp(px, 0, maxOffset()); }
void scrollBy(int deltaPx) { scrollTo(offset + deltaPx); }
void scrollToStart() { offset = 0; }
void scrollToEnd() { offset = maxOffset(); }
< ---- the IMPLIED decision ----------------------------------------------- >
< Scrolling is implied exactly when the content overflows the viewport. >
boolean overflow() { return content > viewport && viewport > 0; }
< Should the drawn bar be shown, given the policy? >
boolean implied() {
if (policy == SHOW_ALWAYS) { return true; }
if (policy == SHOW_NEVER) { return false; }
< SHOW_AUTO >
return overflow();
}
< ---- normalized geometry for uiScrollBar(parent, orient, value, page) ---- >
< page = fraction of content currently visible (thumb size), in [0,1]. >
int pagePermille() {
< nothing to scroll >
if (content <= 0 || viewport <= 0) { return UNIT; }
if (viewport >= content) { return UNIT; }
return clamp((viewport * UNIT) / content, 1, UNIT);
}
< value = thumb position from the scroll offset, in [0,1]. >
int valuePermille() {
int mx = maxOffset();
if (mx <= 0) { return 0; }
return clamp((offset * UNIT) / mx, 0, UNIT);
}
< Convenience: scaled to an arbitrary resolution (e.g. 100 for a percent). >
int pageScaled(int scale) { return (pagePermille() * scale) / UNIT; }
int valueScaled(int scale) { return (valuePermille() * scale) / UNIT; }
< ---- readers ------------------------------------------------------------ >
int getAxis() { return axis; }
int getOffset() { return offset; }
int getViewport() { return viewport; }
int getContent() { return content; }
int getThickness() { return thicknessPx; }
int getPolicy() { return policy; }
< the SLUIOrientation to pass >
int orient() { return axis; }
String axisName() { return (axis == AXIS_HORIZONTAL) ? "horizontal" : "vertical"; }
String policyName() {
if (policy == SHOW_ALWAYS) { return "always"; }
if (policy == SHOW_NEVER) { return "never"; }
return "auto";
}
< Internally consistent: non-negative extents, offset within range, and a >
< page/value pair that stay inside [0,1]. >
boolean honored() {
if (viewport < 0 || content < 0 || offset < 0) { return false; }
if (offset > maxOffset()) { return false; }
int p = pagePermille(); int v = valuePermille();
return p >= 0 && p <= UNIT && v >= 0 && v <= UNIT;
}
String report() {
return axisName() + " scrollbar: viewport=" + viewport + "px content=" + content
+ "px offset=" + offset + "px (max " + maxOffset() + ") "
+ "implied=" + implied() + " policy=" + policyName()
+ " value=" + valuePermille() + "/1000 page=" + pagePermille() + "/1000";
}
}