button

Documentation

Overview

Package button provides the Vibrant Gio button: a text or icon-only affordance carrying hover, focus, press and disabled treatments, activation by click or by Space and Enter, a screen-reader label, and a minimum 44 dp interactive target.

Button is the observable path — an rx.Observable[theme.Theme] and a Props in, an rx.Observable[layout.Widget] out, rebuilt whenever the theme changes — and activations leave through either Props.OnClick, which is handed the frame's layout.Context, or Props.Message, which adds an mvu.MessageOp to the frame's ops for an MVU runtime to deliver to Update. Render and RenderIcon are the pure path: resolved tokens plus an explicit RenderState in, one frame out, no event handling — that is what the golden-image tests drive and what static rendering should use.

Three things it assumes. Interaction state is allocated inside the component's rx.Defer scope, so press and focus survive the view rebuilds an MVU loop drives; pass Props.Clickable when an enclosing container such as a modal must own the focus tag instead. A button fills the width it is given and is at least 44 dp tall, so a fixed-size button is laid out inside a constrained box. And Props.Shaper is not optional today — leave it nil and the button builds a Go-fonts shaper for itself, with no warning, and renders in the wrong typeface.

Index

• func Button(th rx.Observable[theme.Theme], props Props) rx.Observable[layout.Widget]
• func Render(shaper *text.Shaper, label string, colors tokens.ColorTokens, ...) layout.Widget
• func RenderIcon(icon func(gtx layout.Context, sizePx int, col color.NRGBA), ...) layout.Widget
• type Props
• type RenderState

Functions

func Button

func Button(th rx.Observable[theme.Theme], props Props) rx.Observable[layout.Widget]

Button returns an rx.Observable[layout.Widget] that emits a new widget whenever the theme or disabled state changes. Widget state (clickable, hover, focus, press) lives in the rx.Defer scope and persists across emissions.

Both integration paths are supported:

• FRP: set Props.OnClick; FRP consumers wrap with rx.NewSubject if needed.
• MVU: set Props.Message; the component emits mvu.MessageOp on activation.

func Render

func Render(
	shaper *text.Shaper,
	label string,
	colors tokens.ColorTokens,
	sp tokens.SpacingScale,
	rad tokens.RadiusScale,
	ts tokens.TypeScale,
	s RenderState,
) layout.Widget

Render produces a layout.Widget for a button in an explicit visual state, without any event processing or rx machinery. Intended for golden-image testing and static demonstrations; production code should use Button, which takes the shaper and the LabelLarge text style from the theme's Typography. The TypeScale parameter contributes only the LabelLarge size; typeface, weight and line height stay at the shaper's defaults.

func RenderIcon

func RenderIcon(
	icon func(gtx layout.Context, sizePx int, col color.NRGBA),
	colors tokens.ColorTokens,
	sp tokens.SpacingScale,
	rad tokens.RadiusScale,
	ts tokens.TypeScale,
	s RenderState,
) layout.Widget

RenderIcon produces a layout.Widget for a compact icon-only button in an explicit visual state, without event processing or rx machinery. The glyph is drawn by icon into a square the size of the 44 dp hit target. Intended for golden-image testing and static demonstrations; production code should use Button with Props.Icon (and, when a container drives focus, Props.Clickable).

Types

type Props

type Props struct {
	// Label is the text rendered inside the button.
	Label string

	// Description is the screen-reader label. Falls back to Label when empty.
	Description string

	// Icon, when non-nil and Label is empty, renders the button as a compact
	// icon-only affordance: a square the size of the 44 dp hit target with the
	// glyph centred, instead of a fill-width text label. The painter draws into
	// a sizePx×sizePx box at the current origin in colour col, via
	// clip.Path / clip.Stroke, so output stays golden-deterministic (no font or
	// SVG rasterisation). prism/icon is the registry for named glyphs;
	// determinism-sensitive callers pass a clip.Path painter directly.
	Icon func(gtx layout.Context, sizePx int, col color.NRGBA)

	// Disabled, if non-nil, disables the button when it emits true.
	// A nil Disabled means always enabled.
	Disabled rx.Observable[bool]

	// OnClick is called when the button is activated by click or Space/Enter.
	// This is the FRP callback path. The gtx argument is the layout.Context
	// active on the frame when the click is processed, allowing consumers to
	// emit mvu.MessageOp{Message: ...}.Add(gtx.Ops) inside the callback.
	OnClick func(gtx layout.Context)

	// Message, if non-nil, causes the button to emit mvu.MessageOp{Message}
	// into gtx.Ops on activation. This is the MVU integration path.
	Message any

	// Clickable, if non-nil, is used instead of an internally-allocated one.
	// The caller then owns &Clickable as the button's focus tag — usable with
	// key.FocusCmd, key.Filter{Focus: …} and an external Tab cycle — and may
	// detect activation via Clickable.Clicked(gtx). This lets a container (e.g.
	// cadence/modal) drive focus and trap Tab without a doubled focus ring.
	// When nil the button allocates and owns its own clickable.
	Clickable *widget.Clickable

	// Shaper is an explicit per-instance override of the text shaper. Leave it
	// nil in normal use: the button then shapes its label with the theme's
	// shaper (Typography.Shaper()), which is built once and cached inside the
	// theme's Typography value. Set it only when this button must shape with
	// a different shaper than the theme provides.
	Shaper *text.Shaper
}

Props configures a Button instance.

type RenderState

type RenderState struct {
	Hovered  bool
	Focused  bool
	Pressed  bool
	Disabled bool
}

RenderState holds explicit visual interaction state for static rendering. All fields default to false (normal/idle state). Intended for golden-image testing; production code obtains state from the Gio event system via Button.