widgets

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 3, 2026 License: BSD-3-Clause Imports: 9 Imported by: 0

README

go-ruby-widgets

CI Go Reference Go Report Card

The pure-Go, Ruby-runtime-independent core of the Ruby widgets gem — a live widget UI toolkit (buttons, labels, text fields, lists, menus and the container/layout system that arranges them) — shaped so that go-embedded-ruby (rbgo) can bind it as require "widgets" and build real pixel UIs.

It is a thin adapter over the go-widgets stack:

Library Role
go-widgets/toolkit The pure-Go widget set + container/layout model.
go-widgets/painter The pixel rasteriser (RGBA buffer back-end).

Unlike the stateless data adapters of the go-ruby-* family (opentype, regexp, erb, …), a Module here owns a live object graph: every widget and container is stored under an integer handle the Ruby side keeps, and every operation — mutate, compose, lay out, render, dispatch an event — is addressed by that handle and returns a Ruby-shaped value (a Hash map[string]any, an Array []any or a scalar). Nothing here imports the Ruby runtime, so it is equally usable as a standalone Go library.

CGO_ENABLED=0, no display, no network — deterministic and cross-compiles to all six 64-bit Go architectures and js/wasm (the target wasmdesk runs).

The Ruby-facing surface

Constructors (return an opaque integer handle)
Kind Methods
Leaves button(label, cb), label(text), entry(initial, cb), text_view(initial), check_button(label, checked, cb), drop_down(options, selected, cb), list_box(items, cb), menu(items), menu_bar
Containers container(layout) (fit/box/hbox/vbox/border/card), h_box, v_box, grid(cols, rows), frame(child), dock(body), border, backdrop(fill, grid, step)
Overlays & chrome notification(text), toast(text, kind, action_label, action), badge(text, fill, ink), image(pixels, w, h, scale), context_menu(menu), popover(child, title), command_palette(commands), icon_button(icon, cb), tooltip(text, placement), avatar(initials, color), level_bar(max), decoration(...)
Desktop status_area, status_icon(icon, tooltip, on_click, on_right_click), status_icon_image(pixels, w, h, tooltip, on_click, on_right_click), wallpaper(pixels, w, h, mode) (fill/fit/center/tile), wallpaper_gradient(top_hex, bottom_hex), thumbnail(pixels, w, h, label, on_click)
Mutation

set_text / text, set_checked / checked, select(id, idx), set_style, set_spacing, and the module-wide set_theme("light"|"dark"). Overlay state: set_visible / visible, popup, anchor_in, set_life, tick, set_kind, set_value. Thumbnail state: set_selected(id, bool), set_hover(id, bool).

The module-wide use_opentype_text (and use_opentype_text_size(px)) upgrades the toolkit's active font from the built-in 5x7 bitmap to anti-aliased, shaped OpenType text (the bundled Atkinson Hyperlegible face). Call it once before the first render and every widget — window titles, menus, HUD, desktop, frame decorations — repaints against the vector face.

Composition

add_widget(parent, child) (also joins a status_icon to a status_area and a badge to a status_icon), add(parent, child, {flex:, size:, region:}), add_fixed, add_flex, attach(grid, child, col, row), dock_at(dock, child, side, size), set_region(border, child, region, size), add_menu(bar, name, menu), set_active(card, idx), set_layout(container, layout).

Layout / query

set_bounds(id, x, y, w, h), layout(id, w, h) (at the origin), bounds(id).

The render seam
img = Widgets.render(root, w, h)
# => { "pixels" => <RGBA bytes>, "stride" => w*4, "w" => w, "h" => h }

pixels is 4 bytes per pixel, row-major, top-left origin — exactly what a host (wasmbox) blits into a <canvas> / SharedArrayBuffer.

The event seam
out = Widgets.dispatch(root, { "kind" => "click", "x" => 10, "y" => 4 })
# => { "fired" => ["on_ok"], "repaint" => true }

kind is one of click / keydown / keyup / char / mousedrag / mouseup. A widget is wired to a callback by passing an identifier to its constructor; when it fires, that identifier appears in fired so the Ruby side can invoke the matching block.

Reflective dispatch

Call(recv, method, args...) (any, error) dispatches a snake_case method name to the matching Module method, coercing Ruby scalars / Arrays / Hashes to the Go parameter types (a trailing error return is unwrapped) — the single entry point an rbgo method_missing shim drives. Methods(recv) lists the accepted names.

Usage from Go

m := widgets.NewModule()
root := m.VBox()
title := m.Label("Hello")
ok := m.Button("OK", "on_ok")
_ = m.AddWidget(root, title)
_ = m.AddWidget(root, ok)
_ = m.Layout(root, 200, 80)

img, _ := m.Render(root, 200, 80)                       // {"pixels":…, "stride":800, …}
out, _ := m.Dispatch(ok, map[string]any{"kind": "click"}) // out["fired"] == []any{"on_ok"}

Usage from Ruby

require "widgets"

root  = Widgets.v_box
ok    = Widgets.button("OK", "on_ok")
Widgets.add_widget(root, ok)
Widgets.layout(root, 200, 80)
img   = Widgets.render(root, 200, 80)
fired = Widgets.dispatch(ok, { "kind" => "click" })   # => { "fired" => ["on_ok"], … }

The require "widgets" binding lives in rbgo (a thin method_missing shim over Call); it is pending in that repo.

License

BSD-3-Clause. Copyright (c) 2026, the go-ruby-widgets/widgets authors.

Documentation

Overview

Package widgets is the pure-Go, Ruby-runtime-independent core of the Ruby `widgets` gem: a live widget UI toolkit — buttons, labels, text fields, lists, menus and the container/layout system that arranges them — shaped so that github.com/go-embedded-ruby/ruby (rbgo) can bind it as `require "widgets"` and build real pixel UIs.

It is a thin adapter over github.com/go-widgets/toolkit (the widget set and its container/layout model) and github.com/go-widgets/painter (the pixel rasteriser). Unlike the stateless data adapters of the go-ruby-* family (opentype, regexp, erb, …), a Module here owns a LIVE object graph: every widget and container is stored under an integer handle the Ruby side keeps, and every operation — mutate, compose, lay out, render, dispatch an event — is addressed by that handle and returns a Ruby-shaped value: a Hash (map[string]any), an Array ([]any) or a scalar. A single dynamic entry point, Call, dispatches a Ruby-style snake_case method name to the matching Module method and coerces the arguments, which is exactly what an rbgo binding drives from method_missing. Nothing here imports the Ruby runtime, so the package is equally usable as a standalone Go library.

The object graph

  • Constructors return an opaque integer handle: Button, Label, Entry, TextView, CheckButton, DropDown, ListBox, Menu, MenuBar for leaves; Container (a config-driven fit/box/border/card layout), HBox, VBox, Grid, Frame, Dock and Border for containers; the overlay + chrome set a compositor needs — Notification, Toast (with a leading icon, multi-line body and multi-action buttons), Badge, Image, ContextMenu, Popover, CommandPalette, IconButton, Tooltip, Avatar, LevelBar (with a caption and value-band Thresholds) and Calendar (a month grid); and the desktop-environment set — StatusArea / StatusIcon / StatusIconImage (the tray), Wallpaper / WallpaperGradient (the desktop backdrop) and Thumbnail (the Exposé / Alt-Tab / dock-peek window preview).
  • Mutators address a handle: SetText/Text, SetChecked/Checked, Select, SetFontSize (a Label's per-label pixel size), SetStyle, SetSpacing, the package-wide SetTheme, the overlay state SetVisible/Visible, Popup, AnchorIn, SetLife, Tick, SetKind, SetValue, the Toast refinements SetToastIcon/SetToastLines/SetToastActions, the Calendar controls PrevMonth/NextMonth/OnSelect/OnMonthChange, the command-palette accessors SetQuery/Query/MoveSelection/FilteredCommands/HandleKey, the shared Selected/SetSelected selection state, and the thumbnail state SetHover.
  • Composition wires the tree: AddWidget (which also joins a StatusIcon to a StatusArea and a Badge to a StatusIcon), Add (with a flex/size/region Hash), AddFixed, AddFlex, Attach (grid), DockAt, SetRegion (border), AddMenu, SetActive (card) and SetLayout.
  • Layout + query: SetBounds, Layout (at the origin) and Bounds.
  • Render paints a tree into an RGBA pixel buffer; Dispatch routes an input event into it.

The render seam

Render(root, w, h) lays the tree out to fill a w×h surface and paints it, returning {"pixels": <RGBA bytes>, "stride": w*4, "w": w, "h": h}. The pixels are 4 bytes per pixel, row-major, top-left origin — exactly what a host (wasmbox) blits into a canvas or SharedArrayBuffer.

The event seam

Dispatch(root, {"kind" => "click", "x" => …, "y" => …}) routes the event into the tree by hit-testing container bounds, then reports {"fired": [callback ids…], "repaint": bool}. A widget is wired to a callback by passing a callback identifier to its constructor (Button, Entry, CheckButton, DropDown, ListBox and Menu items); when it fires, its identifier appears in the "fired" Array so the Ruby side can invoke the matching block.

Usage from Go 

m := widgets.NewModule()
root := m.VBox()
title := m.Label("Hello")
ok := m.Button("OK", "on_ok")
_ = m.AddWidget(root, title)
_ = m.AddWidget(root, ok)
_ = m.Layout(root, 200, 80)
img, _ := m.Render(root, 200, 80) // {"pixels":…, "stride":800, "w":200, "h":80}
out, _ := m.Dispatch(ok, map[string]any{"kind": "click"})
// out["fired"] == []any{"on_ok"}

Usage from Ruby

Under rbgo, `require "widgets"` gives a Widgets module whose snake_case methods are these operations, returning Ruby Hashes, Arrays and scalars: 

require "widgets"

root  = Widgets.v_box
ok    = Widgets.button("OK", "on_ok")
Widgets.add_widget(root, ok)
Widgets.layout(root, 200, 80)
img   = Widgets.render(root, 200, 80)   # => { "pixels" => …, "stride" => 800, … }
fired = Widgets.dispatch(ok, { "kind" => "click" })   # => { "fired" => ["on_ok"], … }

The `require "widgets"` binding lives in rbgo (a thin method_missing shim over Call); it is pending in that repo.

Example

Example builds a two-widget column, lays it out, renders it to a pixel buffer and routes a click into the button — every result a Ruby-shaped value. 

package main

import (
	"fmt"

	"github.com/go-ruby-widgets/widgets"
)

func main() {
	m := widgets.NewModule()

	root := m.VBox()
	title := m.Label("Hello")
	ok := m.Button("OK", "on_ok")
	_ = m.AddWidget(root, title)
	_ = m.AddWidget(root, ok)
	_ = m.Layout(root, 200, 80)

	img, _ := m.Render(root, 200, 80)
	fmt.Println("stride:", img["stride"], "w:", img["w"], "h:", img["h"])

	out, _ := m.Dispatch(ok, map[string]any{"kind": "click"})
	fmt.Println("fired:", out["fired"], "repaint:", out["repaint"])

}

Output:
stride: 800 w: 200 h: 80
fired: [on_ok] repaint: true

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Call 

func Call(recv any, method string, args ...any) (any, error)

Call dispatches a Ruby-style snake_case method name to the matching exported method of the Module, coercing each Ruby-supplied argument to the Go parameter type. Trailing arguments may be omitted: a genuinely-absent position defaults to the parameter's zero value (int->0, bool->false, string->"", slice/map->nil), so a Ruby caller writes Widgets.add(parent, child) instead of spelling out the trailing 0 flex/size/region — the same optional-trailing-args ergonomics Ruby itself offers. Only truly-omitted positions are defaulted; a *supplied* argument always flows through the coercion, so a wrong-type value (or too many arguments) still errors rather than being silently absorbed. The result is the method's Ruby-shaped return value (or nil for a method that returns nothing); a trailing error return is unwrapped into Call's own error. This is the single entry point an rbgo binding drives from method_missing.

func Methods 

func Methods(recv any) []string

Methods lists, sorted, the Ruby-style snake_case names Call accepts for recv.

Types

type Module 

type Module struct {
	// contains filtered or unexported fields
}

Module is the stateful Ruby receiver: the `Widgets` module under rbgo. Unlike the stateless data adapters (opentype, regexp, …) a Module owns a live widget tree — every constructed widget or container is stored under an integer handle the Ruby side references, and every mutation, layout, render and event dispatch is addressed by that handle. A Module is NOT safe for concurrent use (its handle table and pending-callback list are mutated in place).

func NewModule 

func NewModule() *Module

NewModule returns a fresh Module with an empty handle table and the default light theme. Handles count up from 1, so a 0 handle always means "none" (used by Frame/Dock to mean a nil child/body).

func (*Module) Add 

func (m *Module) Add(parent, child int, opts map[string]any) error

Add appends child to a Container with an explicit item config Hash: "flex" (proportional weight), "size" (fixed main-axis extent) and "region" ("north"/"south"/"east"/"west"/"center" for a border layout). A nil Hash is the zero config.

func (*Module) AddFixed 

func (m *Module) AddFixed(parent, child, size int) error

AddFixed appends child to an HBox or VBox with a fixed main-axis size.

func (*Module) AddFlex 

func (m *Module) AddFlex(parent, child, flex int) error

AddFlex appends child to an HBox or VBox with a proportional flex weight.

func (*Module) AddMenu 

func (m *Module) AddMenu(bar int, name string, menu int) error

AddMenu appends a named menu to a MenuBar.

func (*Module) AddWidget 

func (m *Module) AddWidget(parent, child int) error

AddWidget appends child to a Container, HBox or VBox with the default per-item config (an equal share in a box, the centre of a border layout). It also serves the tray add seam: a StatusIcon child appended to a StatusArea parent joins the tray row, and a Badge child attached to a StatusIcon parent becomes its corner overlay.

func (*Module) AnchorIn added in v0.6.0 

func (m *Module) AnchorIn(id, x, y, w, h int, corner string) error

AnchorIn sizes a Notification or Toast to its text and positions it at a corner of the host rect (x, y, w, h), inset by the widget's own margin: "top_left" (the default), "top_right", "bottom_left", "bottom_right", "top_center" or "bottom_center". An unknown corner, or a handle that is not a Notification or Toast, is an error.

func (*Module) Attach 

func (m *Module) Attach(parent, child, col, row int) error

Attach places child at (col, row) in a Grid.

func (*Module) Avatar added in v0.6.0 

func (m *Module) Avatar(initials, color string) (int, error)

Avatar constructs a user-identity chip showing initials centred in a rounded-square body. color is the body fill as "#rrggbb"/"#rrggbbaa" hex; an empty string tracks the theme's Accent. A malformed colour is an error.

func (*Module) Backdrop added in v0.2.0 

func (m *Module) Backdrop(fill, grid string, step int) (int, error)

Backdrop constructs a decorative full-bounds ground: a solid fill and, when step > 0, a regular grid of 1-unit lines every step units. It paints no children and handles no events — the plain backing a host composites a scene on top of (a desktop wallpaper, a canvas backing sheet, a chart plot area).

fill and grid are "#rrggbb" or "#rrggbbaa" hex strings; an empty string selects the theme's Background (fill) or Border (grid) at render time. A malformed colour is an error, reported by Call. step <= 0 draws no grid.

func (*Module) Badge added in v0.6.0 

func (m *Module) Badge(text, fill, ink string) (int, error)

Badge constructs a small pill-shaped counter/indicator carrying text (the "12" on an inbox icon). fill overrides the pill body colour and ink the text colour; both are "#rrggbb"/"#rrggbbaa" hex, and an empty string selects the theme's Accent (fill) / Background (ink) at render time. A malformed colour is an error.

func (*Module) Border 

func (m *Module) Border() int

Border constructs an edge-region container (set regions with SetRegion).

func (*Module) Bounds 

func (m *Module) Bounds(id int) (map[string]any, error)

Bounds reports a widget's placement as a Hash with "x", "y", "w", "h".

func (*Module) Button 

func (m *Module) Button(label, callback string) int

Button constructs a push button labelled label. When callback is non-empty it is fired (reported by Dispatch) on every click.

func (*Module) Calendar added in v0.8.0 

func (m *Module) Calendar(year, month, selected int) int

Calendar constructs a month grid for the given year and month (1..12) with day selected highlighted. A host drives the view with PrevMonth / NextMonth and the selection with SetSelected, reads the selected day back with Selected, and wires OnSelect / OnMonthChange. Out-of-range fields are clamped by the toolkit.

func (*Module) CheckButton 

func (m *Module) CheckButton(label string, checked bool, callback string) int

CheckButton constructs a labelled checkbox. When callback is non-empty it fires on every toggle.

func (*Module) Checked 

func (m *Module) Checked(id int) (bool, error)

Checked reads a CheckButton's state.

func (*Module) CommandPalette added in v0.6.0 

func (m *Module) CommandPalette(commands []any) int

CommandPalette constructs a hidden centred spotlight overlay over commands — a Ruby Array of Hashes, each with a "label" (the searchable text) and an "action" (a callback identifier fired, and reported by Dispatch, when the command is chosen). Non-Hash elements are skipped, mirroring the Menu constructor. Open it with SetVisible(id, true), which clears any prior query + selection.

func (*Module) Container 

func (m *Module) Container(layout string) (int, error)

Container constructs a config-driven container whose children are placed by a named layout: "fit" (fill), "box"/"hbox" (a row), "vbox" (a column), "border" (edge regions + centre) or "card" (one visible child). An unknown name is an error, reported by Call.

func (*Module) ContextMenu added in v0.6.0 

func (m *Module) ContextMenu(menu int) (int, error)

ContextMenu wraps an existing Menu handle (built with Menu) as a right-click pop-up: it appears at a point (Popup), clamps itself inside the surface, and dismisses on an outside click. The menu handle must reference a Menu.

func (*Module) Decoration added in v0.3.0 

func (m *Module) Decoration(spec map[string]any) (int, error)

Decoration constructs a toolkit.WindowDecoration — a window's frame chrome (title-bar band + caption + buttons + border + optional shadow + resize grip) painted with EXPLICIT colours and EXPLICIT frame-local geometry — from a Ruby spec Hash, and returns its handle.

The host (a compositor) owns the window model and its hit-testing, so it passes the exact rects it hit-tests against plus the palette its style needs; the widget only paints. The body region is left transparent so the host composites the decoration over a live window body.

Recognised spec keys (all optional; absent = zero/omitted): 

"title"        String    the caption
"title_ink"    hex       caption colour
"title_color"  hex       title-bar band fill
"titlebar"     [x,y,w,h] band rect (frame-local)
"title_center" Bool      centre the caption (default: left)
"hairline"     hex       band bottom hairline ("" = none)
"border"       [x,y,w,h] full frame extent (frame-local)
"border_color" hex       border stroke ("" = none)
"shadow"       hex       faux drop shadow past the border ("" = none)
"grip"         [x,y,w,h] resize-grip rect (frame-local)
"show_grip"    Bool      draw the grip
"grip_color"   hex       grip diagonals colour
"buttons"      [Hash]    the title-bar button cluster, each:
                 "rect"      [x,y,w,h] (frame-local)
                 "shape"     "rect" | "circle"     (default "rect")
                 "face"      hex   face fill
                 "outline"   hex   circle outline ("" = none)
                 "glyph"     "none"|"close"|"minimize"|"maximize"
                 "glyph_ink" hex   glyph colour

A malformed colour, rect or enum value is an error, surfaced by Call.

func (*Module) Dispatch 

func (m *Module) Dispatch(id int, ev map[string]any) (map[string]any, error)

Dispatch routes an input event into a tree and reports the outcome. The ev Hash carries "kind" ("click"/"keydown"/"keyup"/"char"/"mousedrag"/"mouseup"), "x"/"y" (widget-local pixels), "code" (key/char text) and Bool "ctrl"/"shift". The result Hash is "fired" (an Array of the callback identifiers that ran, in order) and a Bool "repaint" (whether any callback ran, i.e. the tree may have changed).

func (*Module) Dock 

func (m *Module) Dock(body int) (int, error)

Dock constructs an edge-docking container around body (pass 0 for a bars-only frame); attach bars with DockAt.

func (*Module) DockAt 

func (m *Module) DockAt(parent, child int, side string, size int) error

DockAt attaches child to an edge ("top"/"bottom"/"left"/"right") of a Dock, reserving size pixels along that edge's axis.

func (*Module) DropDown 

func (m *Module) DropDown(options []any, selected int, callback string) int

DropDown constructs a drop-down selector over options (a Ruby Array of strings) with the given initial selection. When callback is non-empty it fires on every Select.

func (*Module) Entry 

func (m *Module) Entry(initial, callback string) int

Entry constructs a single-line text field seeded with initial. When callback is non-empty it fires on every value change and on submit (Enter).

func (*Module) FilteredCommands added in v0.8.0 

func (m *Module) FilteredCommands(id int) ([]any, error)

FilteredCommands returns a CommandPalette's currently visible commands, in display order, as a Ruby Array of Hashes each carrying the command's "label" — the exact list the result rows render, so a host can mirror the filtering (e.g. show a live count) without duplicating the match logic. A handle that is not a CommandPalette is an error.

func (*Module) Frame 

func (m *Module) Frame(child int) (int, error)

Frame constructs a 1-pixel-bordered panel around child; pass a 0 child for an empty frame.

func (*Module) Grid 

func (m *Module) Grid(cols, rows int) int

Grid constructs a cols×rows table (children placed with Attach).

func (*Module) HBox 

func (m *Module) HBox() int

HBox constructs an imperative horizontal box (children added with AddWidget / AddFixed / AddFlex).

func (*Module) HandleKey added in v0.8.0 

func (m *Module) HandleKey(id int, ev map[string]any) (map[string]any, error)

HandleKey routes a host-supplied key event into a CommandPalette without going through the widget tree: a typed character (kind "char") extends the query, and a key press (kind "keydown") drives Backspace / ArrowUp / ArrowDown / Enter / Escape (Enter fires the selected command's callback, reported in the result). ev is the same event Hash Dispatch takes; the result is Dispatch-shaped ({"fired" => [...], "repaint" => bool}). A handle that is not a CommandPalette, or a malformed event Hash, is an error.

func (*Module) IconButton added in v0.6.0 

func (m *Module) IconButton(icon, callback string) int

IconButton constructs a compact toolbar tile whose whole face is the short glyph string icon ("+", "OK", "×"). When callback is non-empty it fires (reported by Dispatch) on every click.

func (*Module) Image added in v0.6.0 

func (m *Module) Image(pixels any, w, h int, scale string) (int, error)

Image constructs a widget that blits a caller-supplied RGBA pixel buffer (the desktop wallpaper, an app icon). pixels is either raw RGBA bytes (a Ruby binary String surfaces as []byte) or a base64-encoded String; it must hold at least w*h*4 bytes. w and h are the source dimensions and must be positive. scale selects how the source maps onto the widget bounds: "stretch" (the default, fill ignoring aspect) or "fit" (aspect-preserving, centred). A bad base64 string, non-positive size, short buffer or unknown scale is an error.

func (*Module) Label 

func (m *Module) Label(text string) int

Label constructs a passive text label.

func (*Module) Layout 

func (m *Module) Layout(id, w, h int) error

Layout is SetBounds at the origin — the common case for a top-level tree.

func (*Module) LevelBar added in v0.6.0 

func (m *Module) LevelBar(max int, label string, thresholds []any) (int, error)

LevelBar constructs a discrete segmented indicator (battery / signal / VU meter) of max equal cells; the first Value cells fill (set with SetValue). max is floored at 1 by the toolkit. label, when non-empty, is a caption centred over the bar. thresholds is an optional Ruby Array of Hashes, each with a "min" (an integer Value) and a "color_hex" ("#rrggbb"/"#rrggbbaa"), recolouring the filled cells by value band: the band with the greatest "min" not exceeding Value wins (e.g. red low, amber mid, green high). Non-Hash elements are skipped, mirroring the Menu constructor; the empty/omitted array keeps the Accent fill. A malformed "color_hex" is an error. label and thresholds may be omitted for the original plain bar.

func (*Module) ListBox 

func (m *Module) ListBox(items []any, callback string) int

ListBox constructs a scrollable single-column list over items (a Ruby Array of strings). When callback is non-empty it fires on every row activation.

func (*Module) Menu 

func (m *Module) Menu(items []any) int

Menu constructs a vertical popover menu from items — a Ruby Array of Hashes, each with "label", optional "shortcut", a Bool "separator" and an "action" (a callback identifier fired when the row is chosen). Non-Hash elements are skipped.

func (*Module) MenuBar 

func (m *Module) MenuBar() int

MenuBar constructs an empty horizontal menu bar; attach menus with AddMenu.

func (*Module) MoveSelection added in v0.8.0 

func (m *Module) MoveSelection(id, delta int) error

MoveSelection shifts a CommandPalette's selection by delta (negative up, positive down) within the filtered list, clamped at both ends — the ArrowUp/ArrowDown behaviour, host-driven. A handle that is not a CommandPalette is an error.

func (*Module) NextMonth added in v0.8.0 

func (m *Module) NextMonth(id int) error

NextMonth advances a Calendar one month (wrapping December to the next January), re-clamps the selected day and fires OnMonthChange. A handle that is not a Calendar is an error.

func (*Module) Notification added in v0.6.0 

func (m *Module) Notification(text string) int

Notification constructs a transient, auto-dismissing banner carrying text. It starts hidden with the default life budget pre-armed; a host makes it visible (SetVisible / AnchorIn), positions it, then Ticks it down each animation frame.

func (*Module) OnMonthChange added in v0.8.0 

func (m *Module) OnMonthChange(id int, callback string) error

OnMonthChange wires a Calendar's month-change callback: PrevMonth / NextMonth (or a header-arrow click) fires the callback identifier (reported by Dispatch). An empty callback clears the wiring. A handle that is not a Calendar is an error.

func (*Module) OnSelect added in v0.8.0 

func (m *Module) OnSelect(id int, callback string) error

OnSelect wires a Calendar's day-selection callback: clicking a day fires the callback identifier (reported by Dispatch); the host then reads the chosen day back with Selected. An empty callback clears the wiring. A handle that is not a Calendar is an error.

func (*Module) Popover added in v0.6.0 

func (m *Module) Popover(child int, title string) (int, error)

Popover constructs a hidden floating panel wrapping child (pass 0 for an empty framed panel), with an optional title header. Make it visible with SetVisible and position it with SetBounds; while hidden it draws and dispatches nothing.

func (*Module) Popup added in v0.6.0 

func (m *Module) Popup(id, x, y int) error

Popup opens a ContextMenu anchored at (x, y) — the cursor point — so its next render draws the menu clamped inside the surface. The handle must be a ContextMenu.

func (*Module) PrevMonth added in v0.8.0 

func (m *Module) PrevMonth(id int) error

PrevMonth steps a Calendar one month back (wrapping January to the previous December), re-clamps the selected day and fires OnMonthChange. A handle that is not a Calendar is an error.

func (*Module) Query added in v0.8.0 

func (m *Module) Query(id int) (string, error)

Query returns a CommandPalette's current search text. A handle that is not a CommandPalette is an error.

func (*Module) Render 

func (m *Module) Render(id, w, h int) (map[string]any, error)

Render lays a tree out to fill a w×h surface and paints it, returning a Hash with the RGBA "pixels" (4 bytes per pixel, row-major, top-left origin), "stride" (the byte offset between rows, i.e. w*4) and "w"/"h". A host (wasmbox) blits pixels straight into a canvas / SharedArrayBuffer.

func (*Module) Select 

func (m *Module) Select(id, idx int) error

Select changes the selection of a DropDown (which also fires its callback) or a ListBox.

func (*Module) Selected added in v0.8.0 

func (m *Module) Selected(id int) (int, error)

Selected returns a widget's current selection index: a Calendar's selected day or a CommandPalette's selected row (within its filtered list). A handle that is neither is an error.

func (*Module) SetActive 

func (m *Module) SetActive(container, idx int) error

SetActive selects the visible child of a Container backed by a card layout.

func (*Module) SetBounds 

func (m *Module) SetBounds(id, x, y, w, h int) error

SetBounds positions a widget (or the root of a tree) at (x, y) with size w×h, running the toolkit layout over any descendants.

func (*Module) SetChecked 

func (m *Module) SetChecked(id int, v bool) error

SetChecked sets a CheckButton's state.

func (*Module) SetFontSize added in v0.8.0 

func (m *Module) SetFontSize(id, px int) error

SetFontSize sets a Label's per-label pixel font size (a big clock face, a heading): the label re-renders its text at px regardless of the theme's base size. A non-positive px reverts to the theme default. It only takes effect on a scalable TrueType/OpenType face (an unscalable bitmap font degrades gracefully to the base size). A handle that is not a Label is an error.

func (*Module) SetHover added in v0.7.0 

func (m *Module) SetHover(id int, v bool) error

SetHover sets the hover-border state of a Thumbnail (the pointer is over the tile). A handle that is not a Thumbnail is an error.

func (*Module) SetKind added in v0.6.0 

func (m *Module) SetKind(id int, kind string) error

SetKind changes a Toast's severity ("info"/"success"/"warning"/"error"), re-tinting its pill. An unknown kind, or a handle that is not a Toast, is an error.

func (*Module) SetLayout 

func (m *Module) SetLayout(container int, layout string) error

SetLayout swaps a Container's layout to a named one (see Container).

func (*Module) SetLife added in v0.6.0 

func (m *Module) SetLife(id, n int) error

SetLife sets the auto-dismiss countdown of a Notification or Toast: the number of Tick calls before it hides. For a Toast, 0 is the "sticky" sentinel (never auto-hide). A handle that is neither is an error.

func (*Module) SetQuery added in v0.8.0 

func (m *Module) SetQuery(id int, q string) error

SetQuery replaces a CommandPalette's search text (seeding or overriding it from a host), re-clamping the selection into the newly filtered list exactly as typing would. A handle that is not a CommandPalette is an error.

func (*Module) SetRegion 

func (m *Module) SetRegion(parent, child int, region string, size int) error

SetRegion assigns child to a Border region ("north"/"south"/"east"/"west"/ "center"), with size the edge band's thickness (ignored for the centre).

func (*Module) SetSelected added in v0.7.0 

func (m *Module) SetSelected(id int, v any) error

SetSelected sets a widget's selection state, dispatching on the handle's type: a Thumbnail's selected-border flag (v is truthy — the Alt-Tab / Exposé current choice), a CommandPalette's selection index (v is an integer, clamped into the filtered list) or a Calendar's selected day (v is an integer day, re-clamped into the current month). A handle that is none of these is an error, as is a non-integer v where an index/day is expected.

func (*Module) SetSpacing 

func (m *Module) SetSpacing(id, n int) error

SetSpacing sets the inter-child gap of an HBox, VBox or Grid.

func (*Module) SetStyle 

func (m *Module) SetStyle(id int, style string) error

SetStyle sets a Button's resting appearance: "default", "prominent" or "secondary".

func (*Module) SetText 

func (m *Module) SetText(id int, s string) error

SetText sets the text of a Label, Button, Entry, TextView or CheckButton, the message of a Notification, Toast, Tooltip or Badge, an IconButton's glyph or an Avatar's initials.

func (*Module) SetTheme 

func (m *Module) SetTheme(name string) error

SetTheme switches the render theme to "light" or "dark".

func (*Module) SetToastActions added in v0.8.0 

func (m *Module) SetToastActions(id int, actions []any) error

SetToastActions gives a Toast several action buttons, superseding the single ActionLabel/Action pair: actions is a Ruby Array of Hashes, each with a "label" (the button caption) and a "callback" (a callback identifier fired, and reported by Dispatch, when that button is clicked). Non-Hash elements are skipped, mirroring the Menu constructor. An empty array reverts to the single action pair. A handle that is not a Toast is an error.

func (*Module) SetToastIcon added in v0.8.0 

func (m *Module) SetToastIcon(id int, icon any, w, h int) error

SetToastIcon gives a Toast a leading icon. icon is either a stock glyph name ("new"/"open"/"save"/"cut"/"copy"/"paste"/"undo"/"redo"/"search"/"settings"), which paints a vector glyph, or RGBA pixel data (raw []byte or a base64 String) drawn as an image, in which case w and h are its positive source dimensions and the buffer must hold at least w*h*4 bytes. Passing a known glyph name clears any prior pixels (w and h are ignored); passing pixels clears any prior glyph. A handle that is not a Toast, an unknown-glyph string that is also not valid base64, a non-positive pixel size or a short buffer is an error.

func (*Module) SetToastLines added in v0.8.0 

func (m *Module) SetToastLines(id int, lines []any) error

SetToastLines gives a Toast a multi-line body: the message is rendered as the supplied rows (a bold-reading title line plus one or more body lines) stacked top-to-bottom instead of the single Text. An empty array reverts to the single-Text look. A handle that is not a Toast is an error.

func (*Module) SetValue added in v0.6.0 

func (m *Module) SetValue(id, v int) error

SetValue sets a LevelBar's filled-cell count (clamped by the widget to its cell range at draw time). A handle that is not a LevelBar is an error.

func (*Module) SetVisible added in v0.6.0 

func (m *Module) SetVisible(id int, v bool) error

SetVisible shows or hides a transient overlay: it toggles the Visible flag of a Notification, Toast, Popover or Tooltip, the Open flag of a ContextMenu, and Opens (v true, clearing query + selection) or Dismisses (v false) a CommandPalette. A handle that is not one of these is an error.

func (*Module) StatusArea added in v0.7.0 

func (m *Module) StatusArea() int

StatusArea constructs an empty tray: a left-to-right row of StatusIcons (the menu-bar extras / notification-area slots), each in a square cell. Populate it by adding StatusIcon handles with AddWidget; the row re-flows on every add and on SetBounds.

func (*Module) StatusIcon added in v0.7.0 

func (m *Module) StatusIcon(icon, tooltip, onClick, onRightClick string) (int, error)

StatusIcon constructs a tray indicator painting a stock vector glyph named by icon: "new", "open", "save", "cut", "copy", "paste", "undo", "redo", "search" or "settings" (an empty string draws no glyph — a badge-only slot). tooltip is the hover text the host surfaces. onClick fires on a primary click and onRightClick on a secondary (menu) click; each is wired only when non-empty. An unknown icon name is an error, reported by Call.

func (*Module) StatusIconImage added in v0.7.0 

func (m *Module) StatusIconImage(pixels any, w, h int, tooltip, onClick, onRightClick string) (int, error)

StatusIconImage is StatusIcon with a caller-supplied RGBA image instead of a stock glyph: pixels is raw RGBA bytes (a Ruby binary String) or a base64 String and must hold at least w*h*4 bytes; w and h are the source dimensions and must be positive. The image is drawn aspect-preserved and centred in the tray cell. tooltip, onClick and onRightClick behave as in StatusIcon. A bad base64 string, non-positive size or short buffer is an error.

func (*Module) Text 

func (m *Module) Text(id int) (string, error)

Text reads the text of a Label, Button, Entry, TextView or CheckButton, the message of a Notification, Toast, Tooltip or Badge, an IconButton's glyph or an Avatar's initials.

func (*Module) TextView 

func (m *Module) TextView(initial string) int

TextView constructs a multi-line editable text area seeded with initial.

func (*Module) Thumbnail added in v0.7.0 

func (m *Module) Thumbnail(pixels any, w, h int, label, onClick string) (int, error)

Thumbnail constructs a window-preview tile that renders a caller-supplied RGBA buffer scaled down (aspect-preserved, centred) into its bounds, with an optional caption strip carrying label and a selected/hover border. It is the tile an Exposé grid, an Alt-Tab switcher or a dock-hover peek is built from. pixels is raw RGBA bytes or a base64 String and must hold at least w*h*4 bytes; w and h are the source dimensions and must be positive. onClick fires (reported by Dispatch) on a click, so a grid can select the tile; it is wired only when non-empty. A bad base64 string, non-positive size or short buffer is an error.

func (*Module) Tick added in v0.6.0 

func (m *Module) Tick(id int) error

Tick advances a Notification or Toast one animation frame, decrementing its life and auto-hiding it when the countdown reaches 0. A host calls it once per frame from its render loop. A handle that is neither is an error.

func (*Module) Toast added in v0.6.0 

func (m *Module) Toast(text, kind, actionLabel, action string) (int, error)

Toast constructs a short-lived severity pill: text rendered in a Kind-coloured body ("info"/"success"/"warning"/"error"; "" == info). An unknown kind is an error, reported by Call. When actionLabel is non-empty a small action button is rendered inside the pill's right edge and, when action is also non-empty, its callback identifier fires (reported by Dispatch) when that button is clicked.

func (*Module) Tooltip added in v0.6.0 

func (m *Module) Tooltip(text, placement string) (int, error)

Tooltip constructs a hidden text bubble. placement picks which side of its anchor the bubble sits on: "below" (the default), "above", "left" or "right". An unknown placement is an error. A host toggles it with SetVisible and positions it with SetBounds.

func (*Module) UseOpentypeText added in v0.4.0 

func (m *Module) UseOpentypeText() error

UseOpentypeText switches the toolkit's active font from the built-in 5x7 bitmap to anti-aliased, shaped OpenType text — the bundled Atkinson Hyperlegible face at the toolkit's default UI size — in a single call. After it, every widget (window titles, menus, HUD, desktop, frame decorations, …) re-lays-out and repaints against the vector face without any further per-widget wiring.

Call it once at start-up, before the first render. The active font is a process-global in the toolkit, so this affects every Module. A parse failure (which the bundled face never triggers) is returned and leaves the bitmap default in place.

func (*Module) UseOpentypeTextSize added in v0.4.0 

func (m *Module) UseOpentypeTextSize(px int) error

UseOpentypeTextSize is UseOpentypeText at an explicit pixel size — for apps (or high-DPI surfaces) wanting AA text larger or smaller than the toolkit default. The active font is only swapped on success; on a parse error it is left untouched and the error is returned.

func (*Module) VBox 

func (m *Module) VBox() int

VBox constructs an imperative vertical box.

func (*Module) Visible added in v0.6.0 

func (m *Module) Visible(id int) (bool, error)

Visible reports whether a transient overlay (Notification, Toast, Popover, Tooltip, ContextMenu or CommandPalette) is currently shown. A handle that is not one of these is an error.

func (*Module) Wallpaper added in v0.7.0 

func (m *Module) Wallpaper(pixels any, w, h int, mode string) (int, error)

Wallpaper constructs a full-bounds desktop backdrop that paints a caller- supplied RGBA image scaled by mode: "fill" (the default, cover — aspect- preserved, cropped to fill the screen), "fit" (contain — the whole image centred inside the bounds), "center" (1:1, centred) or "tile" (repeated 1:1). pixels is raw RGBA bytes or a base64 String and must hold at least w*h*4 bytes; w and h are the source dimensions and must be positive. The wallpaper is event-transparent (clicks pass through to the composited scene). A bad base64 string, non-positive size, short buffer or unknown mode is an error.

func (*Module) WallpaperGradient added in v0.7.0 

func (m *Module) WallpaperGradient(topHex, bottomHex string) (int, error)

WallpaperGradient constructs an image-less Wallpaper painting a vertical gradient from topHex down to bottomHex — both "#rrggbb"/"#rrggbbaa" hex. An empty top selects the theme Background; an empty (zero-alpha) bottom makes the fill a solid top colour (no gradient). Like Wallpaper it is event-transparent. A malformed colour is an error.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.