Home /Modules/user-interface/USER-INTERFACE.md

USER-INTERFACE.md

lib/user-interface/USER-INTERFACE.md · 337 line(s) · markdown

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 raw HWND, NSWindow*, X11 Window, or C++ pointer — the same safety discipline used everywhere in the VM. The ui* 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-inEffectSleelaUI C ABI
uiBackend() → intLive backend id (1 Win32 / 2 Cocoa / 3 X11)slui_backend
uiBackendName(id) → String"win32"/"cocoa"/"x11"slui_backend_name
uiVersion() → StringToolkit version stringslui_version_string
uiAppCreate(id) → intOpen the application; VM-local handle (-1 fail)slui_app_create
uiAppDestroy(app)Release the application and its windowsslui_app_destroy
uiAppPump(app,block) → intDispatch pending events onceslui_app_pump
uiAppRun(app) → intRun the event loop; return the exit codeslui_app_run
uiAppQuit(app,code)Ask the loop to stopslui_app_quit
uiWindowCreate(app,title,w,h,theme) → intOpen a window; VM-local handleslui_window_create
uiWindowShow/Hide(win)Map / unmap the windowslui_window_show/_hide
uiWindowClosed(win) → int1 once the user closed the window (X button), else 0slui_window_closed
uiWindowSetTitle(win,title)Set the titleslui_window_set_title
uiWindowRoot(win) → intThe root container widget handleslui_window_root
uiWindowSetTheme(win,theme)Swap the palette liveslui_window_set_theme
uiWindowRedraw(win)Request a repaintslui_window_request_redraw
uiBox(parent,orient,spacing) → intA vertical/horizontal boxslui_box
uiHeaderBar(parent) → intA title-bar stripslui_header_bar
uiLabel(parent,text) → intA text labelslui_label
uiButton(parent,text) → intA push buttonslui_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) → intA toggle switchslui_toggle
uiEntry(parent,placeholder) → intA single-line text fieldslui_entry
uiSlider(parent,min,max,val) → intA sliderslui_slider
uiSeparator(parent,orient) → intA hairline ruleslui_separator
uiSpacer(parent) → intA flexible expanding gapslui_spacer
uiCheckBox(parent,text,on) → intA labelled check boxslui_check_box
uiRadioButton(parent,text,group,on) → intA grouped radio buttonslui_radio_button
uiComboBox(parent) → intA drop-down selectionslui_combo_box
uiComboBoxAdd(combo,option)Append a combo optionslui_combo_box_add
uiSpinButton(parent,min,max,step,val) → intA numeric spin buttonslui_spin_button
uiProgressBar(parent,frac) → intA determinate progress barslui_progress_bar
uiLevelBar(parent,frac) → intA segmented level barslui_level_bar
uiSpinner(parent) → intAn indeterminate activity spinnerslui_spinner
uiScrollBar(parent,orient,val,page) → intA scroll bar indicatorslui_scroll_bar
uiFrame(parent,title) → intA titled bordered containerslui_frame
uiCard(parent) → intA raised surface panelslui_card
uiPopupCreate(parent) → intA hidden floating overlay card (menu/dropdown); painted last, above the frame, with a drop shadow + raised 3D faceslui_popup_create
uiPopupSetOpen(popup,open)Show (1) / dismiss (0) the popupslui_popup_set_open
uiPopupIsOpen(popup) → int1 while the popup is openslui_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-rightslui_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 buttonslui_popup_anchor_to
uiGrid(parent,cols,spacing) → intA row/column gridslui_grid
uiStatusBar(parent) → intA footer status stripslui_status_bar
uiImage(parent,src,w,h) → intImage 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) → intA round avatarslui_avatar
uiBadge(parent,text) → intA count/status pillslui_badge
uiChip(parent,text) → intA tag / chip pillslui_chip
uiHeading(parent,text,size) → intA large title labelslui_heading
uiTooltip(parent,text) → intA tooltip bubbleslui_tooltip
uiLinkButton(parent,text) → intA hyperlink-style buttonslui_link_button
uiSearchEntry(parent,ph) → intA search fieldslui_search_entry
uiPasswordEntry(parent,ph) → intA masked password fieldslui_password_entry
uiInfoBar(parent,text,severity) → intAn inline notice barslui_info_bar
uiWidgetMargin(w,t,r,b,l)Set marginsslui_widget_set_margin
uiWidgetAlign(w,h,v)Set alignmentslui_widget_set_align
uiWidgetExpand(w,h,v)Set expansionslui_widget_set_expand
uiWidgetSizeRequest(w,mw,mh)Minimum sizeslui_widget_set_size_request
uiWidgetSensitive(w,on)Enable / grey outslui_widget_set_sensitive
uiWidgetVisible(w,on)Show / hideslui_widget_set_visible
uiWidgetSetText(w,text) / uiWidgetGetText(w)Text accessorslui_widget_set/get_text
uiWidgetSetToggle(w,on) / uiWidgetGetToggle(w)Toggle stateslui_widget_set/get_toggle
uiWidgetSetValue(w,v) / uiWidgetGetValue(w)Slider valueslui_widget_set/get_value
uiWidgetSuggested(w,on) / uiWidgetDestructive(w,on)Accentsslui_widget_set_suggested/_destructive
uiWidgetTakeActivated(w) → int1 once per activation (latch cleared on read)activate callback latch
uiThemePreset(id) → intA theme filled from a preset; VM-local handleslui_theme_preset
uiThemeSet*(theme,color)Set a role colour (0xRRGGBBAA)SLUITheme fields
uiThemeSetRadius/ControlHeight(theme,px)MetricsSLUITheme fields
uiThemeSetFont(theme,family,size)TypographySLUITheme 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 uiWidgetTakeActivated reads and clears, so a SLeeLa program observes a click/flip/edit exactly once per pump() turn without needing function pointers.

The classes

Application and window

ClassRole
SLUserInterfaceThe capstone facade: create the application, report the live backend, open windows, run/pump/quit the event loop.
SLWindowA top-level native window: show/hide, title, its root container, live theme swap, redraw.

Widgets

ClassRole
SLWidgetThe base for every control: margins, alignment, expansion, size request, sensitivity, visibility, text, suggested/destructive accents.
SLBoxA vertical/horizontal box container (GTK/CSS box layout).
SLHeaderBarA title-bar strip (chrome fill + bottom hairline).
SLLabelA non-interactive text label.
SLButtonA push button, with suggested (accent) and destructive variants.
SLToggleA toggle switch with a trailing label.
SLEntryA single-line UTF-8 text field with a caret.
SLSliderA horizontal slider over a [min,max] range.
SLSeparatorA 1px hairline rule.
SLSpacerA flexible expanding gap.
SLCheckBoxA labelled check box with an accent tick.
SLRadioButtonA grouped, mutually-exclusive radio button.
SLComboBoxA drop-down selection control.
SLSpinButtonA numeric value with − / + steppers over [min,max].
SLProgressBarA determinate progress bar over [0,1].
SLLevelBarA segmented level indicator over [0,1].
SLSpinnerAn indeterminate activity spinner.
SLScrollBarA scroll bar with a draggable thumb.
SLFrameA titled, bordered group container.
SLCardA raised rounded surface panel.
SLGridA fixed row/column grid container.
SLStatusBarA footer status strip.
SLImageAn image/icon tile with a centred glyph.
SLAvatarA round accent avatar with an initial.
SLBadgeA small accent count/status pill.
SLChipA rounded tag/filter pill.
SLHeadingA large title label.
SLTooltipA small tooltip bubble.
SLLinkButtonA hyperlink-style accent button.
SLSearchEntryAn entry with a leading search glyph.
SLPasswordEntryAn entry that masks its characters.
SLInfoBarAn 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.

ClassRoleComposed from
SLScrollViewA scrollable, clipping viewport; children build into its contentArea().SLFrame + SLBox + SLScrollBar
SLTreeViewA hierarchical tree with depth indentation, expand/collapse, and selection.SLScrollView + SLLabel rows
SLNotebookA tabbed container: a tab strip over a one-page-visible content stack, with per-tab dirty markers.SLBox + SLButton tabs
SLTextViewA multi-line editable code editor: line buffer, caret, selection, dirty flag, gutter line numbers, current-line highlight, drawn via the Draw API.SLCanvasView + SLDrawContext
SLLoadingIndicatorA 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.)

ClassRole
SLGuiEventTypeThe event catalogue (click, input, change, keydown, toggle, submit, custom, …) with ordinals ↔ names.
SLGuiEventA dispatched event with a value/key/pointer payload and preventDefault/stopPropagation.
SLGuiHandlerA bound callback (type, target, operation) with once/capture and a take-the-latch activation.
SLGuiEventBusThe dispatcher: addEventListener/removeEventListener, phased capture → bubble dispatch, once sweeping.
SLGuiNodeA DOM element: tag/id/text, parent + children, an attribute map, an inline style map, visibility/enabled, a live widget handle.
SLGuiDomThe document: getElementById, createElement, appendChild, setText/setAttribute/setStyle, show/hide, onClick/onInput/…
SLGuiScriptCommandOne script instruction (verb + operands).
SLGuiScriptThe bounded command-list engine that drives the DOM/events.
SLGuiWidgetFactoryMaps a node tag → a SleelaUI constructor (the DOM→toolkit seam).
SLGuiMountThe reconciler: depth-first mount, id → widget map, applies dirty-node state to widgets.
SLGuiHostAdapterPolls widget activation latches and raises the matching SLGuiEvents into the bus.
SLGuiAppThe 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)

ClassRole
SLDrawContextThe 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).
SLFrameClockRefresh-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 at user-interface/THROBBER.md.

Lighting, shadow & relief

ClassRole
SLLightA 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.
SLLightSceneA 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.
SLMaterialHow 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

ClassRole
SLMeasureA 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.
SLLayoutA 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

ClassRole
SLMmMillimetre 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.
SLCalculus8The 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).
SLWashAn Excellent Wash: a soft, multi-stop graded colour field (smoothstep-sampled) that paints a mood.
SLMoodA 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

ClassRole
SLFontA 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.
SLFontEffectOne 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

ClassRole
SLThemeA 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.
SLColorA straight-alpha 0xRRGGBBAA colour value helper (rgb/rgba + channel accessors).

Example

ClassRole
SLGalleryDemoA 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

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).