widgets

package module
v0.10.9 Latest Latest
Warning

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

 Go to latest Published: Aug 21, 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) ButtonRects added in v0.9.0 

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

ButtonRects reports the laid-out rectangle of each of a Toast's action buttons, in the toast's local (painted) coordinate space, as a Ruby Array of Hashes each carrying "x"/"y"/"w"/"h". The i-th rect is the click target for the i-th action (the Actions set by SetToastActions, else the single legacy action button); an action-less toast yields an empty Array. A host that renders the toast to a pixel buffer and hit-tests clicks itself maps a click into the toast's local space and finds the button whose rect contains it — routing the click to the correct action instead of always the first. The rects reflect the toast's CURRENT bounds, so size it first (Render, which lays the toast out to the pixel buffer, or SetBounds). A handle that is not a Toast is an error.

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) MenuRowAt added in v0.10.0 

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

MenuRowAt reports the index of the menu entry under the widget-local point (x, y) — the SAME coordinate space Dispatch's "x"/"y" use — that a click there would activate, or -1 when the point is outside the menu's bounds, over a separator, or over a disabled (action-less, submenu-less) row. It is the exact query a compositor that paints the menu via Render/Layout and routes its OWN clicks needs, so it can ask "which row is under this point" instead of mirroring the toolkit's row height, body inset, separator height and scroll offset (which drift out of sync when those change). It delegates verbatim to toolkit.Menu.RowAt, so the answer can never diverge from what a click through Dispatch actually does.

Contract: RowAt reads the menu's Bounds and scroll, so lay the handle out first with layout(handle, w, h) (or set_bounds) — exactly as render/layout already require. On an unlaid menu (zero bounds) every point is outside, so the result is uniformly -1. A handle that is not a menu is an error.

func (*Module) MenuRowHeight added in v0.10.0 

func (m *Module) MenuRowHeight(id, i int) (int, error)

MenuRowHeight returns the pixel height of row i in the current scale and touch density (a normal row's height, the separator height for a separator, or -1 when i is out of range), delegating to toolkit.Menu.RowHeight. A handle that is not a menu is an error.

func (*Module) MenuRowTop added in v0.10.0 

func (m *Module) MenuRowTop(id, i int) (int, error)

MenuRowTop returns the widget-local top Y of row i in the same coordinate space MenuRowAt takes and Dispatch receives, with the current scroll offset already applied (so it is negative for a row scrolled above the fold). It is panic-free for any i (an i past the last row returns the body's bottom edge, a negative i the top inset), delegating to toolkit.Menu.RowTop. Paired with MenuRowHeight it gives a host the full row band without re-deriving the metrics. A handle that is not a menu is an error.

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.