primitives

package
v0.1.12 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2026 License: MIT Imports: 11 Imported by: 1

Documentation

Overview

Package primitives provides the fundamental widget building blocks for the gogpu/ui framework: BoxWidget, TextWidget, and ImageWidget.

These three primitives are the lowest-level concrete widgets from which all higher-level components are composed. Each primitive implements widget.Widget for layout, drawing, and event handling, and a11y.Accessible for accessibility.

Fluent Builder API

All primitives use a Tailwind-inspired fluent builder API where the constructor returns a pointer to the widget struct, and style methods return that same pointer for chaining. There is no separate Build step; the returned value is a ready-to-use widget. 

root := primitives.Box(
    primitives.Text("Hello World").
        FontSize(24).
        Color(widget.RGBA(0, 0, 0, 1)),
    primitives.Text("Subtitle").
        FontSize(14),
).Padding(16).Background(widget.RGBA(1, 1, 1, 1)).Rounded(8)

Box

Box is a container widget that lays out its children in a vertical stack with optional padding, background, border, rounded corners, shadow, and gap between children. 

card := primitives.Box(
    primitives.Text("Title").FontSize(18).Bold(),
    primitives.Text("Body text").FontSize(14),
).Padding(16).Background(widget.Hex(0xFFFFFF)).Rounded(12).Shadow(2)

Text

Text displays static or reactive text content. Static text is created with Text, reactive text via a function with TextFn, and signal-bound text with TextWidget.ContentSignal. 

label := primitives.Text("Hello").FontSize(16).Bold()

counter := state.NewSignal(0)
dynamic := primitives.TextFn(func() string {
    return fmt.Sprintf("Count: %d", counter.Get())
}).FontSize(14)

name := state.NewSignal("Alice")
bound := primitives.Text("").ContentSignal(name).FontSize(14)

Image

Image displays a raster image with support for different fit modes (cover, contain, fill) and an alt text label for accessibility. 

img := primitives.Image(mySource).
    Size(200, 150).
    Cover().
    Alt("Photo of a sunset").
    Rounded(8)

Index

Constants

View Source 
const (
	// TextAlignStart aligns text to the start edge (left in LTR, right in RTL).
	TextAlignStart = widget.TextAlignLeft

	// TextAlignCenter centers text horizontally.
	TextAlignCenter = widget.TextAlignCenter

	// TextAlignEnd aligns text to the end edge (right in LTR, left in RTL).
	TextAlignEnd = widget.TextAlignRight
)

TextAlign constants mapped to widget.TextAlign values.

Variables

This section is empty.

Functions

This section is empty.

Types

type Border 

type Border struct {
	// Width is the border thickness in logical pixels.
	Width float32
	// Color is the border color.
	Color widget.Color
}

Border describes the border of a widget.

func (Border) IsZero 

func (b Border) IsZero() bool

IsZero returns true if the border has no visible thickness.

type BoxStyle 

type BoxStyle struct {
	Padding    geometry.Insets
	Background widget.Color
	Radius     float32
	Border     Border
	Shadow     Shadow
	Gap        float32

	// Explicit dimensions. Zero means unconstrained in that dimension.
	ExplicitWidth  float32
	ExplicitHeight float32
	MinWidth       float32
	MinHeight      float32
	MaxWidth       float32
	MaxHeight      float32
}

BoxStyle holds all visual styling for a BoxWidget.

type BoxWidget 

type BoxWidget struct {
	widget.WidgetBase
	// contains filtered or unexported fields
}

BoxWidget is a container that lays out children vertically or horizontally with optional padding, background, border, rounded corners, shadow, and gap.

BoxWidget implements widget.Widget, a11y.Accessible, and widget.Lifecycle.

Create a BoxWidget with the Box constructor. Use HBox or VBox for convenience constructors with a pre-set direction.

func Box 

func Box(children ...widget.Widget) *BoxWidget

Box creates a new container widget with the given children.

Children are laid out vertically from top to bottom by default. Use BoxWidget.SetDirection to switch to horizontal layout, or use the HBox and VBox convenience constructors. 

card := primitives.Box(
    primitives.Text("Title").Bold(),
    primitives.Text("Body"),
).Padding(16).Background(widget.Hex(0xFFFFFF))

func HBox 

func HBox(children ...widget.Widget) *BoxWidget

HBox creates a new container that lays out children horizontally (left to right).

This is a convenience constructor equivalent to Box(children...).SetDirection(DirectionHorizontal). 

row := primitives.HBox(icon, label, spacer).Gap(8)

func VBox 

func VBox(children ...widget.Widget) *BoxWidget

VBox creates a new container that lays out children vertically (top to bottom).

This is a convenience constructor equivalent to Box(children...).SetDirection(DirectionVertical). Since vertical is the default direction, VBox is primarily useful for readability when paired with HBox in the same codebase. 

column := primitives.VBox(title, subtitle, body).Gap(4)

func (*BoxWidget) AccessibilityActions 

func (b *BoxWidget) AccessibilityActions() []a11y.Action

AccessibilityActions returns nil. Containers have no actions.

func (*BoxWidget) AccessibilityHint 

func (b *BoxWidget) AccessibilityHint() string

AccessibilityHint returns an empty string. Containers typically have no hint.

func (*BoxWidget) AccessibilityLabel 

func (b *BoxWidget) AccessibilityLabel() string

AccessibilityLabel returns the custom label, or empty string if none set.

func (*BoxWidget) AccessibilityRole 

func (b *BoxWidget) AccessibilityRole() a11y.Role

AccessibilityRole returns a11y.RoleGenericContainer.

func (*BoxWidget) AccessibilityState 

func (b *BoxWidget) AccessibilityState() a11y.State

AccessibilityState returns the default state.

func (*BoxWidget) AccessibilityValue 

func (b *BoxWidget) AccessibilityValue() string

AccessibilityValue returns an empty string. Containers have no value.

func (*BoxWidget) Background 

func (b *BoxWidget) Background(c widget.Color) *BoxWidget

Background sets the background color.

func (*BoxWidget) BorderStyle 

func (b *BoxWidget) BorderStyle(width float32, color widget.Color) *BoxWidget

BorderStyle sets the border width and color.

func (*BoxWidget) Children 

func (b *BoxWidget) Children() []widget.Widget

Children returns the box's child widgets.

func (*BoxWidget) DirectionSignal 

func (b *BoxWidget) DirectionSignal(sig state.ReadonlySignal[Direction]) *BoxWidget

DirectionSignal binds the layout direction to a read-only reactive signal. When set, the signal value takes precedence over the static direction set via BoxWidget.SetDirection.

Because BoxWidget is a container (not user-editable), only state.ReadonlySignal is accepted (no write-back capability is needed). 

dir := state.NewSignal(primitives.DirectionHorizontal)
box := primitives.Box(a, b).DirectionSignal(dir)

func (*BoxWidget) Draw 

func (b *BoxWidget) Draw(ctx widget.Context, canvas widget.Canvas)

Draw renders the box background, border, shadow, and then draws all children.

func (*BoxWidget) Event 

func (b *BoxWidget) Event(ctx widget.Context, e event.Event) bool

Event dispatches the event to children. Returns true if any child consumed it.

func (*BoxWidget) Gap 

func (b *BoxWidget) Gap(v float32) *BoxWidget

Gap sets the spacing between children. The gap is applied in the layout direction: vertically for DirectionVertical, horizontally for DirectionHorizontal.

func (*BoxWidget) Height 

func (b *BoxWidget) Height(v float32) *BoxWidget

Height sets an explicit height.

func (*BoxWidget) Label 

func (b *BoxWidget) Label(label string) *BoxWidget

Label sets a custom accessibility label for this container.

func (*BoxWidget) Layout 

func (b *BoxWidget) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size

Layout calculates the box size by laying out children in the resolved direction (vertical or horizontal) with padding and gap, then constraining the result.

func (*BoxWidget) MaxHeightValue 

func (b *BoxWidget) MaxHeightValue(v float32) *BoxWidget

MaxHeightValue sets the maximum height.

func (*BoxWidget) MaxWidthValue 

func (b *BoxWidget) MaxWidthValue(v float32) *BoxWidget

MaxWidthValue sets the maximum width.

func (*BoxWidget) MinHeightValue 

func (b *BoxWidget) MinHeightValue(v float32) *BoxWidget

MinHeightValue sets the minimum height.

func (*BoxWidget) MinWidthValue 

func (b *BoxWidget) MinWidthValue(v float32) *BoxWidget

MinWidthValue sets the minimum width.

func (*BoxWidget) Mount 

func (b *BoxWidget) Mount(ctx widget.Context)

Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.

func (*BoxWidget) Padding 

func (b *BoxWidget) Padding(v float32) *BoxWidget

Padding sets uniform padding on all edges.

func (*BoxWidget) PaddingBottom 

func (b *BoxWidget) PaddingBottom(v float32) *BoxWidget

PaddingBottom sets the bottom padding.

func (*BoxWidget) PaddingLeft 

func (b *BoxWidget) PaddingLeft(v float32) *BoxWidget

PaddingLeft sets the left padding.

func (*BoxWidget) PaddingRight 

func (b *BoxWidget) PaddingRight(v float32) *BoxWidget

PaddingRight sets the right padding.

func (*BoxWidget) PaddingTop 

func (b *BoxWidget) PaddingTop(v float32) *BoxWidget

PaddingTop sets the top padding.

func (*BoxWidget) PaddingXY 

func (b *BoxWidget) PaddingXY(x, y float32) *BoxWidget

PaddingXY sets separate horizontal and vertical padding.

func (*BoxWidget) ResolvedDirection 

func (b *BoxWidget) ResolvedDirection() Direction

ResolvedDirection returns the effective layout direction. Priority: ReadonlySignal > Static.

func (*BoxWidget) Rounded 

func (b *BoxWidget) Rounded(r float32) *BoxWidget

Rounded sets a uniform border radius.

func (*BoxWidget) SetDirection 

func (b *BoxWidget) SetDirection(d Direction) *BoxWidget

SetDirection sets the layout direction for child widgets. 

primitives.Box(a, b, c).SetDirection(primitives.DirectionHorizontal)

func (*BoxWidget) ShadowLevel 

func (b *BoxWidget) ShadowLevel(level int) *BoxWidget

ShadowLevel sets the elevation shadow level (0-5).

func (*BoxWidget) Style 

func (b *BoxWidget) Style() BoxStyle

Style returns the current box style (read-only snapshot).

func (*BoxWidget) Unmount 

func (b *BoxWidget) Unmount()

Unmount is called when the box widget is removed from the widget tree. Implements widget.Lifecycle.

func (*BoxWidget) Width 

func (b *BoxWidget) Width(v float32) *BoxWidget

Width sets an explicit width.

type Direction 

type Direction uint8

Direction specifies the layout direction for child widgets within a container. 

const (
	// DirectionVertical lays out children from top to bottom (default).
	DirectionVertical Direction = iota

	// DirectionHorizontal lays out children from left to right.
	DirectionHorizontal
)

Direction constants.

func (Direction) String 

func (d Direction) String() string

String returns a human-readable name for the layout direction.

type ExpandedWidget added in v0.1.4 

type ExpandedWidget struct {
	widget.WidgetBase
	// contains filtered or unexported fields
}

ExpandedWidget wraps a widget to indicate it should fill all remaining space in a BoxWidget layout (HBox/VBox). Without Expanded, children take only their intrinsic size. With Expanded, the child receives all space left after fixed-size siblings are measured.

ExpandedWidget is transparent: it delegates Layout, Draw, Event, and Children entirely to its wrapped child. It serves only as a marker for the parent BoxWidget's two-pass layout algorithm.

Usage: 

primitives.HBox(
    leftPanel.Width(56),           // fixed 56px
    primitives.Expanded(editor),   // fills remaining
    rightPanel.Width(40),          // fixed 40px
)

Multiple Expanded children in the same BoxWidget split the remaining space equally: 

primitives.HBox(
    primitives.Expanded(left),     // 50% of remaining
    primitives.Expanded(right),    // 50% of remaining
)

func Expanded added in v0.1.4 

func Expanded(child widget.Widget) *ExpandedWidget

Expanded wraps a widget to mark it as filling remaining space in a BoxWidget. The child must not be nil.

func (*ExpandedWidget) AccessibilityActions added in v0.1.4 

func (e *ExpandedWidget) AccessibilityActions() []a11y.Action

AccessibilityActions delegates to the child if it implements a11y.Accessible.

func (*ExpandedWidget) AccessibilityHint added in v0.1.4 

func (e *ExpandedWidget) AccessibilityHint() string

AccessibilityHint delegates to the child if it implements a11y.Accessible.

func (*ExpandedWidget) AccessibilityLabel added in v0.1.4 

func (e *ExpandedWidget) AccessibilityLabel() string

AccessibilityLabel delegates to the child if it implements a11y.Accessible.

func (*ExpandedWidget) AccessibilityRole added in v0.1.4 

func (e *ExpandedWidget) AccessibilityRole() a11y.Role

AccessibilityRole delegates to the child if it implements a11y.Accessible, otherwise returns a11y.RoleNone.

func (*ExpandedWidget) AccessibilityState added in v0.1.4 

func (e *ExpandedWidget) AccessibilityState() a11y.State

AccessibilityState delegates to the child if it implements a11y.Accessible.

func (*ExpandedWidget) AccessibilityValue added in v0.1.4 

func (e *ExpandedWidget) AccessibilityValue() string

AccessibilityValue delegates to the child if it implements a11y.Accessible.

func (*ExpandedWidget) Child added in v0.1.4 

func (e *ExpandedWidget) Child() widget.Widget

Child returns the wrapped widget.

func (*ExpandedWidget) Children added in v0.1.4 

func (e *ExpandedWidget) Children() []widget.Widget

Children returns the wrapped child as a single-element slice.

func (*ExpandedWidget) Draw added in v0.1.4 

func (e *ExpandedWidget) Draw(ctx widget.Context, canvas widget.Canvas)

Draw delegates to the wrapped child, applying a transform for positioning.

func (*ExpandedWidget) Event added in v0.1.4 

func (e *ExpandedWidget) Event(ctx widget.Context, ev event.Event) bool

Event delegates to the wrapped child with coordinate translation for mouse and wheel events.

func (*ExpandedWidget) IsExpanded added in v0.1.4 

func (e *ExpandedWidget) IsExpanded() bool

IsExpanded returns true. Public API for querying expanded state.

func (*ExpandedWidget) Layout added in v0.1.4 

func (e *ExpandedWidget) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size

Layout delegates to the wrapped child and stores the resulting bounds.

type ImageFit 

type ImageFit uint8

ImageFit specifies how an image is sized relative to its container. 

const (
	// ImageFitContain scales the image to fit entirely within the container
	// while preserving aspect ratio. The image may not fill the entire
	// container.
	ImageFitContain ImageFit = iota

	// ImageFitCover scales the image to completely cover the container while
	// preserving aspect ratio. Parts of the image may be clipped.
	ImageFitCover

	// ImageFitFill stretches the image to exactly fill the container,
	// ignoring aspect ratio.
	ImageFitFill

	// ImageFitNone displays the image at its natural size, centered within
	// the container. Overflow is clipped.
	ImageFitNone
)

ImageFit constants.

func (ImageFit) String 

func (f ImageFit) String() string

String returns a human-readable name for the image fit mode.

type ImageSource 

type ImageSource interface {
	// Bounds returns the natural pixel dimensions of the image.
	Bounds() [2]float32
}

ImageSource provides the natural dimensions of an image.

Concrete implementations are provided by the rendering backend. The primitives package only queries the image bounds for layout; actual pixel data is drawn by the backend-specific Canvas implementation.

type ImageStyle 

type ImageStyle struct {
	// ExplicitWidth and ExplicitHeight override the natural image size.
	// Zero means use the natural dimension.
	ExplicitWidth  float32
	ExplicitHeight float32
	Fit            ImageFit
	Radius         float32
}

ImageStyle holds all visual styling for an ImageWidget.

type ImageWidget 

type ImageWidget struct {
	widget.WidgetBase
	// contains filtered or unexported fields
}

ImageWidget displays a raster image with configurable fit mode, optional rounded corners, and accessibility alt text.

ImageWidget implements widget.Widget and a11y.Accessible.

Create an ImageWidget with the Image constructor.

func Image 

func Image(source ImageSource) *ImageWidget

Image creates a new image widget with the given source.

The source provides the natural pixel dimensions of the image. If source is nil, the widget has zero natural size. 

img := primitives.Image(mySource).Size(200, 150).Cover()

func (*ImageWidget) AccessibilityActions 

func (w *ImageWidget) AccessibilityActions() []a11y.Action

AccessibilityActions returns nil. Images have no actions.

func (*ImageWidget) AccessibilityHint 

func (w *ImageWidget) AccessibilityHint() string

AccessibilityHint returns an empty string.

func (*ImageWidget) AccessibilityLabel 

func (w *ImageWidget) AccessibilityLabel() string

AccessibilityLabel returns the alt text.

func (*ImageWidget) AccessibilityRole 

func (w *ImageWidget) AccessibilityRole() a11y.Role

AccessibilityRole returns a11y.RoleImage.

func (*ImageWidget) AccessibilityState 

func (w *ImageWidget) AccessibilityState() a11y.State

AccessibilityState returns the default state.

func (*ImageWidget) AccessibilityValue 

func (w *ImageWidget) AccessibilityValue() string

AccessibilityValue returns an empty string.

func (*ImageWidget) Alt 

func (w *ImageWidget) Alt(text string) *ImageWidget

Alt sets the accessibility alt text.

func (*ImageWidget) AltText 

func (w *ImageWidget) AltText() string

AltText returns the accessibility alt text.

func (*ImageWidget) Children 

func (w *ImageWidget) Children() []widget.Widget

Children returns nil. Image is a leaf widget.

func (*ImageWidget) Contain 

func (w *ImageWidget) Contain() *ImageWidget

Contain is a shorthand for Fit(ImageFitContain).

func (*ImageWidget) Cover 

func (w *ImageWidget) Cover() *ImageWidget

Cover is a shorthand for Fit(ImageFitCover).

func (*ImageWidget) Draw 

func (w *ImageWidget) Draw(_ widget.Context, canvas widget.Canvas)

Draw renders the image placeholder.

The current implementation draws a light gray rectangle with a centered cross to indicate the image area. Full image rendering requires a Canvas implementation that supports DrawImage, which will be provided by the rendering backend.

func (*ImageWidget) Event 

func (w *ImageWidget) Event(_ widget.Context, _ event.Event) bool

Event returns false. Image widgets do not consume events.

func (*ImageWidget) Fill 

func (w *ImageWidget) Fill() *ImageWidget

Fill is a shorthand for Fit(ImageFitFill).

func (*ImageWidget) Fit 

func (w *ImageWidget) Fit(f ImageFit) *ImageWidget

Fit sets the image fit mode.

func (*ImageWidget) Layout 

func (w *ImageWidget) Layout(_ widget.Context, constraints geometry.Constraints) geometry.Size

Layout determines the widget size based on the image source bounds, the explicit size overrides, and the fit mode.

func (*ImageWidget) Rounded 

func (w *ImageWidget) Rounded(r float32) *ImageWidget

Rounded sets the border radius for clipping.

func (*ImageWidget) Size 

func (w *ImageWidget) Size(width, height float32) *ImageWidget

Size sets explicit width and height.

func (*ImageWidget) Source 

func (w *ImageWidget) Source() ImageSource

Source returns the image source.

func (*ImageWidget) Style 

func (w *ImageWidget) Style() ImageStyle

Style returns the current image style (read-only snapshot).

type Option 

type Option func(*RepaintBoundary)

Option configures a RepaintBoundary.

func WithDebugLabel 

func WithDebugLabel(label string) Option

WithDebugLabel sets an optional label for diagnostics and logging.

type RepaintBoundary 

type RepaintBoundary struct {
	widget.WidgetBase
	// contains filtered or unexported fields
}

RepaintBoundary is a display widget that caches its child subtree as a CPU-side pixel buffer (image.RGBA). When the child subtree is clean (no dirty widgets), the cached image is composited directly onto the parent canvas instead of re-executing Draw on every descendant.

This is the Flutter RepaintBoundary pattern: an explicit opt-in boundary that isolates expensive subtrees from the rest of the render tree. Users wrap widgets in RepaintBoundary at points where subtrees are expensive to draw and rarely change.

For large widgets (>= 128x128 pixels), RepaintBoundary uses scene.Scene with tile-parallel rendering via scene.Renderer, providing better performance for complex subtrees. Small widgets use the traditional gg.Context path to avoid overhead.

Cache lifecycle:

  • The cache is allocated on first draw (lazy).
  • The cache is invalidated when any descendant is dirty or the size changes.
  • The cache is freed on Unmount or when the widget is garbage collected.

RepaintBoundary implements widget.Widget and a11y.Accessible.

Example: 

expensive := primitives.Box(
    primitives.Text("Complex chart..."),
).Padding(16)

cached := primitives.NewRepaintBoundary(expensive)

func NewRepaintBoundary 

func NewRepaintBoundary(child widget.Widget, opts ...Option) *RepaintBoundary

NewRepaintBoundary creates a RepaintBoundary that caches the rendering of the given child widget.

If child is nil, the boundary renders nothing and reports zero size.

Options:

func (*RepaintBoundary) AccessibilityActions 

func (rb *RepaintBoundary) AccessibilityActions() []a11y.Action

AccessibilityActions returns nil.

func (*RepaintBoundary) AccessibilityHint 

func (rb *RepaintBoundary) AccessibilityHint() string

AccessibilityHint returns an empty string.

func (*RepaintBoundary) AccessibilityLabel 

func (rb *RepaintBoundary) AccessibilityLabel() string

AccessibilityLabel returns the debug label or empty string.

func (*RepaintBoundary) AccessibilityRole 

func (rb *RepaintBoundary) AccessibilityRole() a11y.Role

AccessibilityRole returns a11y.RoleGenericContainer.

func (*RepaintBoundary) AccessibilityState 

func (rb *RepaintBoundary) AccessibilityState() a11y.State

AccessibilityState returns the default state.

func (*RepaintBoundary) AccessibilityValue 

func (rb *RepaintBoundary) AccessibilityValue() string

AccessibilityValue returns an empty string.

func (*RepaintBoundary) CacheHits 

func (rb *RepaintBoundary) CacheHits() int

CacheHits returns how many times the cache was served instead of re-rendering.

func (*RepaintBoundary) CacheValid 

func (rb *RepaintBoundary) CacheValid() bool

CacheValid reports whether the cache currently holds valid content.

func (*RepaintBoundary) Child 

func (rb *RepaintBoundary) Child() widget.Widget

Child returns the wrapped child widget.

func (*RepaintBoundary) Children 

func (rb *RepaintBoundary) Children() []widget.Widget

Children returns the child widget, or nil if none.

func (*RepaintBoundary) DebugLabel 

func (rb *RepaintBoundary) DebugLabel() string

DebugLabel returns the diagnostic label, or empty string if none set.

func (*RepaintBoundary) Draw 

func (rb *RepaintBoundary) Draw(ctx widget.Context, canvas widget.Canvas)

Draw renders the child subtree, using the pixel cache when possible.

If the child subtree is clean and the cache is valid, the cached image is composited directly. Otherwise, the child is rendered into an offscreen buffer, the result is captured as the new cache, and then composited.

func (*RepaintBoundary) Event 

func (rb *RepaintBoundary) Event(ctx widget.Context, e event.Event) bool

Event dispatches events to the child.

func (*RepaintBoundary) InvalidateCache 

func (rb *RepaintBoundary) InvalidateCache()

InvalidateCache marks the cache as stale, forcing a re-render on the next draw pass. This is called automatically when descendants are dirty; manual invocation is rarely needed.

func (*RepaintBoundary) Layout 

func (rb *RepaintBoundary) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size

Layout delegates to the child and stores the resulting size.

func (*RepaintBoundary) Unmount 

func (rb *RepaintBoundary) Unmount()

Unmount releases the pixel cache and scene resources when the widget is removed from the tree.

type Shadow 

type Shadow struct {
	// Level is the elevation level from 0 (none) to maxShadowLevel.
	Level int
}

Shadow describes a box shadow with an integer elevation level (0-5).

Level 0 means no shadow. Higher levels produce progressively larger and more diffuse shadows. The rendering of each level is determined by the current theme; the primitives package uses a simple constant lookup.

func (Shadow) IsZero 

func (s Shadow) IsZero() bool

IsZero returns true if the shadow has no elevation.

type TextAlign 

type TextAlign = widget.TextAlign

TextAlign is an alias for widget.TextAlign for backward compatibility.

type TextOverflow 

type TextOverflow uint8

TextOverflow specifies how text behaves when it exceeds its container. 

const (
	// TextOverflowClip clips overflowing text at the container boundary.
	TextOverflowClip TextOverflow = iota

	// TextOverflowEllipsis truncates overflowing text and appends "...".
	TextOverflowEllipsis
)

TextOverflow constants.

func (TextOverflow) String 

func (o TextOverflow) String() string

String returns a human-readable name for the text overflow mode.

type TextStyle 

type TextStyle struct {
	FontSize   float32
	Color      widget.Color
	Bold       bool
	Align      TextAlign
	MaxLines   int
	Overflow   TextOverflow
	LineHeight float32
}

TextStyle holds all visual styling for a TextWidget.

type TextWidget 

type TextWidget struct {
	widget.WidgetBase
	// contains filtered or unexported fields
}

TextWidget displays static or reactive text content.

TextWidget implements widget.Widget and a11y.Accessible.

Create a TextWidget with Text (static) or TextFn (reactive).

Theme-Aware Default Color

By default, TextWidget uses the theme's OnSurface color for text when a ThemeProvider is available on the context. If no theme is set, the fallback is widget.ColorBlack. An explicit call to TextWidget.Color always takes precedence over the theme default.

func Text 

func Text(content string) *TextWidget

Text creates a new text widget with static content. 

label := primitives.Text("Hello World").FontSize(18).Bold()

func TextFn 

func TextFn(fn func() string) *TextWidget

TextFn creates a new text widget with reactive content.

The function fn is called during layout and draw to obtain the current text. When the function reads a signal's value, changes to that signal will cause re-layout and re-draw when the binding is set up externally. 

counter := state.NewSignal(0)
label := primitives.TextFn(func() string {
    return fmt.Sprintf("Count: %d", counter.Get())
}).FontSize(14)

func (*TextWidget) AccessibilityActions 

func (t *TextWidget) AccessibilityActions() []a11y.Action

AccessibilityActions returns nil. Text has no actions.

func (*TextWidget) AccessibilityHint 

func (t *TextWidget) AccessibilityHint() string

AccessibilityHint returns an empty string.

func (*TextWidget) AccessibilityLabel 

func (t *TextWidget) AccessibilityLabel() string

AccessibilityLabel returns the text content.

func (*TextWidget) AccessibilityRole 

func (t *TextWidget) AccessibilityRole() a11y.Role

AccessibilityRole returns a11y.RoleLabel.

func (*TextWidget) AccessibilityState 

func (t *TextWidget) AccessibilityState() a11y.State

AccessibilityState returns the default state.

func (*TextWidget) AccessibilityValue 

func (t *TextWidget) AccessibilityValue() string

AccessibilityValue returns an empty string.

func (*TextWidget) Align 

func (t *TextWidget) Align(a TextAlign) *TextWidget

Align sets horizontal text alignment.

func (*TextWidget) Bold 

func (t *TextWidget) Bold() *TextWidget

Bold enables bold font weight.

func (*TextWidget) Children 

func (t *TextWidget) Children() []widget.Widget

Children returns nil. Text is a leaf widget.

func (*TextWidget) Color 

func (t *TextWidget) Color(c widget.Color) *TextWidget

Color sets the text color explicitly.

An explicit color always takes precedence over the theme's default OnSurface color.

func (*TextWidget) Content 

func (t *TextWidget) Content() string

Content returns the current text content.

Resolution priority: [ContentSignal] > TextFn > static Text.

func (*TextWidget) ContentSignal 

func (t *TextWidget) ContentSignal(sig state.ReadonlySignal[string]) *TextWidget

ContentSignal binds the text content to a read-only reactive signal. When set, the signal value takes precedence over both TextFn and static content set via Text.

Because TextWidget is display-only, only state.ReadonlySignal is accepted (no write-back capability is needed). 

name := state.NewSignal("Alice")
label := primitives.Text("").ContentSignal(name).FontSize(14)

func (*TextWidget) Draw 

func (t *TextWidget) Draw(ctx widget.Context, canvas widget.Canvas)

Draw renders the text content.

The text color is resolved with the following priority:

  1. Explicit color set via TextWidget.Color (always wins)
  2. ThemeProvider's OnSurface color (if a theme is active)
  3. widget.ColorBlack (fallback when no theme is set)

func (*TextWidget) Ellipsis 

func (t *TextWidget) Ellipsis() *TextWidget

Ellipsis enables truncation with "..." when text overflows.

func (*TextWidget) Event 

func (t *TextWidget) Event(_ widget.Context, _ event.Event) bool

Event returns false. Text widgets do not consume events.

func (*TextWidget) FontSize 

func (t *TextWidget) FontSize(size float32) *TextWidget

FontSize sets the font size in logical pixels.

func (*TextWidget) IsReactive 

func (t *TextWidget) IsReactive() bool

IsReactive returns true if the widget uses a function or signal for its content.

func (*TextWidget) Layout 

func (t *TextWidget) Layout(_ widget.Context, constraints geometry.Constraints) geometry.Size

Layout measures the text and returns the constrained size.

Text measurement uses a simple character-width heuristic. Real font measurement is delegated to the Canvas implementation in production.

func (*TextWidget) LineHeight 

func (t *TextWidget) LineHeight(v float32) *TextWidget

LineHeight sets the line height multiplier. The default is 1.2.

func (*TextWidget) MaxLines 

func (t *TextWidget) MaxLines(n int) *TextWidget

MaxLines limits the number of displayed lines. Zero means unlimited.

func (*TextWidget) Mount 

func (t *TextWidget) Mount(ctx widget.Context)

Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.

func (*TextWidget) Style 

func (t *TextWidget) Style() TextStyle

Style returns the current text style (read-only snapshot).

func (*TextWidget) Unmount 

func (t *TextWidget) Unmount()

Unmount is called when the text widget is removed from the widget tree. Implements widget.Lifecycle.

type ThemeScopeWidget 

type ThemeScopeWidget struct {
	widget.WidgetBase
	// contains filtered or unexported fields
}

ThemeScopeWidget overrides the theme for a subtree of widgets.

All descendants of a ThemeScopeWidget receive the scoped ThemeProvider instead of the application-level theme. This enables use cases like a dark dialog inside a light application, a branded section, or a high-contrast widget region.

ThemeScopeWidget is transparent to layout: it delegates sizing entirely to its single child. If the scope has no child, it reports zero size.

Nested ThemeScopeWidgets follow the "nearest wins" rule, matching the Flutter InheritedWidget pattern. The priority chain is: 

Widget override > Nearest ThemeScope > App theme > Default

Create a ThemeScopeWidget with the ThemeScope constructor.

Example: 

darkTheme := material3.NewDark(widget.Hex(0x6750A4))
scoped := primitives.ThemeScope(darkTheme,
    primitives.Text("Dark text"),
    primitives.Box(
        primitives.Text("Also dark"),
    ).Padding(8),
)

func ThemeScope 

func ThemeScope(theme widget.ThemeProvider, children ...widget.Widget) *ThemeScopeWidget

ThemeScope creates a new ThemeScopeWidget that overrides the theme for the given children.

If multiple children are provided, they are wrapped in a Box container for vertical layout. A single child is used directly. If no children are provided, the scope has no child and reports zero size.

The theme parameter must not be nil; passing nil causes ThemeScope to behave as if no theme override is applied (the parent context theme is used).

func (*ThemeScopeWidget) Children 

func (ts *ThemeScopeWidget) Children() []widget.Widget

Children returns the child widget, or nil if none.

func (*ThemeScopeWidget) Draw 

func (ts *ThemeScopeWidget) Draw(ctx widget.Context, canvas widget.Canvas)

Draw renders the child with the scoped theme context.

func (*ThemeScopeWidget) Event 

func (ts *ThemeScopeWidget) Event(ctx widget.Context, e event.Event) bool

Event dispatches events to the child with the scoped theme context.

func (*ThemeScopeWidget) Layout 

func (ts *ThemeScopeWidget) Layout(ctx widget.Context, constraints geometry.Constraints) geometry.Size

Layout delegates sizing to the child widget, passing a context with the overridden theme.

func (*ThemeScopeWidget) SetTheme 

func (ts *ThemeScopeWidget) SetTheme(theme widget.ThemeProvider)

SetTheme changes the scoped theme.

func (*ThemeScopeWidget) Theme 

func (ts *ThemeScopeWidget) Theme() widget.ThemeProvider

Theme returns the ThemeProvider set on this scope.

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.