lib/user-interface — Building a Graphical Interface from SLeeLa
This package lets a SLeeLa program open a real native window and build a
graphical user interface — on Windows, macOS, or Linux/Unix — using SleelaUI™,
SLeeLa's own, original cross-platform UI toolkit (not GTK, Qt, or a wrapper).
A developer writes ui.openWindow(...), box.vertical(...), button.createIn(...),
and the SLeeLa VM makes the genuine SleelaUI C ABI call for whatever OS the
program is running on:
SLeeLa source (lib/user-interface/SL*.sleela)
-> ui* built-ins uiAppCreate / uiWindowCreate / uiButton / ...
-> SLVM opcodes OP_UI_* (sleela_core.c dispatch)
-> SleelaUI C ABI include/sleela_ui.h (user-interface/)
-> native backend X11 (Xlib) / Cocoa (AppKit) / Win32 (GDI)
The same .sleela program is portable: it calls one named built-in and the VM
selects the X11, Cocoa, or Win32 backend at the native layer. The toolkit draws
its own widgets with its own software rasterizer, so the signature Slick
Black look is pixel-identical on all three desktops. The native toolkit, its
backends, theme, and documentation live under /user-interface.
Boundary — honesty note. These calls cross the explicit VM/UI bridge the same way the rest of the standard library does (sockets, files, time, the
os*bridge in/lib/os). A window, widget, theme, or application is a VM-local bounded handle, never a rawHWND,NSWindow*, X11Window, or C++ pointer — the same safety discipline used everywhere in the VM. Theui*built-ins require#sleela 1.5.
The SLVM UI built-in surface
The VM exposes these built-ins (lowered to OP_UI_* opcodes, serviced by the
SleelaUI C ABI in user-interface/include/sleela_ui.h). Every backend
implements the same surface.
| Built-in | Effect | SleelaUI C ABI |
|---|---|---|
uiBackend() → int | Live backend id (1 Win32 / 2 Cocoa / 3 X11) | slui_backend |
uiBackendName(id) → String | "win32"/"cocoa"/"x11" | slui_backend_name |
uiVersion() → String | Toolkit version string | slui_version_string |
uiAppCreate(id) → int | Open the application; VM-local handle (-1 fail) | slui_app_create |
uiAppDestroy(app) | Release the application and its windows | slui_app_destroy |
uiAppPump(app,block) → int | Dispatch pending events once | slui_app_pump |
uiAppRun(app) → int | Run the event loop; return the exit code | slui_app_run |
uiAppQuit(app,code) | Ask the loop to stop | slui_app_quit |
uiWindowCreate(app,title,w,h,theme) → int | Open a window; VM-local handle | slui_window_create |
uiWindowShow/Hide(win) | Map / unmap the window | slui_window_show/_hide |
uiWindowClosed(win) → int | 1 once the user closed the window (X button), else 0 | slui_window_closed |
uiWindowSetTitle(win,title) | Set the title | slui_window_set_title |
uiWindowRoot(win) → int | The root container widget handle | slui_window_root |
uiWindowSetTheme(win,theme) | Swap the palette live | slui_window_set_theme |
uiWindowRedraw(win) | Request a repaint | slui_window_request_redraw |
uiBox(parent,orient,spacing) → int | A vertical/horizontal box | slui_box |
uiHeaderBar(parent) → int | A title-bar strip | slui_header_bar |
uiLabel(parent,text) → int | A text label | slui_label |
uiButton(parent,text) → int | A push button | slui_button |
uiWidgetSetIcon(widget,path,symbol) | Add a JPEG icon with a named vector fallback (for example, Wifi) | slui_widget_set_icon |
uiToggle(parent,text,on) → int | A toggle switch | slui_toggle |
uiEntry(parent,placeholder) → int | A single-line text field | slui_entry |
uiSlider(parent,min,max,val) → int | A slider | slui_slider |
uiSeparator(parent,orient) → int | A hairline rule | slui_separator |
uiSpacer(parent) → int | A flexible expanding gap | slui_spacer |
uiCheckBox(parent,text,on) → int | A labelled check box | slui_check_box |
uiRadioButton(parent,text,group,on) → int | A grouped radio button | slui_radio_button |
uiComboBox(parent) → int | A drop-down selection | slui_combo_box |
uiComboBoxAdd(combo,option) | Append a combo option | slui_combo_box_add |
uiSpinButton(parent,min,max,step,val) → int | A numeric spin button | slui_spin_button |
uiProgressBar(parent,frac) → int | A determinate progress bar | slui_progress_bar |
uiLevelBar(parent,frac) → int | A segmented level bar | slui_level_bar |
uiSpinner(parent) → int | An indeterminate activity spinner | slui_spinner |
uiScrollBar(parent,orient,val,page) → int | A scroll bar indicator | slui_scroll_bar |
uiFrame(parent,title) → int | A titled bordered container | slui_frame |
uiCard(parent) → int | A raised surface panel | slui_card |
uiPopupCreate(parent) → int | A hidden floating overlay card (menu/dropdown); painted last, above the frame, with a drop shadow + raised 3D face | slui_popup_create |
uiPopupSetOpen(popup,open) | Show (1) / dismiss (0) the popup | slui_popup_set_open |
uiPopupIsOpen(popup) → int | 1 while the popup is open | slui_popup_is_open |
uiPopupSetAnchor(popup,topLeft,x) | Place the overlay: topLeft=1 anchors below the top strip (a menubar dropdown), x>=0 fixes its left edge under its button; default is lower-right | slui_popup_set_anchor |
uiPopupAnchorTo(popup,trigger) | Center the popup on a trigger widget (exact, from its laid-out rect) and draw a teardrop caret pointing up at it — the way a menu dropdown sits under its button | slui_popup_anchor_to |
uiGrid(parent,cols,spacing) → int | A row/column grid | slui_grid |
uiStatusBar(parent) → int | A footer status strip | slui_status_bar |
uiImage(parent,src,w,h) → int | Image tile; src is a file path — decodes & renders real JPEG (always) / PNG, AVIF (when linked); a non-file string shows a captioned tile. Re-decoded on uiWidgetSetText. | slui_image |
uiAvatar(parent,initial,d) → int | A round avatar | slui_avatar |
uiBadge(parent,text) → int | A count/status pill | slui_badge |
uiChip(parent,text) → int | A tag / chip pill | slui_chip |
uiHeading(parent,text,size) → int | A large title label | slui_heading |
uiTooltip(parent,text) → int | A tooltip bubble | slui_tooltip |
uiLinkButton(parent,text) → int | A hyperlink-style button | slui_link_button |
uiSearchEntry(parent,ph) → int | A search field | slui_search_entry |
uiPasswordEntry(parent,ph) → int | A masked password field | slui_password_entry |
uiInfoBar(parent,text,severity) → int | An inline notice bar | slui_info_bar |
uiWidgetMargin(w,t,r,b,l) | Set margins | slui_widget_set_margin |
uiWidgetAlign(w,h,v) | Set alignment | slui_widget_set_align |
uiWidgetExpand(w,h,v) | Set expansion | slui_widget_set_expand |
uiWidgetSizeRequest(w,mw,mh) | Minimum size | slui_widget_set_size_request |
uiWidgetSensitive(w,on) | Enable / grey out | slui_widget_set_sensitive |
uiWidgetVisible(w,on) | Show / hide | slui_widget_set_visible |
uiWidgetSetText(w,text) / uiWidgetGetText(w) | Text accessor | slui_widget_set/get_text |
uiWidgetSetToggle(w,on) / uiWidgetGetToggle(w) | Toggle state | slui_widget_set/get_toggle |
uiWidgetSetValue(w,v) / uiWidgetGetValue(w) | Slider value | slui_widget_set/get_value |
uiWidgetSuggested(w,on) / uiWidgetDestructive(w,on) | Accents | slui_widget_set_suggested/_destructive |
uiWidgetTakeActivated(w) → int | 1 once per activation (latch cleared on read) | activate callback latch |
uiThemePreset(id) → int | A theme filled from a preset; VM-local handle | slui_theme_preset |
uiThemeSet*(theme,color) | Set a role colour (0xRRGGBBAA) | SLUITheme fields |
uiThemeSetRadius/ControlHeight(theme,px) | Metrics | SLUITheme fields |
uiThemeSetFont(theme,family,size) | Typography | SLUITheme fields |
uiThemeDestroy(theme) | Release a theme handle | — |
The native toolkit uses C callbacks for activation; from SLeeLa the VM records each activation in a per-widget latch that
uiWidgetTakeActivatedreads and clears, so a SLeeLa program observes a click/flip/edit exactly once perpump()turn without needing function pointers.
The classes
Application and window
| Class | Role |
|---|---|
SLUserInterface | The capstone facade: create the application, report the live backend, open windows, run/pump/quit the event loop. |
SLWindow | A top-level native window: show/hide, title, its root container, live theme swap, redraw. |
Widgets
| Class | Role |
|---|---|
SLWidget | The base for every control: margins, alignment, expansion, size request, sensitivity, visibility, text, suggested/destructive accents. |
SLBox | A vertical/horizontal box container (GTK/CSS box layout). |
SLHeaderBar | A title-bar strip (chrome fill + bottom hairline). |
SLLabel | A non-interactive text label. |
SLButton | A push button, with suggested (accent) and destructive variants. |
SLToggle | A toggle switch with a trailing label. |
SLEntry | A single-line UTF-8 text field with a caret. |
SLSlider | A horizontal slider over a [min,max] range. |
SLSeparator | A 1px hairline rule. |
SLSpacer | A flexible expanding gap. |
SLCheckBox | A labelled check box with an accent tick. |
SLRadioButton | A grouped, mutually-exclusive radio button. |
SLComboBox | A drop-down selection control. |
SLSpinButton | A numeric value with − / + steppers over [min,max]. |
SLProgressBar | A determinate progress bar over [0,1]. |
SLLevelBar | A segmented level indicator over [0,1]. |
SLSpinner | An indeterminate activity spinner. |
SLScrollBar | A scroll bar with a draggable thumb. |
SLFrame | A titled, bordered group container. |
SLCard | A raised rounded surface panel. |
SLGrid | A fixed row/column grid container. |
SLStatusBar | A footer status strip. |
SLImage | An image/icon tile with a centred glyph. |
SLAvatar | A round accent avatar with an initial. |
SLBadge | A small accent count/status pill. |
SLChip | A rounded tag/filter pill. |
SLHeading | A large title label. |
SLTooltip | A small tooltip bubble. |
SLLinkButton | A hyperlink-style accent button. |
SLSearchEntry | An entry with a leading search glyph. |
SLPasswordEntry | An entry that masks its characters. |
SLInfoBar | An inline info/warning/error notice bar. |
| SLThrobber | A width-adjustable, water-like flowing, colour-predictive activity field. |
| SLCanvasView | A general animated drawing surface driven by a per-frame draw routine. |
Composite / data widgets
These are built entirely in SLeeLa from the primitives above (they add no new C ABI). They are the data and container widgets a document application — such as an IDE — needs, so a complete GUI can be authored in SLeeLa alone.
| Class | Role | Composed from |
|---|---|---|
SLScrollView | A scrollable, clipping viewport; children build into its contentArea(). | SLFrame + SLBox + SLScrollBar |
SLTreeView | A hierarchical tree with depth indentation, expand/collapse, and selection. | SLScrollView + SLLabel rows |
SLNotebook | A tabbed container: a tab strip over a one-page-visible content stack, with per-tab dirty markers. | SLBox + SLButton tabs |
SLTextView | A multi-line editable code editor: line buffer, caret, selection, dirty flag, gutter line numbers, current-line highlight, drawn via the Draw API. | SLCanvasView + SLDrawContext |
SLLoadingIndicator | A unified loading indicator with a caption that switches between indeterminate (throbber/spinner) and determinate (progress bar) modes, with done()/fail() end states. | SLThrobber + SLSpinner + SLProgressBar |
Events, DHTML-style DOM, and scripting
The backing API for dynamic interfaces — action callbacks / onClick, a
browser-DOM-style document with live manipulation, a small scripting engine, and
the support structure that projects the DOM onto real widgets and feeds
activations back. SLeeLa owns the meaning of events and the document; the
toolkit renders it. (These classes are maintained in parallel with the
identical set in /lib/gui; see
/lib/gui/EVENTS-DOM-SCRIPTING.md for the full
contract and runnable walkthroughs.)
| Class | Role |
|---|---|
SLGuiEventType | The event catalogue (click, input, change, keydown, toggle, submit, custom, …) with ordinals ↔ names. |
SLGuiEvent | A dispatched event with a value/key/pointer payload and preventDefault/stopPropagation. |
SLGuiHandler | A bound callback (type, target, operation) with once/capture and a take-the-latch activation. |
SLGuiEventBus | The dispatcher: addEventListener/removeEventListener, phased capture → bubble dispatch, once sweeping. |
SLGuiNode | A DOM element: tag/id/text, parent + children, an attribute map, an inline style map, visibility/enabled, a live widget handle. |
SLGuiDom | The document: getElementById, createElement, appendChild, setText/setAttribute/setStyle, show/hide, onClick/onInput/… |
SLGuiScriptCommand | One script instruction (verb + operands). |
SLGuiScript | The bounded command-list engine that drives the DOM/events. |
SLGuiWidgetFactory | Maps a node tag → a SleelaUI constructor (the DOM→toolkit seam). |
SLGuiMount | The reconciler: depth-first mount, id → widget map, applies dirty-node state to widgets. |
SLGuiHostAdapter | Polls widget activation latches and raises the matching SLGuiEvents into the bus. |
SLGuiApp | The top-level support object: app + window + DOM + mount + host adapter + script engine + run loop. |
The full catalogue — every widget with its C ABI constructor, SLeeLa class, description, and focus behaviour — is tabulated in
user-interface/WIDGETS.DESCRIPTION.md.
Drawing (the Draw API)
| Class | Role |
|---|---|
SLDrawContext | The comprehensive 2D draw surface: owned RGBA buffers, single/double buffering, pixel-level get/set/blend, blend modes, a clip stack, and all primitives (rects, rounded rects, lines, circles, ellipses, arcs, triangles, gradients, text, blits). |
SLFrameClock | Refresh-rate control for a render loop: target FPS, per-frame delta, elapsed time, measured rate, sleep hint, and a fixed-timestep accumulator. |
The Draw API is documented in full at
user-interface/DRAW-API.md, and the water throbber model atuser-interface/THROBBER.md.
Lighting, shadow & relief
| Class | Role |
|---|---|
SLLight | A light descriptor: kind (point/directional/ambient), role (SOURCE reserves its anchor object; EMITTER reserves nothing), polarity (LIGHT brightens / SHADOW darkens), position/direction, reach, intensity, softness, colour. |
SLLightScene | A collection of lights applied to a draw context; owns the source-reservation table (an anchor is used as a source at most once) and the base ambient fill. |
SLMaterial | How an object catches light: a relief profile (flat/rounded/bevel/engraved/embossed) plus depth, gloss, and crease occlusion — the "quality relief". |
The lighting model — sources vs emitters, light vs shadow emissions, and the relief profiles — is documented at
user-interface/LIGHTING.md.
Layout & flow manager
| Class | Role |
|---|---|
SLMeasure | A standardized unit of measurement across US customary (in/ft/pt/pica), Eurasian metric (mm/cm/m), device px, and relative (%/fr/em); resolves to pixels at a DPI. |
SLLayout | A flow/layout manager: named groups of named items, adjusted singly, by group, or n-ary; several flow solutions (stack, wrap, grid, dock, central weight/mass); Named placement (MEDIUM = center, CENTRAL = weight/mass) and named ergonomic presets. |
The layout manager — the orthogonal conflation of unit parts and organizations, the flows, named placement, and the ergonomics of publics — is documented at
user-interface/LAYOUT.md.
Moods, washes, Calculus-8 & millimetre placement
| Class | Role |
|---|---|
SLMm | Millimetre placement for a light/dark/shadow emitter relative to the text's font-paint location: left/right, up/down, and the HEIGHT it shines down from; converts to pixels at a DPI. |
SLCalculus8 | The careful 8-stage calculus with 100 differentiable inputs that maps a light's control points into a mood scalar; slope() gives d(mood)/d(input) (differentiable). |
SLWash | An Excellent Wash: a soft, multi-stop graded colour field (smoothstep-sampled) that paints a mood. |
SLMood | A named, adjustable mood = a wash + a natural tanor (portrait glow for lightless bulbs, with a refresh and an "a little left" bias) + a Calculus-8; colours and places lights in one call. |
Millimetre placement, the Calculus-8, Excellent Washes, the natural tanor, and moods are documented at
user-interface/MOODS.md.
Fonts & font effects
| Class | Role |
|---|---|
SLFont | A font for Sleela's UI: face (family/size/weight/slant/spacing/line-height) + an effect stack + a quality level; draws into an SLDrawContext and attaches to a text widget via SLWidget.setFont. |
SLFontEffect | One effect: drop/inner shadow, glow, light sheen, EMITTER (text that radiates into a light scene — pure emitter or anchored source), outline, relief emboss/engrave, or gradient fill. |
The font model and effects are documented at
user-interface/FONTS.md.
Theme
| Class | Role |
|---|---|
SLTheme | A palette handle. Choose DEFAULT, WHITE, BLUE, BLACK, or GRAY with preset(); loadConfig() explicitly loads a runtime theme file. Custom base colours and per-role overrides remain supported. |
SLColor | A straight-alpha 0xRRGGBBAA colour value helper (rgb/rgba + channel accessors). |
Example
| Class | Role |
|---|---|
SLGalleryDemo | A runnable worked example that builds a full Slick Black window with every control — the SLeeLa-source twin of user-interface/examples/gallery.c. |
Minimal usage
SLUserInterface ui = new SLUserInterface();
ui.configure("com.example.App");
if (ui.open()) { // false if no display (X11)
SLTheme theme = new SLTheme();
theme.preset(SLTheme.DEFAULT); // graphite/charcoal + steel blue
SLWindow win = ui.openWindow("Hello", 480, 320, theme.handle());
SLWidget root = win.rootWidget();
SLBox col = new SLBox();
col.vertical(root, 12);
col.setMarginAll(20);
SLLabel label = new SLLabel();
label.createIn(col, "Welcome to SleelaUI");
SLButton ok = new SLButton();
ok.createIn(col, "Continue");
ok.setSuggested(true); // the one accent action
win.show();
ui.run(); // run the toolkit event loop
}
A custom accent on top of Slick Black:
SLTheme t = new SLTheme();
t.slickBlack();
SLColor green = new SLColor();
green.rgb(0x3d, 0xd6, 0x8c);
t.setAccentColor(green);
t.setRadius(12);
Relationship to the rest of SLeeLa
lib/user-interfaceis the SLeeLa-source surface of the native toolkit under/user-interface; the C ABI there (include/sleela_ui.h) is what theui*built-ins call.- It parallels
lib/os: wherelib/osdrives the real host OS through theos*bridge,lib/user-interfacedrives the real host window system through theui*bridge. Both expose one portable surface with native backends underneath and report which backend is live. lib/guiremains the general module facade;lib/user-interfaceis the concrete, class-rich toolkit binding.
Note on fidelity
Every method here resolves to a genuine SleelaUI C ABI call, which raises a real
native window and paints it with the toolkit's own rasterizer on Windows, macOS,
and Linux/Unix. The look is defined by the portable toolkit core, not by any
native theme, so a SLeeLa program's interface is identical on all three
platforms — the project's stated UI quality bar (see
user-interface/UI-PRINCIPLES.md).