widget

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Apr 11, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultCalendarWidth  = 280.0
	DefaultCalendarHeight = 300.0
)

Default CalendarSelector dimensions.

View Source 
const (
	GradientModeH          = render.GradientModeH
	GradientModeV          = render.GradientModeV
	GradientModeFourCorner = render.GradientModeFourCorner
)
View Source 
const (
	// LayoutNone uses manual positioning; children keep their own X/Y.
	LayoutNone = core.LayoutNone
	// LayoutVBox stacks children vertically with spacing between them.
	LayoutVBox = core.LayoutVBox
	// LayoutHBox stacks children horizontally with spacing between them.
	LayoutHBox = core.LayoutHBox
	// LayoutGrid arranges children in a fixed-column grid.
	LayoutGrid = core.LayoutGrid
	// LayoutFlow arranges children left-to-right, wrapping to new rows when
	// the available width is exceeded.
	LayoutFlow = core.LayoutFlow
	// LayoutAnchor pins each child to a corner, edge, or center of the parent
	// using per-child anchor metadata. Use Component.AddAnchoredChild to add
	// children with explicit anchor positions.
	LayoutAnchor = core.LayoutAnchor
)
View Source 
const (
	AlignStart        = core.AlignStart        // left for VBox, top for HBox (default)
	AlignCenter       = core.AlignCenter       // center on cross-axis
	AlignEnd          = core.AlignEnd          // right for VBox, bottom for HBox
	AlignSpaceBetween = core.AlignSpaceBetween // distribute children evenly across main axis
)
View Source 
const (
	Horizontal = core.Horizontal
	Vertical   = core.Vertical
)
View Source 
const (
	AnchorTopLeft      = core.AnchorTopLeft
	AnchorTopCenter    = core.AnchorTopCenter
	AnchorTopRight     = core.AnchorTopRight
	AnchorMiddleLeft   = core.AnchorMiddleLeft
	AnchorCenter       = core.AnchorCenter
	AnchorMiddleRight  = core.AnchorMiddleRight
	AnchorBottomLeft   = core.AnchorBottomLeft
	AnchorBottomCenter = core.AnchorBottomCenter
	AnchorBottomRight  = core.AnchorBottomRight
)
View Source 
const (
	DefaultNavDrawerWidth    = 240
	DefaultNavDrawerDuration = 0.25 // seconds
)

Default NavDrawer dimensions and animation.

View Source 
const (
	DefaultNumberStepperWidth  = 120.0
	DefaultNumberStepperHeight = 28.0
)

Default NumberStepper dimensions.

View Source 
const (
	DefaultMeterWidth  = 200
	DefaultMeterHeight = 20
)

Default meter bar dimensions.

View Source 
const (
	DefaultScrollBarWidth  = 16
	DefaultScrollBarLength = 200
	MinScrollThumbSize     = 20
)

Default scrollbar dimensions.

View Source 
const (
	DefaultSliderWidth     = 200
	DefaultSliderHeight    = 20
	DefaultSliderThumbSize = 16
)

Default slider dimensions.

View Source 
const (
	Primary   = theme.Primary
	Secondary = theme.Secondary
	Accent    = theme.Accent
	Neutral   = theme.Neutral
	Danger    = theme.Danger
	Success   = theme.Success
	Warning   = theme.Warning
	Info      = theme.Info
	Custom1   = theme.Custom1
	Custom2   = theme.Custom2
	Custom3   = theme.Custom3
	Custom4   = theme.Custom4
	Custom5   = theme.Custom5
	Custom6   = theme.Custom6
	Custom7   = theme.Custom7
	Custom8   = theme.Custom8
	Custom9   = theme.Custom9
	Custom10  = theme.Custom10
	Custom11  = theme.Custom11
	Custom12  = theme.Custom12
	Custom13  = theme.Custom13
	Custom14  = theme.Custom14
	Custom15  = theme.Custom15
	Custom16  = theme.Custom16
	Custom17  = theme.Custom17
	Custom18  = theme.Custom18
	Custom19  = theme.Custom19
	Custom20  = theme.Custom20
	Custom21  = theme.Custom21
	Custom22  = theme.Custom22
	Custom23  = theme.Custom23
	Custom24  = theme.Custom24
	Custom25  = theme.Custom25
	Custom26  = theme.Custom26
	Custom27  = theme.Custom27
	Custom28  = theme.Custom28
	Custom29  = theme.Custom29
	Custom30  = theme.Custom30
	Custom31  = theme.Custom31
	Custom32  = theme.Custom32
	Custom33  = theme.Custom33
	Custom34  = theme.Custom34
	Custom35  = theme.Custom35
	Custom36  = theme.Custom36
	Custom37  = theme.Custom37
	Custom38  = theme.Custom38
	Custom39  = theme.Custom39
	Custom40  = theme.Custom40
	Custom41  = theme.Custom41
	Custom42  = theme.Custom42
	Custom43  = theme.Custom43
	Custom44  = theme.Custom44
	Custom45  = theme.Custom45
	Custom46  = theme.Custom46
	Custom47  = theme.Custom47
	Custom48  = theme.Custom48
	Custom49  = theme.Custom49
	Custom50  = theme.Custom50
	Custom51  = theme.Custom51
	Custom52  = theme.Custom52
	Custom53  = theme.Custom53
	Custom54  = theme.Custom54
	Custom55  = theme.Custom55
	Custom56  = theme.Custom56
)
View Source 
const (
	StateDefault       = core.StateDefault
	StateHover         = core.StateHover
	StateActive        = core.StateActive
	StateDisabled      = core.StateDisabled
	StateFocus         = core.StateFocus
	StateFocusHover    = core.StateFocusHover
	StateFocusActive   = core.StateFocusActive
	StateFocusDisabled = core.StateFocusDisabled
)
View Source 
const (
	BgNone      = core.BgNone
	BgSolid     = core.BgSolid
	BgNineSlice = core.BgNineSlice
	BgGradient  = core.BgGradient
)
View Source 
const (
	DefaultTimePickerWidth  = 180.0
	DefaultTimePickerHeight = 80.0
)

Default TimePicker dimensions.

View Source 
const (
	DefaultWindowWidth   = 400
	DefaultWindowHeight  = 300
	DefaultWindowMinW    = 120
	DefaultWindowMinH    = 80
	WindowTitleBarHeight = 32
	WindowResizeGripSize = 16
	DefaultWindowPadding = 8
)

Default window dimensions.

View Source 
const DefaultCheckboxGap = 8

DefaultCheckboxGap is the spacing between the box and label.

View Source 
const DefaultCheckboxInnerSize = 12

DefaultCheckboxInnerSize is the check mark inner size.

View Source 
const DefaultCheckboxSize = 20

DefaultCheckboxSize is the default box dimension.

View Source 
const DefaultRadioDotSize = 10

DefaultRadioDotSize is the inner dot dimension.

View Source 
const DefaultRadioGap = 8

DefaultRadioGap is the spacing between the circle and label.

View Source 
const DefaultRadioSize = 20

DefaultRadioSize is the outer circle dimension.

View Source 
const DefaultToggleHeight = 24

DefaultToggleHeight is the default track height.

View Source 
const DefaultToggleThumbSize = 20

DefaultToggleThumbSize is the default thumb diameter.

View Source 
const DefaultToggleWidth = 48

DefaultToggleWidth is the default track width.

View Source 
const GlyphSize = 48

GlyphSize is the pixel width and height of each glyph cell in the default spritesheet (default-glyphs.png).

View Source 
const TreeToggleSize = 16

TreeToggleSize is the default size (width and height) for tree toggle icon buttons returned by NewTreeToggle. Exported so render callbacks can use it for leaf-node spacer sizing.

Variables

View Source 
var (
	// ParseMarkup parses XML-like markup into TextSpan slices.
	ParseMarkup = markup.ParseMarkup

	// ParseColor parses a color string in any supported format.
	ParseColor = markup.ParseColor
)
View Source 
var AutoPadding = core.AutoPadding

AutoPadding is the sentinel Insets value meaning "use the component's built-in default padding". All four fields are -1.

View Source 
var DefaultColorPickerManager = &ColorPickerManager{}

DefaultColorPickerManager is the singleton used by ColorPicker widgets.

View Source 
var DefaultFocusManager = NewFocusManager()

DefaultFocusManager is the package-level focus manager used by form controls. Clicking a focusable component routes through this manager so that at most one component holds focus at a time.

View Source 
var DefaultInputManager = NewInputManager()

DefaultInputManager is the package-level InputManager singleton. Game logic and widgets read key state through this instead of ebiten directly.

View Source 
var DefaultMenuPopupManager = &MenuPopupManager{}

DefaultMenuPopupManager is the singleton used by Select and ContextMenu.

View Source 
var DefaultPopoverManager = &PopoverManager{}

DefaultPopoverManager is the singleton used by all Popover instances.

View Source 
var DefaultScheduler = &reactive.DefaultScheduler

DefaultScheduler is the package-level scheduler. It points into the internal reactive package so that Ref.Set() and Computed.markDirty() enqueue to the same scheduler that external callers flush.

View Source 
var DefaultStage = &StageManager{}

DefaultStage is the package-level stage singleton.

View Source 
var DefaultTheme = theme.DefaultTheme

DefaultTheme is the fallback theme used when no explicit theme is set. This variable is kept for backward compatibility, but EffectiveTheme() reads *theme.DefaultThemeRef so that the root package can redirect the canonical default by setting theme.DefaultThemeRef = &willowui.DefaultTheme.

View Source 
var DefaultToastManager = &ToastManager{
	maxStack: 4,
	marginX:  16,
	marginY:  16,
	fontSize: 14,
}

DefaultToastManager is the package-level singleton used by ShowToast.

View Source 
var DefaultTooltipManager = &TooltipManager{Enabled: true}

DefaultTooltipManager is the package-level singleton used by all components.

View Source 
var DefaultWindowManager = NewWindowManager()

DefaultWindowManager is the package-level window manager. Register windows here so they automatically sort to the top on click.

View Source 
var GradientBackground = core.GradientBackground

GradientBackground creates a gradient background.

View Source 
var NewColorPropStates = theme.NewColorPropStates

NewColorPropStates creates a ColorProperty from per-state colors.

View Source 
var SliceBackground = core.SliceBackground

SliceBackground creates a nine-slice background.

View Source 
var SolidBackground = core.SolidBackground

SolidBackground creates a solid-color background.

Functions

func BindSortableListItems 

func BindSortableListItems[T any](sl *SortableList, items *Array[T])

BindSortableListItems binds a reactive Array[T] to a SortableList. This is a package-level generic function because Go does not support generic methods.

func GlyphScale 

func GlyphScale(img engine.Image, desiredPx float64) float64

GlyphScale returns the uniform scale factor to display img at desiredPx width. For a 48×48 spritesheet glyph displayed at 9px: GlyphScale(img, 9) ≈ 0.1875.

func IconArrowDown 

func IconArrowDown() engine.Image

func IconArrowUp 

func IconArrowUp() engine.Image

func IconCheckmark 

func IconCheckmark() engine.Image

func IconChevronDown 

func IconChevronDown() engine.Image

func IconChevronLeft 

func IconChevronLeft() engine.Image

func IconChevronRight 

func IconChevronRight() engine.Image

func IconChevronUp 

func IconChevronUp() engine.Image

func IconCloseX 

func IconCloseX() engine.Image

func IconFilter 

func IconFilter() engine.Image

func IconGripDotsH 

func IconGripDotsH() engine.Image

func IconGripDotsSquare 

func IconGripDotsSquare() engine.Image

func IconGripDotsV 

func IconGripDotsV() engine.Image

func IconGripLinesH 

func IconGripLinesH() engine.Image

func IconGripLinesV 

func IconGripLinesV() engine.Image

func IconHamburger 

func IconHamburger() engine.Image

func IconMinus 

func IconMinus() engine.Image

func IconPasswordDot 

func IconPasswordDot() engine.Image

func IconPlus 

func IconPlus() engine.Image

func IconRadioDot 

func IconRadioDot() engine.Image

func IconSearch 

func IconSearch() engine.Image

func LayoutNineSlice 

func LayoutNineSlice(nodes *NineSliceNodes, ns *NineSlice, w, h float64)

LayoutNineSlice is an exported wrapper for render.LayoutNineSlice. Used for testing.

func LerpColor 

func LerpColor(a, b sg.Color, t float64) sg.Color

LerpColor is an exported wrapper for render.LerpColor. Used for testing.

func PasswordDotGlyph 

func PasswordDotGlyph() engine.Image

PasswordDotGlyph returns the procedural dot glyph used for password masking.

func RoundedRectBorderMesh 

func RoundedRectBorderMesh(w, h, r, bw float64, segments int) ([]engine.Vertex, []uint16)

RoundedRectBorderMesh is an exported wrapper for render.RoundedRectBorderMesh. Used for testing.

func RoundedRectGradientMesh 

func RoundedRectGradientMesh(w, h, cornerRadius float64, segments int, g *GradientColors) ([]engine.Vertex, []uint16)

RoundedRectGradientMesh is an exported wrapper for render.RoundedRectGradientMesh. Used for testing.

func RoundedRectPoints 

func RoundedRectPoints(w, h, r float64, segments int) []sg.Vec2

RoundedRectPoints is an exported wrapper for render.RoundedRectPoints. Used for testing.

func SetGlyphSheet 

func SetGlyphSheet(pngData []byte)

SetGlyphSheet stores the raw PNG bytes of the default glyph spritesheet. Called by the root willowui package at init time.

func SetRowClickSelects 

func SetRowClickSelects(col *DataTableColumn, enable bool)

SetRowClickSelects configures whether clicking anywhere on a row triggers the selection toggle for a SelectionColumn. Call this on the DataTableColumn returned by SelectionColumn.

By default row-click selection is off — only clicking the checkbox/radio toggles selection. Enable it for an email-inbox-style UX where clicking the entire row selects it.

func SetScene 

func SetScene(s *sg.Scene)

SetScene registers the active scene so UI components can read injected keyboard input from test runners. The most recently registered non-nil scene is retained as a fallback when active scene is nil.

func SetSearchBoxFunc 

func SetSearchBoxFunc[T any](sb *SearchBox, results *Array[T], fn func(query string) []T)

SetSearchBoxFunc sets the automatic search callback that returns a result slice.

func SetSearchBoxIntoFunc 

func SetSearchBoxIntoFunc[T any](sb *SearchBox, results *Array[T], fn func(query string, results *Array[T]))

SetSearchBoxIntoFunc sets the advanced search callback that directly mutates the result array.

func ShowToast 

func ShowToast(message string, variant Variant, opts ...ToastOption)

ShowToast shows a toast via DefaultToastManager with the given variant. The variant selects the semantic color (Info, Success, Warning, Danger). Pass theme.Primary or omit for the default appearance.

func SubRegion 

func SubRegion(base sg.TextureRegion, x, y, w, h uint16) sg.TextureRegion

SubRegion is an exported wrapper for render.SubRegion. Used for testing.

func TreeCollapseGlyph 

func TreeCollapseGlyph() engine.Image

TreeCollapseGlyph returns the collapse glyph image. Used for testing.

func TreeExpandGlyph 

func TreeExpandGlyph() engine.Image

TreeExpandGlyph returns the expand glyph image. Used for testing.

func UpdateEllipsisLabel 

func UpdateEllipsisLabel(comp *Component, text string)

UpdateEllipsisLabel updates the text of an EllipsisLabel component.

func WordBoundaries 

func WordBoundaries(runes []rune, pos int) (lo, hi int)

wordBoundaries returns the start (inclusive) and end (exclusive) rune indices of the word surrounding pos. A "word" is a contiguous run of letters/digits; everything else is a contiguous run of non-word chars. WordBoundaries is the exported equivalent of wordBoundaries, for use by the root package tests.

Types

type Accordion 

type Accordion struct {
	Component
	// contains filtered or unexported fields
}

Accordion is a vertically stacked list of collapsible sections, each with a header row and an arbitrary content panel.

func NewAccordion 

func NewAccordion(name string) *Accordion

NewAccordion creates an Accordion with default settings.

func (*Accordion) AddSection 

func (a *Accordion) AddSection(section AccordionSection) *Accordion

AddSection appends a section to the accordion and returns the accordion for chaining.

func (*Accordion) BindExpanded 

func (a *Accordion) BindExpanded(ref *Ref[string])

BindExpanded binds the expanded section ID to a reactive Ref. In exclusive mode this is the single open section's ID (or "" when all are collapsed). In non-exclusive mode this tracks the most recently toggled section.

func (*Accordion) Close 

func (a *Accordion) Close(id string)

Close collapses a section by ID.

func (*Accordion) Dispose 

func (a *Accordion) Dispose()

Dispose cleans up the accordion.

func (*Accordion) ExpandedID 

func (a *Accordion) ExpandedID() string

ExpandedID returns the ID of the currently expanded section (first found), or "" if none are expanded.

func (*Accordion) IsExpanded 

func (a *Accordion) IsExpanded(id string) bool

IsExpanded returns whether a section is expanded.

func (*Accordion) Open 

func (a *Accordion) Open(id string)

Open expands a section by ID.

func (*Accordion) RemoveSection 

func (a *Accordion) RemoveSection(id string)

RemoveSection removes a section by ID.

func (*Accordion) Section 

func (a *Accordion) Section(id string) *AccordionSection

Section returns a pointer to the AccordionSection data for the given ID, or nil.

func (*Accordion) SetAnimated 

func (a *Accordion) SetAnimated(v bool)

SetAnimated enables or disables expand/collapse animation.

func (*Accordion) SetExclusive 

func (a *Accordion) SetExclusive(v bool)

SetExclusive sets whether only one section can be open at a time.

func (*Accordion) SetExpanded 

func (a *Accordion) SetExpanded(id string, v bool)

SetExpanded sets the expanded state of a section.

func (*Accordion) SetFont 

func (a *Accordion) SetFont(source *sg.FontFamily, size float64)

SetFont sets the font source used for section header labels.

func (*Accordion) SetOnToggle 

func (a *Accordion) SetOnToggle(fn func(id string, expanded bool))

SetOnToggle sets the callback invoked when a section is toggled.

func (*Accordion) SetSize 

func (a *Accordion) SetSize(w, h float64)

SetSize sets the accordion dimensions.

func (*Accordion) Toggle 

func (a *Accordion) Toggle(id string)

Toggle toggles a section's expanded state.

func (*Accordion) Update 

func (a *Accordion) Update(dt float32)

Update advances any active expand/collapse animations.

type AccordionSection 

type AccordionSection struct {
	ID      string
	Label   string
	Icon    sg.TextureRegion // zero value = no icon
	Content *Component
}

AccordionSection defines a section to add to an Accordion.

type Alignment 

type Alignment = core.Alignment

Alignment controls child positioning. Used for both cross-axis (Align) and main-axis (Justify) in VBox/HBox layouts.

type Anchor 

type Anchor = core.Anchor

Anchor identifies a position within a parent container.

type AnchorLayout 

type AnchorLayout struct {
	Panel
}

AnchorLayout is a Panel whose Layout is pre-set to LayoutAnchor. It is a convenience wrapper around Panel + LayoutAnchor; all anchor functionality lives on Component.

Prefer using a plain Panel (or Component) with Layout = LayoutAnchor and Component.AddAnchoredChild for new code. AnchorLayout is kept for compatibility with existing code and XML templates.

func NewAnchorLayout 

func NewAnchorLayout(name string) *AnchorLayout

NewAnchorLayout creates an AnchorLayout container.

type AnimPlayMode 

type AnimPlayMode int

AnimPlayMode controls how an AnimatedImage loops. 

const (
	AnimPlayOnce     AnimPlayMode = iota // play once, stop at last frame
	AnimPlayLoop                         // restart from frame 0
	AnimPlayPingPong                     // reverse at each end
)

type AnimatedImage 

type AnimatedImage struct {
	Component
	// contains filtered or unexported fields
}

AnimatedImage extends Image to play back a frame-strip sprite animation, cycling through regions at a configurable FPS.

func NewAnimatedImage 

func NewAnimatedImage(name string) *AnimatedImage

NewAnimatedImage creates an AnimatedImage widget with no frames set.

func (*AnimatedImage) CurrentFrame 

func (a *AnimatedImage) CurrentFrame() int

CurrentFrame returns the current frame index.

func (*AnimatedImage) FrameCount 

func (a *AnimatedImage) FrameCount() int

FrameCount returns the number of frames in the animation.

func (*AnimatedImage) IsPlaying 

func (a *AnimatedImage) IsPlaying() bool

IsPlaying returns true if the animation is currently playing.

func (*AnimatedImage) LoadGIF 

func (a *AnimatedImage) LoadGIF(g *gif.GIF)

LoadGIF loads frames from a decoded GIF, using its built-in per-frame delays and compositing each frame onto a full canvas.

func (*AnimatedImage) Pause 

func (a *AnimatedImage) Pause()

Pause halts playback without resetting the frame index.

func (*AnimatedImage) Play 

func (a *AnimatedImage) Play()

Play starts or resumes playback.

func (*AnimatedImage) SetAtlas 

func (a *AnimatedImage) SetAtlas(img engine.Image, frameWidth, frameHeight int)

SetAtlas auto-slices an atlas image into frames of the given size, scanning left-to-right, top-to-bottom. Each frame is extracted via SubImage so the sprite node renders one frame at a time.

func (*AnimatedImage) SetCornerRadius 

func (a *AnimatedImage) SetCornerRadius(r float64)

SetCornerRadius sets the corner rounding. -1 means full pill.

func (*AnimatedImage) SetFPS 

func (a *AnimatedImage) SetFPS(fps float64)

SetFPS sets the playback speed in frames per second.

func (*AnimatedImage) SetFrame 

func (a *AnimatedImage) SetFrame(n int)

SetFrame jumps to a specific frame index.

func (*AnimatedImage) SetFrames 

func (a *AnimatedImage) SetFrames(frames []sg.TextureRegion)

SetFrames sets an explicit list of texture regions as animation frames.

func (*AnimatedImage) SetOnComplete 

func (a *AnimatedImage) SetOnComplete(fn func())

SetOnComplete sets a callback fired when a non-looping animation finishes.

func (*AnimatedImage) SetOnFrameChanged 

func (a *AnimatedImage) SetOnFrameChanged(fn func(frame int))

SetOnFrameChanged sets a callback fired each time the frame index changes.

func (*AnimatedImage) SetPlayMode 

func (a *AnimatedImage) SetPlayMode(mode AnimPlayMode)

SetPlayMode sets the loop behavior.

func (*AnimatedImage) SetScaleMode 

func (a *AnimatedImage) SetScaleMode(mode ImageScaleMode)

SetScaleMode sets how the current frame is scaled within the widget bounds.

func (*AnimatedImage) SetSize 

func (a *AnimatedImage) SetSize(w, h float64)

SetSize sets the widget dimensions.

func (*AnimatedImage) SetTint 

func (a *AnimatedImage) SetTint(c sg.Color)

SetTint sets the color multiplied over the image.

func (*AnimatedImage) Stop 

func (a *AnimatedImage) Stop()

Stop halts playback and resets to frame 0.

func (*AnimatedImage) Update 

func (a *AnimatedImage) Update(dt float64)

Update advances the animation by dt seconds. Called automatically via OnUpdate.

func (*AnimatedImage) UpdateVisuals 

func (a *AnimatedImage) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

type Array 

type Array[T any] = reactive.Array[T]

func NewArray 

func NewArray[T any]() *Array[T]

NewArray creates a new reactive array.

func NewArrayFrom 

func NewArrayFrom[T any](items []T) *Array[T]

NewArrayFrom creates a reactive array from an existing slice.

type Background 

type Background = core.Background

Background describes how to render a component's background.

type BackgroundProperty 

type BackgroundProperty = theme.BackgroundProperty

BackgroundProperty holds a background value for each component state.

type BackgroundType 

type BackgroundType = core.BackgroundType

BackgroundType tags the kind of background rendering.

type Badge 

type Badge struct {
	Component
	// contains filtered or unexported fields
}

Badge is a small pill or dot overlay that displays a count, label, or status indicator. It supports two display modes: label mode (short text in a pill shape) and dot mode (small filled circle, no text).

func NewBadge 

func NewBadge(name string, source *sg.FontFamily, displaySize float64) *Badge

NewBadge creates a Badge with the given name, font source, and display size.

func (*Badge) SetCount 

func (b *Badge) SetCount(n int)

SetCount sets the text to the string representation of n, clamped by MaxCount.

func (*Badge) SetDotMode 

func (b *Badge) SetDotMode(v bool)

SetDotMode enables or disables dot mode (small circle, no text).

func (*Badge) SetMaxCount 

func (b *Badge) SetMaxCount(n int)

SetMaxCount sets the maximum displayed count. Values above this show "N+". Default is 99. Set to 0 to disable truncation.

func (*Badge) SetPadding 

func (b *Badge) SetPadding(top, right, bottom, left float64)

SetPadding overrides the theme padding with per-instance values.

func (*Badge) SetSize 

func (b *Badge) SetSize(w, h float64)

SetSize overrides the auto-size dimensions.

func (*Badge) SetText 

func (b *Badge) SetText(text string)

SetText updates the displayed text and re-sizes if in auto-size mode.

func (*Badge) SizeToContent 

func (b *Badge) SizeToContent()

SizeToContent auto-sizes the badge to fit its content plus padding.

func (*Badge) Text 

func (b *Badge) Text() string

Text returns the current text content.

func (*Badge) UpdateVisuals 

func (b *Badge) UpdateVisuals()

UpdateVisuals applies theme colors and corner radius.

type BindHandle 

type BindHandle uint64

BindHandle identifies a registered keybind for later removal.

type Button 

type Button struct {
	Component
	// contains filtered or unexported fields
}

Button is an interactive component with a colored background and centered text label. Visual state (normal, hovered, pressed, disabled) is driven by theme colors and updated via UpdateVisuals.

func NewButton 

func NewButton(name string, text string, source *sg.FontFamily, displaySize float64) *Button

NewButton creates a Button with the given name, text label, font source, and display size. If displaySize is 0, the native atlas size is used.

func (*Button) AutoSize 

func (b *Button) AutoSize() bool

AutoSize reports whether the button auto-sizes to fit its text.

func (*Button) BindText 

func (b *Button) BindText(ref *Ref[string])

BindText binds the button's label to a reactive Ref[string]. The label updates automatically whenever the ref changes. Any previous binding is stopped first.

func (*Button) Dispose 

func (b *Button) Dispose()

Dispose cleans up the button and its label.

func (*Button) HasOnClickCallback 

func (b *Button) HasOnClickCallback() bool

HasOnClickCallback reports whether an onClick callback is registered.

func (*Button) LabelHeight 

func (b *Button) LabelHeight() float64

LabelHeight returns the height of the button's text label.

func (*Button) LabelLabel 

func (b *Button) LabelLabel() *Label

LabelLabel returns the button's label widget, or nil if none.

func (*Button) LabelText 

func (b *Button) LabelText() string

LabelText returns the current text of the button's label, or "" if none.

func (*Button) LabelWidth 

func (b *Button) LabelWidth() float64

LabelWidth returns the width of the button's text label.

func (*Button) SetAutoSize 

func (b *Button) SetAutoSize(v bool)

SetAutoSize enables or disables automatic sizing to fit text content. When enabled, the button resizes on every SetText call. When disabled (the default after any explicit SetSize call), the button keeps its current dimensions.

func (*Button) SetEnabled 

func (b *Button) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*Button) SetOnClick 

func (b *Button) SetOnClick(fn func())

SetOnClick sets the callback invoked when the button is clicked.

func (*Button) SetSize 

func (b *Button) SetSize(w, h float64)

SetSize sets the button dimensions and updates the background, label position, and hit shape so the button is immediately clickable. Calling SetSize disables auto-size — the button will no longer resize when SetText is called.

func (*Button) SetText 

func (b *Button) SetText(t string)

SetText updates the button's label text. If auto-size is enabled (the default), the button resizes to fit the new text content.

func (*Button) SimulateOnClick 

func (b *Button) SimulateOnClick()

SimulateOnClick invokes the onClick callback directly if one is set. Intended for unit tests.

func (*Button) TextOY 

func (b *Button) TextOY() float64

TextOY returns the current text vertical offset from the theme. Used for testing.

func (*Button) UpdateVisuals 

func (b *Button) UpdateVisuals()

UpdateVisuals applies theme colors based on the current interaction state.

type CalendarSelector 

type CalendarSelector struct {
	Component
	// contains filtered or unexported fields
}

CalendarSelector is a month-grid date picker with prev/next month navigation. It supports inline mode (always visible) and popup mode (trigger button opens a floating calendar overlay via PopoverManager).

func NewCalendarSelector 

func NewCalendarSelector(name string, source *sg.FontFamily, displaySize float64) *CalendarSelector

NewCalendarSelector creates a CalendarSelector with today's date selected.

func (*CalendarSelector) BindDate 

func (cs *CalendarSelector) BindDate(ref *Ref[time.Time])

BindDate binds the selected date to a reactive Ref. Changes to the Ref update the calendar, and user selections update the Ref.

func (*CalendarSelector) ClearMaxDate 

func (cs *CalendarSelector) ClearMaxDate()

ClearMaxDate removes the maximum date constraint.

func (*CalendarSelector) ClearMinDate 

func (cs *CalendarSelector) ClearMinDate()

ClearMinDate removes the minimum date constraint.

func (*CalendarSelector) ClosePopup 

func (cs *CalendarSelector) ClosePopup()

ClosePopup closes the popup calendar (popup mode only).

func (*CalendarSelector) Date 

func (cs *CalendarSelector) Date() time.Time

Date returns the currently selected date.

func (*CalendarSelector) Dispose 

func (cs *CalendarSelector) Dispose()

Dispose cleans up the calendar.

func (*CalendarSelector) IsPopupMode 

func (cs *CalendarSelector) IsPopupMode() bool

IsPopupMode returns true if the calendar is in popup mode.

func (*CalendarSelector) NextButton 

func (cs *CalendarSelector) NextButton() *Button

NextButton returns the next-month navigation button.

func (*CalendarSelector) OpenPopup 

func (cs *CalendarSelector) OpenPopup()

OpenPopup opens the popup calendar (popup mode only).

func (*CalendarSelector) PrevButton 

func (cs *CalendarSelector) PrevButton() *Button

PrevButton returns the previous-month navigation button.

func (*CalendarSelector) SetDate 

func (cs *CalendarSelector) SetDate(t time.Time)

SetDate sets the selected date and navigates to its month.

func (*CalendarSelector) SetEnabled 

func (cs *CalendarSelector) SetEnabled(v bool)

SetEnabled enables or disables the calendar.

func (*CalendarSelector) SetMaxDate 

func (cs *CalendarSelector) SetMaxDate(t time.Time)

SetMaxDate sets the maximum selectable date.

func (*CalendarSelector) SetMinDate 

func (cs *CalendarSelector) SetMinDate(t time.Time)

SetMinDate sets the minimum selectable date.

func (*CalendarSelector) SetMonth 

func (cs *CalendarSelector) SetMonth(year, month int)

SetMonth navigates the calendar view to a specific year and month.

func (*CalendarSelector) SetOnDateSelected 

func (cs *CalendarSelector) SetOnDateSelected(fn func(time.Time))

SetOnDateSelected sets the callback fired when a day is clicked.

func (*CalendarSelector) SetPopupMode 

func (cs *CalendarSelector) SetPopupMode(v bool)

SetPopupMode switches between inline and popup display.

func (*CalendarSelector) SetSize 

func (cs *CalendarSelector) SetSize(w, h float64)

SetSize resizes the calendar and repositions sub-components.

func (*CalendarSelector) TriggerButton 

func (cs *CalendarSelector) TriggerButton() *Button

TriggerButton returns the popup mode trigger button.

func (*CalendarSelector) UpdateVisuals 

func (cs *CalendarSelector) UpdateVisuals()

UpdateVisuals applies theme colors to all sub-components.

type CellClipMode 

type CellClipMode int

CellClipMode controls how cell content is clipped when it overflows. 

const (
	ClipEllipsis CellClipMode = iota // truncate with "..."
	ClipMask                         // use a mask to clip content
)

type CellCoord 

type CellCoord struct {
	Row, Col int
}

CellCoord identifies a cell by row and column.

type CellStyle 

type CellStyle struct {
	Align        sg.TextAlign                    // text alignment within the cell
	Color        sg.Color                        // text color override (zero = theme default)
	FontSize     float64                         // font size override (0 = table font size)
	Sharpness    float64                         // SDF sharpness override (0 = default)
	OnPostUpdate func(data any, comp *Component) // called after UpdateCell with the row data and cell component
}

CellStyle holds styling overrides for DataTable cells and headers. Zero values mean "use default" (theme color, table font/size, left-aligned).

type Checkbox 

type Checkbox struct {
	Component
	// contains filtered or unexported fields
}

Checkbox is a toggle control with a box and check mark, plus an optional label.

func NewCheckbox 

func NewCheckbox(name string, text string, source *sg.FontFamily, displaySize float64) *Checkbox

NewCheckbox creates a Checkbox with the given label text, font source, and display size.

func (*Checkbox) BindValue 

func (c *Checkbox) BindValue(ref *Ref[bool])

BindValue binds the checkbox to a reactive Ref[bool].

func (*Checkbox) BoxNode 

func (c *Checkbox) BoxNode() *sg.Node

BoxNode returns the border box node. Used for testing.

func (*Checkbox) CheckNode 

func (c *Checkbox) CheckNode() *sg.Node

CheckNode returns the inner check fill node. Used for testing.

func (*Checkbox) CheckboxLabel 

func (c *Checkbox) CheckboxLabel() *Label

CheckboxLabel returns the optional label widget, or nil. Used for testing.

func (*Checkbox) Checked 

func (c *Checkbox) Checked() bool

Checked returns the current checked state.

func (*Checkbox) Dispose 

func (c *Checkbox) Dispose()

Dispose stops reactive watches and disposes children.

func (*Checkbox) SetCheckIcon 

func (c *Checkbox) SetCheckIcon(img engine.Image)

SetCheckIcon replaces the default filled-square check mark with a custom image (e.g. a pixel-art checkmark glyph). The image is rendered at 1:1 pixel scale, centered in the box.

func (*Checkbox) SetChecked 

func (c *Checkbox) SetChecked(v bool)

SetChecked sets the checked state.

func (*Checkbox) SetEnabled 

func (c *Checkbox) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*Checkbox) SetOnChange 

func (c *Checkbox) SetOnChange(fn func(bool))

SetOnChange sets the callback invoked when checked state changes.

func (*Checkbox) SetText 

func (c *Checkbox) SetText(text string)

SetText sets the checkbox label text.

func (*Checkbox) UpdateVisuals 

func (c *Checkbox) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

type ColorMode 

type ColorMode int

ColorMode selects which input mode the picker popup displays. 

const (
	ColorModeHex ColorMode = iota
	ColorModeRGB           // 0–255
	ColorModeHSV           // internal gradient representation
	ColorModeHSL
	ColorModeFloat // sg.Color 0–1
)

type ColorPicker 

type ColorPicker struct {
	Component
	// contains filtered or unexported fields
}

ColorPicker is a swatch + label trigger that opens a floating picker popup.

func NewColorPicker 

func NewColorPicker(name string, source *sg.FontFamily, displaySize float64) *ColorPicker

NewColorPicker creates a new ColorPicker trigger.

func (*ColorPicker) BindValue 

func (cp *ColorPicker) BindValue(ref *Ref[sg.Color])

BindValue binds a *Ref[sg.Color] so the picker writes back to it.

func (*ColorPicker) Cancel 

func (cp *ColorPicker) Cancel()

Cancel programmatically cancels the picker, restoring the original color.

func (*ColorPicker) Close 

func (cp *ColorPicker) Close()

Close programmatically commits and closes the picker popup.

func (*ColorPicker) Open 

func (cp *ColorPicker) Open()

Open programmatically opens the picker popup.

func (*ColorPicker) SetDefaultMode 

func (cp *ColorPicker) SetDefaultMode(mode ColorMode)

SetDefaultMode sets the color mode shown first when the popup opens.

func (*ColorPicker) SetOnChange 

func (cp *ColorPicker) SetOnChange(fn func(sg.Color))

SetOnChange sets a callback invoked whenever the color changes (each drag step).

func (*ColorPicker) SetOnCommit 

func (cp *ColorPicker) SetOnCommit(fn func(sg.Color))

SetOnCommit sets a callback invoked when the popup closes with a committed value.

func (*ColorPicker) SetShowAlpha 

func (cp *ColorPicker) SetShowAlpha(show bool)

SetShowAlpha controls whether the alpha channel is editable in the popup.

func (*ColorPicker) SetSize 

func (cp *ColorPicker) SetSize(w, h float64)

SetSize sets the trigger dimensions.

func (*ColorPicker) SetValue 

func (cp *ColorPicker) SetValue(c sg.Color)

SetValue sets the current color without opening the popup.

func (*ColorPicker) UpdateVisuals 

func (cp *ColorPicker) UpdateVisuals()

UpdateVisuals updates the trigger's visual appearance based on state and theme.

func (*ColorPicker) Value 

func (cp *ColorPicker) Value() sg.Color

Value returns the current color.

type ColorPickerManager 

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

ColorPickerManager manages the single active floating color picker popup.

func (*ColorPickerManager) IsOpen 

func (m *ColorPickerManager) IsOpen() bool

IsOpen returns true if a picker popup is currently visible.

func (*ColorPickerManager) Show 

func (m *ColorPickerManager) Show(trigger *ColorPicker)

Show opens the color picker popup for the given trigger.

type ColorProperty 

type ColorProperty = theme.ColorProperty

ColorProperty holds a color value for each component state.

type Component 

type Component struct {

	// Layout mode and configuration.
	Layout      LayoutMode
	GridColumns int
	Spacing     float64
	FlowRowGap  float64   // vertical gap between rows in LayoutFlow; falls back to Spacing when zero
	Align       Alignment // cross-axis alignment
	Justify     Alignment // main-axis alignment

	// Position and size.
	X, Y             float64
	OffsetX, OffsetY float64 // user offset applied on top of layout-computed position
	Width, Height    float64

	// Constraints.
	MinWidth, MinHeight float64
	MaxWidth, MaxHeight float64

	// Fill stretches the child to match the parent's content dimension.
	Fill FillMode

	// Grow is a flex-like weight for proportional sizing in HBox/VBox.
	// Children with Grow > 0 share remaining space after fixed children.
	Grow int

	// Insets.
	Padding Insets
	Margin  Insets

	// Focus navigation flags. Disabled by default; interactive widgets
	// opt in by setting these in their constructors.
	Focusable          bool // can receive keyboard focus
	AllowTab           bool // participates in Tab/Shift+Tab cycling
	AllowSpatial       bool // participates in arrow-key spatial navigation
	InterceptArrows    bool // wants to handle arrow keys before spatial nav
	ConsumeHandledKeys bool // when HandleKey returns true, also consume from InputManager (default true)
	// contains filtered or unexported fields
}

Component is the base type for all WillowUI widgets. It wraps a sg.Node container and provides layout, state tracking, and dirty flag propagation.

func NewComponent 

func NewComponent(name string) *Component

NewComponent creates a new Component with sensible defaults. The underlying sg.Node is a container with pointer callbacks wired for hover and pressed state tracking.

func NewFlow 

func NewFlow(name string) *Component

NewFlow creates a Component with LayoutFlow pre-configured.

func NewHBox 

func NewHBox(name string) *Component

NewHBox creates a Component with LayoutHBox pre-configured.

func NewVBox 

func NewVBox(name string) *Component

NewVBox creates a Component with LayoutVBox pre-configured.

func (*Component) AddAnchoredChild 

func (c *Component) AddAnchoredChild(child UIElement, anchor Anchor, offsetX, offsetY float64)

AddAnchoredChild adds a child pinned to the given anchor with pixel offsets. The parent's Layout must be LayoutAnchor for anchor positioning to take effect.

func (*Component) AddChild 

func (c *Component) AddChild(child UIElement)

AddChild appends a child component. Both the Component tree and the underlying willow Node tree are updated. Accepts any UIElement (all widget types implement this interface).

func (*Component) AddRawChild 

func (c *Component) AddRawChild(node *sg.Node)

AddRawChild adds a raw willow node as a child of this component's node. Use this when adding nodes that are not WillowUI components, such as nodes created with willow.NewSprite or willow.NewText.

func (*Component) AddToNode 

func (c *Component) AddToNode(parent *sg.Node)

AddToNode adds this component's node as a child of parent. It also applies any pending layout so components with VBox/HBox children position correctly without requiring a Screen controller.

func (*Component) AddToScene 

func (c *Component) AddToScene(scene *sg.Scene)

AddToScene adds this component to the scene root node. It also applies any pending layout so components with VBox/HBox children position correctly without requiring a Screen controller.

func (*Component) AnchorOf 

func (c *Component) AnchorOf(child UIElement) (anchor Anchor, offsetX, offsetY float64, ok bool)

AnchorOf returns the anchor metadata for a child. Returns false if the child is not a direct child or has no explicit anchor data (defaults apply).

func (*Component) ApplyBackgroundForTest 

func (c *Component) ApplyBackgroundForTest(bg Background)

ApplyBackgroundForTest calls the internal applyBackground method. Intended for unit tests that need to drive background-switching logic directly.

func (*Component) ApplyBorderForTest 

func (c *Component) ApplyBorderForTest(color sg.Color, width float64, bg Background)

ApplyBorderForTest calls the internal applyBorder method. Intended for unit tests that need to drive border-switching logic directly.

func (*Component) BaseComp 

func (c *Component) BaseComp() *Component

BaseComp returns the embedded Component. Used for testing.

func (*Component) BgContainer 

func (c *Component) BgContainer() *sg.Node

BgContainer returns the component's nine-slice container node, or nil if none has been created yet. Used for testing nine-slice background state.

func (*Component) BgGradientMesh 

func (c *Component) BgGradientMesh() *sg.Node

BgGradientMesh returns the component's gradient mesh node, or nil if none has been created. Used for testing gradient background state.

func (*Component) BgNode 

func (c *Component) BgNode() *sg.Node

BgNode returns the component's background willow node, or nil if none has been initialized. Used for testing visual state.

func (*Component) BgPoly 

func (c *Component) BgPoly() *sg.Node

BgPoly returns the background polygon node (for rounded corners). Used for testing.

func (*Component) BindEnabled 

func (c *Component) BindEnabled(ref *Ref[bool])

BindEnabled binds the component's enabled state to a reactive Ref[bool]. Any previous binding is stopped first.

func (*Component) BindVisible 

func (c *Component) BindVisible(ref *Ref[bool])

BindVisible binds the component's visibility to a reactive Ref[bool]. Any previous binding is stopped first.

func (*Component) BorderBot 

func (c *Component) BorderBot() *sg.Node

BorderBot returns the bottom border node, or nil if not initialized.

func (*Component) BorderLeft 

func (c *Component) BorderLeft() *sg.Node

BorderLeft returns the left border node, or nil if not initialized.

func (*Component) BorderPoly 

func (c *Component) BorderPoly() *sg.Node

BorderPoly returns the border polygon node (for rounded corners). Used for testing.

func (*Component) BorderRight 

func (c *Component) BorderRight() *sg.Node

BorderRight returns the right border node, or nil if not initialized.

func (*Component) BorderTop 

func (c *Component) BorderTop() *sg.Node

BorderTop returns the top border node, or nil if not initialized.

func (*Component) BorderWidth 

func (c *Component) BorderWidth() float64

BorderWidth returns the current border width.

func (*Component) Children 

func (c *Component) Children() []*Component

Children returns a read-only view of the child components.

func (*Component) ClearContextMenu 

func (c *Component) ClearContextMenu()

ClearContextMenu removes any attached context menu from this component.

func (*Component) ClearTooltip 

func (c *Component) ClearTooltip()

ClearTooltip removes any attached tooltip from this component.

func (*Component) Dispose 

func (c *Component) Dispose()

Dispose removes this component from its parent, disposes the underlying willow node, and recursively disposes all children.

func (*Component) EffectiveTheme 

func (c *Component) EffectiveTheme() *Theme

EffectiveTheme returns the theme in effect for this component: its own if set, otherwise the nearest ancestor's, falling back to DefaultTheme if no ancestor has an explicit theme.

func (*Component) FireEvent 

func (c *Component) FireEvent(name string)

FireEvent triggers a named custom event handler previously registered via SetOnEvent or XML template on:* bindings.

func (*Component) GetTooltip 

func (c *Component) GetTooltip() *Tooltip

GetTooltip returns the tooltip attached to this component, or nil if none.

func (*Component) HandleKey 

func (c *Component) HandleKey(key engine.Key) bool

HandleKey delegates to the component's handleKeyFn. Returns false if no handler is set. This is a pure query — it must not perform the action itself; the widget's own Update() handles the actual behavior.

func (*Component) HasBgSliceNodes 

func (c *Component) HasBgSliceNodes() bool

HasBgSliceNodes reports whether the nine-slice sprite nodes have been created. Used for testing nine-slice lazy initialization.

func (*Component) HitShape 

func (c *Component) HitShape() sg.HitShape

HitShape returns the current hit-test shape of the underlying node.

func (*Component) InitBackgroundForTest 

func (c *Component) InitBackgroundForTest(name string)

InitBackgroundForTest calls the internal initBackground method. Intended for unit tests that need to set up a Component background outside of a widget constructor (e.g. to test gradient or nine-slice behaviour in isolation).

func (*Component) InitBorderForTest 

func (c *Component) InitBorderForTest(name string)

InitBorderForTest calls the internal initBorder method. Intended for unit tests that need to set up border nodes outside of a widget constructor.

func (*Component) IsDisposed 

func (c *Component) IsDisposed() bool

IsDisposed reports whether the underlying node has been disposed.

func (*Component) IsDrawDirty 

func (c *Component) IsDrawDirty() bool

IsDrawDirty reports whether the component needs a visual update.

func (*Component) IsEnabled 

func (c *Component) IsEnabled() bool

IsEnabled reports whether the component is enabled.

func (*Component) IsFocused 

func (c *Component) IsFocused() bool

IsFocused reports whether the component currently has focus.

func (*Component) IsHovered 

func (c *Component) IsHovered() bool

IsHovered reports whether the pointer is over this component.

func (*Component) IsInteractable 

func (c *Component) IsInteractable() bool

IsInteractable reports whether the underlying node receives pointer events.

func (*Component) IsLayoutDirty 

func (c *Component) IsLayoutDirty() bool

IsLayoutDirty reports whether the component needs layout recalculation.

func (*Component) IsPressed 

func (c *Component) IsPressed() bool

IsPressed reports whether the component is being pressed.

func (*Component) IsVisible 

func (c *Component) IsVisible() bool

IsVisible reports whether the component is visible.

func (*Component) MarkDrawDirty 

func (c *Component) MarkDrawDirty()

MarkDrawDirty marks this component as needing a visual update.

func (*Component) MarkLayoutDirty 

func (c *Component) MarkLayoutDirty()

MarkLayoutDirty marks this component as needing layout recalculation. Propagates up to the parent.

func (*Component) Name 

func (c *Component) Name() string

Name returns the name of the underlying willow node.

func (*Component) Node 

func (c *Component) Node() *sg.Node

Node returns the underlying willow node. Use Component methods (SetPosition, SetVisible, SetZIndex, etc.) in preference to calling Node() directly. Node() is an escape hatch for low-level willow operations not covered by Component wrappers (e.g. HitShape, Interactable, AddChild, event callbacks).

func (*Component) NumChildren 

func (c *Component) NumChildren() int

NumChildren returns the number of child components.

func (*Component) OnClick 

func (c *Component) OnClick(fn func(sg.ClickContext))

OnClick registers a click callback on the underlying node. If no hit shape has been established yet and the component has dimensions, one is created automatically so the component becomes a pointer target.

func (*Component) Parent 

func (c *Component) Parent() *Component

Parent returns the parent component, or nil if this is a root.

func (*Component) RemoveChild 

func (c *Component) RemoveChild(child UIElement)

RemoveChild detaches a child component from this component.

func (*Component) RemoveRawChild 

func (c *Component) RemoveRawChild(node *sg.Node)

RemoveRawChild removes a raw willow node from this component's node.

func (*Component) ResizeBackgroundForTest 

func (c *Component) ResizeBackgroundForTest(w, h float64)

ResizeBackgroundForTest calls the internal resizeBackground method. Intended for unit tests that need to drive background resize logic directly.

func (*Component) ResizeBorderForTest 

func (c *Component) ResizeBorderForTest(w, h float64)

ResizeBorderForTest calls the internal resizeBorder method. Intended for unit tests that need to drive border resize logic directly.

func (*Component) SetAnchor 

func (c *Component) SetAnchor(child UIElement, anchor Anchor, offsetX, offsetY float64)

SetAnchor changes the anchor and offset for an existing child. Has no effect if child is not a direct child of this component.

func (*Component) SetContextMenu 

func (c *Component) SetContextMenu(cm *ContextMenu)

SetContextMenu attaches a ContextMenu to this component. Right-clicking the component will show the menu at the cursor position.

func (*Component) SetCursorShape 

func (c *Component) SetCursorShape(shape engine.CursorShapeType)

SetCursorShape sets the cursor shape shown when hovering over this component. Use engine.CursorShapeDefault to clear any override.

func (*Component) SetEnabled 

func (c *Component) SetEnabled(v bool)

SetEnabled sets whether the component responds to input.

func (*Component) SetFocused 

func (c *Component) SetFocused(v bool)

SetFocused sets the focus state directly. Prefer using FocusManager.SetFocus for proper focus tracking across the UI.

func (*Component) SetHandleKey 

func (c *Component) SetHandleKey(fn func(engine.Key) bool)

SetHandleKey sets the function called by HandleKey. Widgets with InterceptArrows set this in their constructor.

func (*Component) SetHitShape 

func (c *Component) SetHitShape(s sg.HitShape)

SetHitShape sets the hit-test shape for the underlying node.

func (*Component) SetInteractable 

func (c *Component) SetInteractable(v bool)

SetInteractable sets whether the underlying node receives pointer events. Unlike SetEnabled, this does not affect visual state tracking.

func (*Component) SetOnActivate 

func (c *Component) SetOnActivate(fn func())

SetOnActivate sets the callback invoked when this component is activated (e.g. a Window being brought to front, or a generic click handler via templates).

func (*Component) SetOnEvent 

func (c *Component) SetOnEvent(name string, fn func())

SetOnEvent registers a named event handler for use with XML template on:* bindings. Custom widgets call FireEvent(name) to trigger the handler.

func (*Component) SetOnThemeChangeForTest 

func (c *Component) SetOnThemeChangeForTest(fn func())

SetOnThemeChangeForTest sets the onThemeChange callback. Used for testing.

func (*Component) SetOnTooltipHide 

func (c *Component) SetOnTooltipHide(fn func())

SetOnTooltipHide registers a callback that fires just after the tooltip is hidden.

func (*Component) SetOnTooltipShow 

func (c *Component) SetOnTooltipShow(fn func())

SetOnTooltipShow registers a callback that fires just before the tooltip becomes visible. Use this to update tooltip content dynamically.

func (*Component) SetPosition 

func (c *Component) SetPosition(x, y float64)

SetPosition sets the component position in local parent space. This forwards to the underlying node while keeping layout fields in sync.

func (*Component) SetTheme 

func (c *Component) SetTheme(t *Theme)

SetTheme sets an explicit theme on this component. Pass nil to revert to parent inheritance. Propagates to descendants.

func (*Component) SetTooltip 

func (c *Component) SetTooltip(tt *Tooltip)

SetTooltip attaches a tooltip to this component, replacing any existing one. Pass nil to clear.

func (*Component) SetTooltipText 

func (c *Component) SetTooltipText(text string, source *sg.FontFamily, size float64)

SetTooltipText is a convenience method that creates a single-label tooltip and attaches it to this component.

func (*Component) SetUserData 

func (c *Component) SetUserData(v any)

SetUserData sets the UserData field of the underlying node.

func (*Component) SetVariant 

func (c *Component) SetVariant(v Variant)

SetVariant sets the visual variant for this component.

func (*Component) SetVisible 

func (c *Component) SetVisible(v bool)

SetVisible sets the component's visibility.

func (*Component) SetZIndex 

func (c *Component) SetZIndex(z int)

SetZIndex sets the z-index of the underlying node.

func (*Component) SimulateDirtyDraw 

func (c *Component) SimulateDirtyDraw(v bool)

SimulateDirtyDraw sets the dirtyDraw flag directly. Intended for unit tests that need to reset dirty state before testing MarkDrawDirty.

func (*Component) SimulateHover 

func (c *Component) SimulateHover(v bool)

SimulateHover sets the hovered state directly. Intended for unit tests that need to drive visual-state logic without a running input pipeline.

func (*Component) SimulatePress 

func (c *Component) SimulatePress(v bool)

SimulatePress sets the pressed state directly. Intended for unit tests that need to drive visual-state logic without a running input pipeline.

func (*Component) SizeToContent 

func (c *Component) SizeToContent()

SizeToContent resizes the component to tightly fit its children based on the current layout mode (VBox or HBox). Children should already have their sizes set. After resizing, UpdateLayout is called to reposition children.

func (*Component) State 

func (c *Component) State() ComponentState

State returns the current ComponentState.

func (*Component) UpdateLayout 

func (c *Component) UpdateLayout()

UpdateLayout recalculates position and size of this component and its children, then syncs the results to the underlying willow nodes.

func (*Component) UserData 

func (c *Component) UserData() any

UserData returns the UserData field of the underlying node.

func (*Component) Variant 

func (c *Component) Variant() Variant

Variant returns the current visual variant.

func (*Component) WorldBounds 

func (c *Component) WorldBounds() (x, y, w, h float64)

WorldBounds returns the component's bounding rectangle in world-space coordinates using the underlying node's transform.

func (*Component) WorldCenter 

func (c *Component) WorldCenter() (cx, cy float64)

WorldCenter returns the component's center point in world-space coordinates.

func (*Component) ZIndex 

func (c *Component) ZIndex() int

ZIndex returns the z-index of the underlying node.

type ComponentState 

type ComponentState = core.ComponentState

ComponentState represents the visual state of a component.

type Computed 

type Computed[T comparable] = reactive.Computed[T]

func NewComputed 

func NewComputed[T comparable](fn func() T) *Computed[T]

NewComputed creates a new computed reactive value.

type Config 

type Config[G any] = theme.Config[G]

Config is a generic component config with variant group support.

type ContextMenu 

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

ContextMenu is a list of items that can be shown at an arbitrary position, typically on right-click. Attach it to a Component via SetContextMenu.

func NewContextMenu 

func NewContextMenu(source *sg.FontFamily, displaySize float64) *ContextMenu

NewContextMenu creates a ContextMenu with the given font source and display size.

func (*ContextMenu) Hide 

func (c *ContextMenu) Hide()

Hide closes the context menu if it is currently open.

func (*ContextMenu) SetItems 

func (c *ContextMenu) SetItems(items []MenuItem)

SetItems replaces the item list.

func (*ContextMenu) SetVariant 

func (c *ContextMenu) SetVariant(v Variant)

SetVariant sets the theme variant for the popup.

func (*ContextMenu) ShowAt 

func (c *ContextMenu) ShowAt(x, y float64)

ShowAt opens the menu with its top-left at (x, y) in world/screen coordinates.

type Controller 

type Controller interface {
	// OnCreate is called once when the screen is shown. Build UI here.
	OnCreate(screen *Screen)

	// OnUpdate is called once per frame during the UI update pass.
	OnUpdate(dt float64)

	// OnDestroy is called when the screen is destroyed. Clean up here.
	OnDestroy()
}

Controller is implemented by per-screen state owners that build UI, run per-frame logic, and clean up resources.

type DataTable 

type DataTable struct {
	Component
	// contains filtered or unexported fields
}

DataTable is a virtualized, sortable, filterable data grid widget.

func NewDataTable 

func NewDataTable(name string, rowHeight float64) *DataTable

NewDataTable creates a DataTable with the given name and row height.

func (*DataTable) AddColumn 

func (dt *DataTable) AddColumn(col DataTableColumn)

AddColumn appends a column definition.

func (*DataTable) BindItems 

func (dt *DataTable) BindItems(items *Array[any])

BindItems binds the DataTable to a reactive Array[any]. Mutations to the array are reflected incrementally without full re-renders where possible.

func (*DataTable) BindScrollPos 

func (dt *DataTable) BindScrollPos(ref *Ref[float64])

BindScrollPos binds an external Ref[float64] to the scroll position.

func (*DataTable) BindSearchFilter 

func (dt *DataTable) BindSearchFilter(ref *Ref[string])

BindSearchFilter binds a reactive string ref to the search filter. Columns with Searchable=true and SearchValue set are filtered when the ref changes.

func (*DataTable) BindSearchInput 

func (dt *DataTable) BindSearchInput(ti *TextInput)

BindSearchInput binds a TextInput's reactive value to the search filter.

func (*DataTable) BindSelectedIndexes 

func (dt *DataTable) BindSelectedIndexes(getFn func() []int, setFn func([]int))

BindSelectedIndexes binds selection state to external getter/setter functions. When the DataTable selection changes, setFn is called with the new indexes. When external code changes the selection, call SetSelectedIndexes to push it in.

func (*DataTable) ClearColumnFilter 

func (dt *DataTable) ClearColumnFilter(colKey string)

ClearColumnFilter removes the per-column filter for the given column.

func (*DataTable) ClearSelection 

func (dt *DataTable) ClearSelection()

ClearSelection deselects all rows.

func (*DataTable) DataTableDisplayCount 

func (dt *DataTable) DataTableDisplayCount() int

DataTableDisplayCount returns the number of rows currently displayed (after filter/sort).

func (*DataTable) DataTableDisplayIndexes 

func (dt *DataTable) DataTableDisplayIndexes() []int

DataTableDisplayIndexes returns a copy of the current display index order.

func (*DataTable) DataTableScrollBar 

func (dt *DataTable) DataTableScrollBar() *ScrollBar

DataTableScrollBar returns the internal scrollbar for testing.

func (*DataTable) DataTableScrollPos 

func (dt *DataTable) DataTableScrollPos() *Ref[float64]

DataTableScrollPos returns the reactive scroll position ref for testing.

func (*DataTable) DataTableSelectedIndexes 

func (dt *DataTable) DataTableSelectedIndexes() []int

DataTableSelectedIndexes returns the current selection (data indexes).

func (*DataTable) DeselectRow 

func (dt *DataTable) DeselectRow(index int)

DeselectRow removes the given data index from the selection.

func (*DataTable) Dispose 

func (dt *DataTable) Dispose()

Dispose cleans up watches and child components.

func (*DataTable) IsSelected 

func (dt *DataTable) IsSelected(index int) bool

IsSelected returns whether the given data index is selected.

func (*DataTable) OnColumn 

func (dt *DataTable) OnColumn(key string, col DataTableColumn)

OnColumn merges render/update funcs into an existing column identified by key. Used to attach RenderCell/UpdateCell factories after loading columns from XML.

func (*DataTable) Rebuild 

func (dt *DataTable) Rebuild()

Rebuild marks the layout as dirty, triggering a full re-layout on the next frame. This recreates all row slots from scratch, so it picks up structural changes like column additions, row height changes, or Label style updates. Not needed for normal operations (scrolling, sorting, filtering, selection, binding new data) — those reuse existing slots automatically.

func (*DataTable) Refresh 

func (dt *DataTable) Refresh()

Refresh marks data as dirty, triggering a slot rebuild on the next frame.

func (*DataTable) ResetFiltersAndSort 

func (dt *DataTable) ResetFiltersAndSort()

ResetFiltersAndSort clears all sort keys, filters, search, and column filters, scrolls to top, and rebuilds.

func (*DataTable) ScrollToBottom 

func (dt *DataTable) ScrollToBottom()

ScrollToBottom scrolls to the bottom of the table.

func (*DataTable) ScrollToRow 

func (dt *DataTable) ScrollToRow(index int)

ScrollToRow scrolls so the given original-array index is visible.

func (*DataTable) ScrollToTop 

func (dt *DataTable) ScrollToTop()

ScrollToTop scrolls to the top of the table.

func (*DataTable) SelectAll 

func (dt *DataTable) SelectAll()

SelectAll selects all rows (multi-selection mode only; no-op otherwise).

func (*DataTable) SelectRow 

func (dt *DataTable) SelectRow(index int)

SelectRow selects the row at the given data index.

func (*DataTable) SelectedIndexes 

func (dt *DataTable) SelectedIndexes() []int

SelectedIndexes returns the current selected data indexes (into items slice).

func (*DataTable) SetColumnFilter 

func (dt *DataTable) SetColumnFilter(colKey string, values []string)

SetColumnFilter sets the allowed values for a per-column filter. Only rows whose column SearchValue is in values will be shown.

func (*DataTable) SetColumns 

func (dt *DataTable) SetColumns(cols []DataTableColumn)

SetColumns replaces all columns.

func (*DataTable) SetDefaultSort 

func (dt *DataTable) SetDefaultSort(key string, dir SortDirection)

SetDefaultSort sets the default sort applied when sortKeys is empty (e.g. on BindItems).

func (*DataTable) SetEmptyComponent 

func (dt *DataTable) SetEmptyComponent(comp *Component)

SetEmptyComponent sets a component to display when the table has no visible rows.

func (*DataTable) SetFilterFunc 

func (dt *DataTable) SetFilterFunc(fn func(data any) bool)

SetFilterFunc sets a function to filter visible rows. Pass nil to clear the filter; scroll position is reset to top.

func (*DataTable) SetFont 

func (dt *DataTable) SetFont(source *sg.FontFamily, size float64)

SetFont sets the font source and display size used for header text and default cell labels. Must be called before SetItems/BindItems so cells pick up the font.

func (*DataTable) SetHeaderHeight 

func (dt *DataTable) SetHeaderHeight(h float64)

SetHeaderHeight sets the height of the header row.

func (*DataTable) SetItems 

func (dt *DataTable) SetItems(items []any)

SetItems replaces the data slice and refreshes the display.

func (*DataTable) SetOnCellClick 

func (dt *DataTable) SetOnCellClick(fn func(coord CellCoord, data any))

SetOnCellClick sets the callback for cell click events.

func (*DataTable) SetOnCellDoubleClick 

func (dt *DataTable) SetOnCellDoubleClick(fn func(coord CellCoord, data any))

SetOnCellDoubleClick sets the callback for cell double-click events.

func (*DataTable) SetOnMultiSort 

func (dt *DataTable) SetOnMultiSort(fn func([]SortKey))

SetOnMultiSort sets the callback invoked on multi-sort changes.

func (*DataTable) SetOnSelectionChanged 

func (dt *DataTable) SetOnSelectionChanged(fn func(indexes []int))

SetOnSelectionChanged sets the callback for selection changes.

func (*DataTable) SetOnSort 

func (dt *DataTable) SetOnSort(fn func(key string, dir SortDirection))

SetOnSort sets the callback invoked when the sort column/direction changes. When registered, the DataTable does NOT apply sorting internally — the caller owns sort logic.

func (*DataTable) SetOnSortScroll 

func (dt *DataTable) SetOnSortScroll(v OnSortScroll)

SetOnSortScroll sets the scroll behavior after sorting.

func (*DataTable) SetRowClickSelects 

func (dt *DataTable) SetRowClickSelects(v bool)

SetRowClickSelects enables/disables selection on row click.

func (*DataTable) SetRowHeight 

func (dt *DataTable) SetRowHeight(h float64)

SetRowHeight sets the height of each data row.

func (*DataTable) SetScrollMode 

func (dt *DataTable) SetScrollMode(m ScrollMode)

SetScrollMode switches between virtual and static scroll modes.

func (*DataTable) SetSelectedIndexes 

func (dt *DataTable) SetSelectedIndexes(indexes []int)

SetSelectedIndexes replaces the selection from external code and refreshes visuals.

func (*DataTable) SetSelectionMode 

func (dt *DataTable) SetSelectionMode(m SelectionMode)

SetSelectionMode sets the selection behavior.

func (*DataTable) SetShowColumnDividers 

func (dt *DataTable) SetShowColumnDividers(v bool)

SetShowColumnDividers shows/hides vertical dividers between columns.

func (*DataTable) SetShowHeader 

func (dt *DataTable) SetShowHeader(v bool)

SetShowHeader controls whether the header row is visible.

func (*DataTable) SetShowRowDividers 

func (dt *DataTable) SetShowRowDividers(v bool)

SetShowRowDividers shows/hides horizontal dividers between rows.

func (*DataTable) SetShowScrollBar 

func (dt *DataTable) SetShowScrollBar(v bool)

SetShowScrollBar controls whether the scrollbar is shown.

func (*DataTable) SetSize 

func (dt *DataTable) SetSize(w, h float64)

SetSize sets the widget dimensions and rebuilds internal layout.

func (*DataTable) SetSortKeys 

func (dt *DataTable) SetSortKeys(keys []SortKey)

SetSortKeys replaces the entire sort key stack.

func (*DataTable) SetSortedColumn 

func (dt *DataTable) SetSortedColumn(key string, dir SortDirection)

SetSortedColumn programmatically sets a single sort column and direction. Clears any multi-column sort.

func (*DataTable) SetZebraStriping 

func (dt *DataTable) SetZebraStriping(v bool)

SetZebraStriping enables or disables alternating row backgrounds.

func (*DataTable) SortKeys 

func (dt *DataTable) SortKeys() []SortKey

SortKeys returns the current sort key stack.

func (*DataTable) SortedColumn 

func (dt *DataTable) SortedColumn() (string, SortDirection)

SortedColumn returns the first sort column key and direction. For multi-sort use SortKeys().

func (*DataTable) ToggleRowSelection 

func (dt *DataTable) ToggleRowSelection(index int)

ToggleRowSelection toggles selection of the given data index.

func (*DataTable) Update 

func (dt *DataTable) Update()

Update is called automatically once per frame via node.OnUpdate.

type DataTableColumn 

type DataTableColumn struct {
	Key         string
	Header      string
	Tooltip     string
	Weight      float64 // flex weight (0 means use FixedWidth)
	FixedWidth  float64 // fixed pixel width (0 means use Weight)
	MinWidth    float64 // minimum pixel width for flex columns
	MaxWidth    float64 // maximum pixel width for flex columns
	Sortable    bool
	Filterable  bool // enables per-column filter UI
	SortType    SortType
	SortValue   func(data any) any // override sort key; returns string or number
	Comparator  func(a, b any) int // used when SortType == SortCustom
	Searchable  bool
	SearchValue func(data any) string // used by BindSearchFilter; Searchable must also be true
	RenderCell  func(rowIndex int, data any) *Component
	UpdateCell  func(rowIndex int, data any, comp *Component)
	Cell        CellStyle // styling and post-update hook for data cells
	HeaderStyle CellStyle // styling overrides for the header text
	ClipMode    CellClipMode

	// Hidden returns true when this column should collapse to zero width and
	// not render any content. The function is called during layout resolution,
	// so the result can change dynamically (e.g. bound to a reactive Ref).
	// A nil Hidden func means the column is always visible.
	Hidden func() bool
	// contains filtered or unexported fields
}

DataTableColumn defines a column in a DataTable.

func LabelColumn 

func LabelColumn(key, header string, accessor func(data any) string) DataTableColumn

LabelColumn creates a simple text-label column with the given key, header and accessor.

func MeterColumn 

func MeterColumn(key, header string, accessor func(data any) float64) DataTableColumn

MeterColumn creates a column that renders an inline MeterBar for each row. The accessor returns a float64 in [0, 1]. Use Cell.OnPostUpdate to customize the fill color dynamically.

func SelectionColumn 

func SelectionColumn(key string, visible, multi *Ref[bool]) DataTableColumn

SelectionColumn creates a column that renders a selection indicator (checkbox or radio button) for each row. The column is designed for "batch mode" UX patterns — hide it in normal viewing mode and show it when the user activates batch operations.

Parameters:

  • key: unique column key (used internally and for identification).

  • visible: reactive bool that controls column visibility. When false the column collapses to zero width and its header/cells are hidden. Bind this to a button or toggle to let users enter/exit batch mode.

  • multi: reactive bool that controls the selection widget type. true renders checkboxes (multi-select), false renders radio dots (single-select). Switching at runtime swaps the widget in every visible cell.

The column is non-sortable, non-searchable, and uses a fixed width of 36px. Selection state is owned by the DataTable — this column is purely the visual companion to the table's SelectionMode / SelectedIndexes API.

The DataTable's SelectionMode must match the multi flag for consistent behavior: SelectionModeMulti when multi is true, SelectionModeSingle when false. The column does NOT change SelectionMode automatically.

Example: 

selVisible := ui.NewRef(false)
selMulti   := ui.NewRef(true)

cols := []ui.DataTableColumn{
    ui.SelectionColumn("sel", selVisible, selMulti),
    ui.LabelColumn("name", "Name", func(d any) string { ... }),
}

table := ui.NewDataTable("tbl", 30)
table.SetColumns(cols)
table.SetSelectionMode(ui.SelectionModeMulti)

// Toggle batch mode from a button:
selVisible.Set(true)

type DragAxis 

type DragAxis int

DragAxis specifies which axis a DragHandle operates on. 

const (
	DragAxisX        DragAxis = iota // horizontal drag — resizes width
	DragAxisY                        // vertical drag — resizes height
	DragAxisDiagonal                 // diagonal drag — resizes both
)

type DragGripStyle 

type DragGripStyle int

DragGripStyle specifies the visual indicator rendered on a DragHandle. 

const (
	DragGripDots  DragGripStyle = iota // dot grid
	DragGripLines                      // parallel short lines
	DragGripNone                       // invisible hit target, no visual
)

type DragHandle 

type DragHandle struct {
	Component
	// contains filtered or unexported fields
}

DragHandle is a visible grip primitive that emits drag delta events and can optionally resize a target component directly.

func NewDragHandle 

func NewDragHandle(name string) *DragHandle

NewDragHandle creates a DragHandle with default dot grip style.

func (*DragHandle) Axis 

func (dh *DragHandle) Axis() DragAxis

Axis returns the current drag axis.

func (*DragHandle) ClearTarget 

func (dh *DragHandle) ClearTarget()

ClearTarget removes the resize target, switching to delegate mode.

func (*DragHandle) GripNodes 

func (dh *DragHandle) GripNodes() []*sg.Node

GripNodes returns the grip child nodes. Used for testing.

func (*DragHandle) GripStyle 

func (dh *DragHandle) GripStyle() DragGripStyle

GripStyle returns the current grip style.

func (*DragHandle) Max 

func (dh *DragHandle) Max() float64

Max returns the maximum constraint.

func (*DragHandle) Min 

func (dh *DragHandle) Min() float64

Min returns the minimum constraint.

func (*DragHandle) SetAxis 

func (dh *DragHandle) SetAxis(axis DragAxis)

SetAxis sets the drag axis.

func (*DragHandle) SetEnabled 

func (dh *DragHandle) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*DragHandle) SetGripStyle 

func (dh *DragHandle) SetGripStyle(style DragGripStyle)

SetGripStyle sets the visual grip indicator style.

func (*DragHandle) SetMax 

func (dh *DragHandle) SetMax(v float64)

SetMax sets the maximum constraint for resize mode.

func (*DragHandle) SetMin 

func (dh *DragHandle) SetMin(v float64)

SetMin sets the minimum constraint for resize mode.

func (*DragHandle) SetOnDrag 

func (dh *DragHandle) SetOnDrag(fn func(delta float64))

SetOnDrag sets the callback fired on each drag move with the total delta.

func (*DragHandle) SetOnDragEnd 

func (dh *DragHandle) SetOnDragEnd(fn func(value float64))

SetOnDragEnd sets the callback fired on drag release with the final value.

func (*DragHandle) SetOnDragStart 

func (dh *DragHandle) SetOnDragStart(fn func())

SetOnDragStart sets the callback fired when a drag begins.

func (*DragHandle) SetSize 

func (dh *DragHandle) SetSize(w, h float64)

SetSize sets the handle dimensions (the entire area is the hit target).

func (*DragHandle) SetTarget 

func (dh *DragHandle) SetTarget(comp *Component)

SetTarget sets the component to resize during drag.

func (*DragHandle) Target 

func (dh *DragHandle) Target() *Component

Target returns the current resize target, or nil. Used for testing.

func (*DragHandle) UpdateVisuals 

func (dh *DragHandle) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

type FillMode 

type FillMode int

FillMode controls how a component stretches to fill its parent's content area. 

const (
	FillNone   FillMode = 0
	FillWidth  FillMode = 1
	FillHeight FillMode = 2
	FillBoth   FillMode = FillWidth | FillHeight
)

type FloatProperty 

type FloatProperty = theme.FloatProperty

FloatProperty holds a float64 value for each component state.

type FocusManager 

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

FocusManager tracks which component has keyboard focus. Owns UI keyboard dispatch: widget interception, scoped and global hotkeys/keybinds, Tab cycling, and spatial navigation.

func NewFocusManager 

func NewFocusManager() *FocusManager

NewFocusManager creates an empty focus manager wired to the DefaultInputManager.

func (*FocusManager) Bind 

func (fm *FocusManager) Bind(combo KeyCombo, fn func() bool) BindHandle

Bind registers a global keybind that fires regardless of focus. The callback returns true to consume the key from InputManager, false to let it pass through. Returns a handle for later removal via Unbind.

func (*FocusManager) BindScoped 

func (fm *FocusManager) BindScoped(comp *Component, combo KeyCombo, fn func() bool)

BindScoped registers a keybind that fires only when comp (or a descendant) is focused. Automatically removed when the component is unregistered or disposed.

func (*FocusManager) ClearFocus 

func (fm *FocusManager) ClearFocus()

ClearFocus removes focus from the currently focused component.

func (*FocusManager) Focused 

func (fm *FocusManager) Focused() *Component

Focused returns the currently focused component, or nil.

func (*FocusManager) Register 

func (fm *FocusManager) Register(c *Component)

Register adds a component to the tab order. Duplicates are ignored.

func (*FocusManager) SetFocus 

func (fm *FocusManager) SetFocus(c *Component)

SetFocus gives focus to c, removing it from the previously focused component. Passing nil clears focus.

func (*FocusManager) TabNext 

func (fm *FocusManager) TabNext()

TabNext moves focus to the next component in tab order that has AllowTab, wrapping around. If nothing is focused, focuses the first eligible.

func (*FocusManager) TabPrev 

func (fm *FocusManager) TabPrev()

TabPrev moves focus to the previous component in tab order that has AllowTab, wrapping around. If nothing is focused, focuses the last eligible.

func (*FocusManager) Unbind 

func (fm *FocusManager) Unbind(handle BindHandle)

Unbind removes a global keybind by handle.

func (*FocusManager) Unregister 

func (fm *FocusManager) Unregister(c *Component)

Unregister removes a component from the tab order and cleans up any scoped keybinds. If it was focused, focus is cleared.

func (*FocusManager) Update 

func (fm *FocusManager) Update()

Update processes one frame of keyboard dispatch. Called once per frame by Screen.Update(). Must not be called by widgets directly.

Dispatch order:

  1. Click-outside detection (clear focus on click outside any focusable)
  2. Focused widget interception (InterceptArrows → HandleKey for arrow keys)
  3. Scoped hotkeys (focused component match)
  4. Global hotkeys
  5. Focus navigation (Tab/Shift+Tab, unhandled arrow keys → spatial nav)

type Gradient 

type Gradient = render.Gradient

Gradient is the value type for GradientEditor.

type GradientColors 

type GradientColors = render.GradientColors

GradientColors defines per-corner colors for gradient backgrounds.

type GradientEditor 

type GradientEditor struct {
	Component
	// contains filtered or unexported fields
}

GradientEditor edits horizontal, vertical, or 4-corner gradients.

func NewGradientEditor 

func NewGradientEditor(name string, source *sg.FontFamily, displaySize float64) *GradientEditor

NewGradientEditor creates a GradientEditor with the given name, font source, and display size.

func (*GradientEditor) BindValue 

func (ge *GradientEditor) BindValue(ref *Ref[render.Gradient])

BindValue binds a *Ref[Gradient] so the editor writes back on every change.

func (*GradientEditor) SetAllowedModes 

func (ge *GradientEditor) SetAllowedModes(modes ...render.GradientMode)

SetAllowedModes restricts which modes appear in the mode selector. If the current mode is not in the list, the widget switches to the first allowed mode.

func (*GradientEditor) SetOnChange 

func (ge *GradientEditor) SetOnChange(fn func(render.Gradient))

SetOnChange sets a callback invoked on every edit (color change or mode switch).

func (*GradientEditor) SetShowModeSelector 

func (ge *GradientEditor) SetShowModeSelector(show bool)

SetShowModeSelector shows or hides the H | V | 4-corner tab row.

func (*GradientEditor) SetSize 

func (ge *GradientEditor) SetSize(w, h float64)

SetSize sets the widget dimensions and re-layouts children.

func (*GradientEditor) SetValue 

func (ge *GradientEditor) SetValue(g render.Gradient)

SetValue sets the current gradient without firing OnChange.

func (*GradientEditor) UpdateVisuals 

func (ge *GradientEditor) UpdateVisuals()

UpdateVisuals updates the visual appearance from the theme.

func (*GradientEditor) Value 

func (ge *GradientEditor) Value() render.Gradient

Value returns the current gradient.

type GradientMode 

type GradientMode = render.GradientMode

GradientMode and Gradient are re-exported from render for widget-layer use.

type IconButton 

type IconButton struct {
	Component
	// contains filtered or unexported fields
}

IconButton is an icon-first button that renders a sprite as its primary content, with an optional text label beneath or beside it. It participates in the same focus, hover, pressed, and disabled state system as Button.

func NewIconButton 

func NewIconButton(name string) *IconButton

NewIconButton creates an icon-only button. The icon is initially blank; call SetIconImage or SetIconKey to provide an icon source.

func NewTreeToggle 

func NewTreeToggle(name string, tl *TreeList, node *TreeNode) *IconButton

NewTreeToggle creates a ready-to-use IconButton for expanding/collapsing the given TreeNode within a TreeList. Returns nil for leaf nodes (no children). The button uses the Custom1 variant and tints the glyph icon with hover/active colors from the theme, following the same pattern as the window close button.

func (*IconButton) BindActive 

func (ib *IconButton) BindActive(ref *Ref[bool])

BindActive binds the button's active state to an external Ref[bool]. The button's active highlight reflects the ref value; clicking the button does NOT automatically toggle the ref — that is the caller's responsibility.

func (*IconButton) Dispose 

func (ib *IconButton) Dispose()

Dispose cleans up the button and its resources.

func (*IconButton) IconNode 

func (ib *IconButton) IconNode() *sg.Node

IconNode returns the button's icon willow node.

func (*IconButton) IsActive 

func (ib *IconButton) IsActive() bool

IsActive reports whether the button is in the active/toggled-on state.

func (*IconButton) SetActive 

func (ib *IconButton) SetActive(v bool)

SetActive sets the toggle-style active highlight on this button.

func (*IconButton) SetEnabled 

func (ib *IconButton) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*IconButton) SetIconImage 

func (ib *IconButton) SetIconImage(img engine.Image)

SetIconImage sets the icon from a direct engine.Image override.

func (*IconButton) SetIconKey 

func (ib *IconButton) SetIconKey(key string)

SetIconKey sets the icon using a sprite key from the theme's sprites map. If the key is found in the effective theme, the resolved sprite image is applied; otherwise the icon is cleared to the white pixel fallback.

func (*IconButton) SetIconSize 

func (ib *IconButton) SetIconSize(w, h float64)

SetIconSize overrides the icon display dimensions. Pass 0,0 to restore the size from the theme (IconSize field, square by default).

func (*IconButton) SetLabel 

func (ib *IconButton) SetLabel(text string, source *sg.FontFamily, size float64)

SetLabel attaches an optional text label to the button.

func (*IconButton) SetLabelPosition 

func (ib *IconButton) SetLabelPosition(pos IconLabelPosition)

SetLabelPosition sets whether the label appears below or to the right of the icon. Defaults to IconLabelBelow.

func (*IconButton) SetOnClick 

func (ib *IconButton) SetOnClick(fn func())

SetOnClick sets the callback invoked when the button is clicked.

func (*IconButton) SetSize 

func (ib *IconButton) SetSize(w, h float64)

SetSize sets the button dimensions.

func (*IconButton) SimulateOnClick 

func (ib *IconButton) SimulateOnClick()

SimulateOnClick invokes the onClick callback directly if one is set. Intended for unit tests.

func (*IconButton) UpdateVisuals 

func (ib *IconButton) UpdateVisuals()

UpdateVisuals applies theme colors based on the current interaction state.

type IconLabelPosition 

type IconLabelPosition int

IconLabelPosition controls where the text label appears relative to the icon. 

const (
	// IconLabelBelow places the label beneath the icon (default).
	IconLabelBelow IconLabelPosition = iota
	// IconLabelRight places the label to the right of the icon.
	IconLabelRight
)

type Image 

type Image struct {
	Component
	// contains filtered or unexported fields
}

Image is a display-only component that renders a sprite, texture region, or engine.Image with configurable fit/fill modes, tinting, and optional corner radius.

For Fill and Center modes the image is positioned so overflow extends outside the widget bounds. Clipping at the widget edge is achieved automatically when the Image is placed inside a container that uses cache or mask — bare usage renders without pixel-level clip.

func NewImage 

func NewImage(name string) *Image

NewImage creates an Image widget with no source set.

func (*Image) ClearImage 

func (im *Image) ClearImage()

ClearImage removes the current image source, leaving the widget empty.

func (*Image) ImgNode 

func (im *Image) ImgNode() *sg.Node

ImgNode returns the internal image sprite node. Used for testing.

func (*Image) ImgPosition 

func (im *Image) ImgPosition() (x, y float64)

ImgPosition returns the pixel-space x/y position applied to the image sprite. Used for testing layout calculations.

func (*Image) ImgSize 

func (im *Image) ImgSize() (w, h float64)

ImgSize returns the pixel-space width and height applied to the image sprite. Used for testing layout calculations.

func (*Image) ScaleMode 

func (im *Image) ScaleMode() ImageScaleMode

ScaleMode returns the current scale mode.

func (*Image) SetAlpha 

func (im *Image) SetAlpha(a float32)

SetAlpha sets the alpha of the tint (convenience wrapper).

func (*Image) SetCornerRadius 

func (im *Image) SetCornerRadius(r float64)

SetCornerRadius sets the corner rounding. -1 means full pill (half the shorter dimension). 0 means sharp corners.

func (*Image) SetImage 

func (im *Image) SetImage(img engine.Image)

SetImage sets the image source to a raw engine.Image. Clears any previously set TextureRegion.

func (*Image) SetRegion 

func (im *Image) SetRegion(region sg.TextureRegion)

SetRegion sets the image source to a TextureRegion (atlas sprite). Clears any previously set engine.Image.

func (*Image) SetScaleMode 

func (im *Image) SetScaleMode(mode ImageScaleMode)

SetScaleMode sets how the image is scaled within the widget bounds.

func (*Image) SetSize 

func (im *Image) SetSize(w, h float64)

SetSize sets the widget dimensions.

func (*Image) SetTint 

func (im *Image) SetTint(c sg.Color)

SetTint sets the color multiplied over the image.

func (*Image) SizeToContent 

func (im *Image) SizeToContent()

SizeToContent resizes the widget to the image's native pixel dimensions. Has no effect if no image is set.

func (*Image) Tint 

func (im *Image) Tint() sg.Color

Tint returns the current tint color.

func (*Image) UpdateVisuals 

func (im *Image) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

type ImageCropper 

type ImageCropper struct {
	Component
	// contains filtered or unexported fields
}

ImageCropper displays an image with a draggable crop rectangle. Users can drag corner and edge handles to resize the crop region, or drag inside the crop rect to move it. The widget returns crop coordinates in image-pixel space via CropRect().

func NewImageCropper 

func NewImageCropper(name string) *ImageCropper

NewImageCropper creates an ImageCropper widget.

func (*ImageCropper) CropRect 

func (c *ImageCropper) CropRect() image.Rectangle

CropRect returns the current crop rectangle in image-pixel coordinates.

func (*ImageCropper) Dispose 

func (c *ImageCropper) Dispose()

Dispose releases resources.

func (*ImageCropper) SetAspectRatio 

func (c *ImageCropper) SetAspectRatio(w, h float64)

SetAspectRatio constrains the crop to a fixed aspect ratio. Pass 0, 0 for free.

func (*ImageCropper) SetCropRect 

func (c *ImageCropper) SetCropRect(x, y, w, h float64)

SetCropRect sets the crop rectangle in image-pixel coordinates.

func (*ImageCropper) SetImage 

func (c *ImageCropper) SetImage(img engine.Image)

SetImage sets the source image.

func (*ImageCropper) SetMaxSize 

func (c *ImageCropper) SetMaxSize(w, h float64)

SetMaxSize sets the maximum crop size in image pixels.

func (*ImageCropper) SetMinSize 

func (c *ImageCropper) SetMinSize(w, h float64)

SetMinSize sets the minimum crop size in image pixels.

func (*ImageCropper) SetOnCropChanged 

func (c *ImageCropper) SetOnCropChanged(fn func(rect image.Rectangle))

SetOnCropChanged sets the callback fired during handle drags.

func (*ImageCropper) SetShowGrid 

func (c *ImageCropper) SetShowGrid(v bool)

SetShowGrid enables/disables the rule-of-thirds grid overlay.

func (*ImageCropper) SetSize 

func (c *ImageCropper) SetSize(w, h float64)

SetSize sets the widget dimensions.

func (*ImageCropper) UpdateVisuals 

func (c *ImageCropper) UpdateVisuals()

UpdateVisuals applies theme colors.

type ImageScaleMode 

type ImageScaleMode int

ImageScaleMode controls how the image is laid out within the widget bounds. 

const (
	ImageScaleStretch ImageScaleMode = iota // fill bounds exactly, ignoring aspect ratio
	ImageScaleFit                           // scale uniformly to fit inside bounds (letterbox)
	ImageScaleFill                          // scale uniformly to fill bounds (crop overflow)
	ImageScaleCenter                        // native pixel size, centered, no scaling
	ImageScaleTile                          // tile at native size to fill bounds
)

type InputField 

type InputField struct {
	Component
	// contains filtered or unexported fields
}

InputField is a labeled text input widget that combines a Label, a TextInput, and an optional validation message into a single composable unit.

func NewInputField 

func NewInputField(name string, source *sg.FontFamily, displaySize float64) *InputField

NewInputField creates a new InputField with a label, text input, and validation message.

func (*InputField) BindValue 

func (f *InputField) BindValue(ref *Ref[string])

BindValue binds the input to a reactive Ref[string].

func (*InputField) ClearValidation 

func (f *InputField) ClearValidation()

ClearValidation resets validation state and hides the message.

func (*InputField) Dispose 

func (f *InputField) Dispose()

Dispose cleans up the input field and its children.

func (*InputField) Input 

func (f *InputField) Input() *TextInput

Input returns the inner TextInput for advanced configuration.

func (*InputField) SetEnabled 

func (f *InputField) SetEnabled(v bool)

SetEnabled enables or disables the entire field.

func (*InputField) SetLabel 

func (f *InputField) SetLabel(text string)

SetLabel sets the field label text.

func (*InputField) SetLabelPosition 

func (f *InputField) SetLabelPosition(pos LabelPosition)

SetLabelPosition sets whether the label is above or to the left of the input.

func (*InputField) SetMaxLength 

func (f *InputField) SetMaxLength(n int)

SetMaxLength limits the number of characters.

func (*InputField) SetOnBlur 

func (f *InputField) SetOnBlur(fn func())

SetOnBlur sets the callback fired when the input loses focus.

func (*InputField) SetOnChange 

func (f *InputField) SetOnChange(fn func(string))

SetOnChange sets the callback fired when text changes.

func (*InputField) SetOnSubmit 

func (f *InputField) SetOnSubmit(fn func(string))

SetOnSubmit sets the callback fired on Enter.

func (*InputField) SetPlaceholder 

func (f *InputField) SetPlaceholder(v string)

SetPlaceholder sets the placeholder text.

func (*InputField) SetReadOnly 

func (f *InputField) SetReadOnly(v bool)

SetReadOnly sets the input to read-only mode.

func (*InputField) SetRequired 

func (f *InputField) SetRequired(v bool)

SetRequired marks the field as required and appends the required marker.

func (*InputField) SetRequiredMarker 

func (f *InputField) SetRequiredMarker(s string)

SetRequiredMarker sets the character(s) appended to the label when required. Default "*".

func (*InputField) SetSize 

func (f *InputField) SetSize(w, h float64)

SetSize sets the input width and height. The label and message auto-size.

func (*InputField) SetValidationMessage 

func (f *InputField) SetValidationMessage(msg string)

SetValidationMessage sets the validation message text.

func (*InputField) SetValidationState 

func (f *InputField) SetValidationState(state ValidationState)

SetValidationState sets the validation state and updates the input border color.

func (*InputField) SetValue 

func (f *InputField) SetValue(v string)

SetValue sets the text content.

func (*InputField) SetWidth 

func (f *InputField) SetWidth(w float64)

SetWidth sets only the width; height is computed from font size.

func (*InputField) Value 

func (f *InputField) Value() string

Value returns the current text.

type InputFieldGroup 

type InputFieldGroup = theme.InputFieldGroup

type InputManager 

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

InputManager reads all keyboard state from ebiten once per frame, tracks which keys have been consumed by UI, and exposes availability queries and event-style listeners for game logic.

func NewInputManager 

func NewInputManager() *InputManager

NewInputManager creates a new InputManager with empty state.

func (*InputManager) Consume 

func (im *InputManager) Consume(key engine.Key)

Consume marks a key as claimed by UI for this frame. Subsequent calls to IsKeyAvailable / IsKeyJustAvailable for this key will return false.

func (*InputManager) FireListeners 

func (im *InputManager) FireListeners()

FireListeners fires registered passthrough listeners for keys that were not consumed this frame. Must be called after FocusManager.Update() completes.

func (*InputManager) IsKeyAvailable 

func (im *InputManager) IsKeyAvailable(key engine.Key) bool

IsKeyAvailable returns true if the key is currently held AND was not consumed by UI this frame.

func (*InputManager) IsKeyJustAvailable 

func (im *InputManager) IsKeyJustAvailable(key engine.Key) bool

IsKeyJustAvailable returns true if the key was just pressed this frame AND was not consumed by UI. Uses the injection-aware wrapper so synthetically injected keys are included.

func (*InputManager) IsKeyJustReleased 

func (im *InputManager) IsKeyJustReleased(key engine.Key) bool

IsKeyJustReleased returns true if the key was just released this frame. Release detection is not affected by consumption — it reflects raw state.

func (*InputManager) OnKeyDown 

func (im *InputManager) OnKeyDown(key engine.Key, fn func()) ListenerHandle

OnKeyDown registers a callback that fires once on the frame a key is first pressed and not consumed by UI. Returns a handle for later removal.

func (*InputManager) OnKeyHeld 

func (im *InputManager) OnKeyHeld(key engine.Key, fn func()) ListenerHandle

OnKeyHeld registers a callback that fires every frame a key is held and not consumed by UI. Returns a handle for later removal.

func (*InputManager) OnKeyUp 

func (im *InputManager) OnKeyUp(key engine.Key, fn func()) ListenerHandle

OnKeyUp registers a callback that fires once on the frame a key is released, but only if the key was available (not consumed) when it was first pressed. This prevents phantom release events for keys entirely consumed by UI. Returns a handle for later removal.

func (*InputManager) RemoveListener 

func (im *InputManager) RemoveListener(handle ListenerHandle)

RemoveListener removes a previously registered listener by handle.

func (*InputManager) Update 

func (im *InputManager) Update()

Update reads all ebiten keyboard state for the current frame. Must be called once per frame before FocusManager.Update().

type Insets 

type Insets = render.Insets

Insets represents spacing on four sides (top, right, bottom, left). It is an alias for render.Insets.

type KeyBinding 

type KeyBinding struct {
	Key           engine.Key
	GamepadButton engine.GamepadButton
	IsGamepad     bool
	IsUnset       bool // true when no binding is assigned

	// Modifier keys for combo bindings.
	Ctrl  bool
	Shift bool
	Alt   bool
}

KeyBinding represents a keyboard or gamepad binding.

func (KeyBinding) DisplayName 

func (b KeyBinding) DisplayName() string

DisplayName returns a human-readable string for the binding (e.g. "SPACE", "Ctrl+A", "GP:0").

type KeyCombo 

type KeyCombo struct {
	Key  engine.Key
	Mods ModifierMask
}

KeyCombo pairs an ebiten key with a modifier mask.

func Key 

func Key(k engine.Key, mods ModifierMask) KeyCombo

Key creates a KeyCombo from a key and modifier mask.

type KeybindInput 

type KeybindInput struct {
	Component
	// contains filtered or unexported fields
}

KeybindInput is a settings control that captures a keyboard or gamepad binding. It displays the current binding as a styled key cap label and enters listening mode on click to capture a new binding.

func NewKeybindInput 

func NewKeybindInput(name string, source *sg.FontFamily, displaySize float64) *KeybindInput

NewKeybindInput creates a KeybindInput with the given name, font source, and display size.

func (*KeybindInput) BindValue 

func (k *KeybindInput) BindValue(ref *Ref[KeyBinding])

BindValue binds the current key binding to a reactive Ref. Changes to the Ref update the widget, and user captures update the Ref.

func (*KeybindInput) Binding 

func (k *KeybindInput) Binding() KeyBinding

Binding returns the current key binding.

func (*KeybindInput) ClearBinding 

func (k *KeybindInput) ClearBinding()

ClearBinding unsets the current binding.

func (*KeybindInput) CombosEnabled 

func (k *KeybindInput) CombosEnabled() bool

CombosEnabled returns whether modifier+key combos are supported.

func (*KeybindInput) Dispose 

func (k *KeybindInput) Dispose()

Dispose cleans up the widget.

func (*KeybindInput) IsListening 

func (k *KeybindInput) IsListening() bool

IsListening returns true if the widget is in listening mode.

func (*KeybindInput) SetBinding 

func (k *KeybindInput) SetBinding(binding KeyBinding)

SetBinding sets the binding programmatically without entering listening mode.

func (*KeybindInput) SetCombosEnabled 

func (k *KeybindInput) SetCombosEnabled(v bool)

SetCombosEnabled sets whether modifier+key combos are supported. Enabled by default. Disable for games that only need single-key bindings.

func (*KeybindInput) SetEnabled 

func (k *KeybindInput) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to update visuals.

func (*KeybindInput) SetListening 

func (k *KeybindInput) SetListening(v bool)

SetListening enters or exits listening mode.

func (*KeybindInput) SetOnBindingChanged 

func (k *KeybindInput) SetOnBindingChanged(fn func(binding KeyBinding))

SetOnBindingChanged sets the callback invoked after a new binding is captured.

func (*KeybindInput) SetOnConflict 

func (k *KeybindInput) SetOnConflict(fn func(existing KeyBinding) bool)

SetOnConflict sets the conflict check callback. Return false to reject a binding.

func (*KeybindInput) SetSize 

func (k *KeybindInput) SetSize(w, h float64)

SetSize sets the widget dimensions and repositions children.

func (*KeybindInput) UpdateVisuals 

func (k *KeybindInput) UpdateVisuals()

UpdateVisuals applies theme colors and repositions child nodes.

type Label 

type Label struct {
	Component
	// contains filtered or unexported fields
}

Label is a text display component. It wraps a willow text node and supports reactive text binding via BindText.

func EllipsisLabel 

func EllipsisLabel(name, text string) *Label

EllipsisLabel creates a Label for use in cell rendering. The label uses nil font which falls back to the default font. Returns both the label and its component.

func NewLabel 

func NewLabel(name string, text string, source *sg.FontFamily, displaySize float64) *Label

NewLabel creates a Label with the given name, initial text, font source, and display size. If displaySize is 0, the native atlas size is used.

func (*Label) BindText 

func (l *Label) BindText(ref *Ref[string])

BindText binds the label to a reactive Ref[string]. The label text updates automatically whenever the ref changes. Any previous binding is stopped first. The label is immediately set to the ref's current value.

func (*Label) Dispose 

func (l *Label) Dispose()

Dispose stops any reactive watch and disposes the underlying component.

func (*Label) Font 

func (l *Label) Font() *sg.FontFamily

Font returns the current resolved font.

func (*Label) SetAlign 

func (l *Label) SetAlign(a sg.TextAlign)

SetAlign sets the text alignment.

func (*Label) SetBold 

func (l *Label) SetBold(bold bool)

SetBold sets bold rendering and updates the TextBlock style.

func (*Label) SetColor 

func (l *Label) SetColor(c sg.Color)

SetColor sets the text color.

func (*Label) SetFont 

func (l *Label) SetFont(source *sg.FontFamily)

SetFont replaces the font source used for rendering and measurement.

func (*Label) SetFontSize 

func (l *Label) SetFontSize(size float64)

SetFontSize sets the display size and re-measures.

func (*Label) SetItalic 

func (l *Label) SetItalic(italic bool)

SetItalic sets italic rendering and updates the TextBlock style.

func (*Label) SetSharpness 

func (l *Label) SetSharpness(s float64)

SetSharpness tightens the SDF edge rendering. 0.0 = default, 1.0 = sharpest. Values around 0.5–0.7 give crisp edges without aliasing on most displays.

func (*Label) SetText 

func (l *Label) SetText(t string)

SetText updates the displayed text and re-measures the label dimensions.

func (*Label) SetWrapWidth 

func (l *Label) SetWrapWidth(w float64)

SetWrapWidth sets the maximum line width for word wrapping. Zero means no wrapping.

func (*Label) Text 

func (l *Label) Text() string

Text returns the current text content.

func (*Label) TextNode 

func (l *Label) TextNode() *sg.Node

TextNode returns the underlying willow text node. Used for testing.

type LabelPosition 

type LabelPosition int

LabelPosition controls where the field label is placed relative to the input. 

const (
	LabelAbove LabelPosition = iota // default: label above the input
	LabelLeft                       // label to the left of the input
)

type LabelStyle 

type LabelStyle = CellStyle

LabelStyle is a deprecated alias for CellStyle.

type LayoutLineForTest 

type LayoutLineForTest struct {
	Fragments []LineFragmentForTest
	Height    float64
}

LayoutLineForTest is a public view of a layoutLine for testing.

type LayoutMode 

type LayoutMode = core.LayoutMode

LayoutMode controls how a Component arranges its children.

type LineFragmentForTest 

type LineFragmentForTest struct {
	SizeOverride float64
	Underline    bool
	LinkURL      string
}

LineFragmentForTest is a public view of a lineFragment for testing.

type List 

type List struct {
	Component

	// ItemAlign controls horizontal alignment of each rendered item within
	// its cell. Default is AlignStart (left-aligned).
	ItemAlign Alignment
	// ItemVAlign controls vertical alignment of each rendered item within
	// its cell. Default is AlignCenter.
	ItemVAlign Alignment
	// contains filtered or unexported fields
}

List is a virtualized vertical scrollable list. Only items visible in the viewport are rendered, and components are recycled as the user scrolls.

func NewList 

func NewList(name string, itemHeight float64) *List

NewList creates a new virtualized list with fixed item height.

func (*List) BindItems 

func (l *List) BindItems(arr *Array[ListItem])

BindItems binds the list to a reactive Array[ListItem]. Any mutation to the array (Push, Remove, Sort, etc.) is automatically reflected in the list without resetting the scroll position.

Pass nil to detach the current binding.

func (*List) BindSelected 

func (l *List) BindSelected(ref *Ref[int])

BindSelected binds the selection to a reactive Ref[int].

func (*List) ClearSelection 

func (l *List) ClearSelection()

ClearSelection deselects the current item.

func (*List) Dispose 

func (l *List) Dispose()

Dispose cleans up watches and child components.

func (*List) ItemCount 

func (l *List) ItemCount() int

ItemCount returns the number of items in the list.

func (*List) Items 

func (l *List) Items() []ListItem

Items returns the current list items.

func (*List) ListScrollBar 

func (l *List) ListScrollBar() *ScrollBar

ListScrollBar returns the internal scrollbar. Used for testing.

func (*List) ListScrollPos 

func (l *List) ListScrollPos() *Ref[float64]

ListScrollPos returns the reactive scroll position ref. Used for testing.

func (*List) ListSelHighlight 

func (l *List) ListSelHighlight() *sg.Node

ListSelHighlight returns the selection highlight node, or nil if not created. Used for testing.

func (*List) PoolSize 

func (l *List) PoolSize() int

PoolSize returns the number of active (non-nil) components in the pool. This is useful for verifying virtualization in tests.

func (*List) ScrollToIndex 

func (l *List) ScrollToIndex(idx int)

ScrollToIndex scrolls so that the given item index is visible.

func (*List) ScrollToSelection 

func (l *List) ScrollToSelection()

ScrollToSelection scrolls so that the currently selected item is visible.

func (*List) SelectFirst 

func (l *List) SelectFirst()

SelectFirst selects the first item and scrolls to it.

func (*List) SelectLast 

func (l *List) SelectLast()

SelectLast selects the last item and scrolls to it.

func (*List) SelectNext 

func (l *List) SelectNext()

SelectNext moves the selection to the next item. If nothing is selected, selects the first item. Scrolls to keep the selection visible.

func (*List) SelectPrevious 

func (l *List) SelectPrevious()

SelectPrevious moves the selection to the previous item. If nothing is selected, selects the last item. Scrolls to keep the selection visible.

func (*List) Selectable 

func (l *List) Selectable() bool

Selectable returns whether built-in selection highlighting is enabled.

func (*List) Selected 

func (l *List) Selected() int

Selected returns the currently selected item index, or -1 if none.

func (*List) SelectedItem 

func (l *List) SelectedItem() any

SelectedItem returns the data of the currently selected item, or nil if no item is selected.

func (*List) SelectedRef 

func (l *List) SelectedRef() *Ref[int]

SelectedRef returns the reactive Ref backing the selection index. Use this to subscribe to selection changes via WatchValue or bind to other reactive state.

func (*List) SetItems 

func (l *List) SetItems(items []ListItem)

SetItems replaces the list data and refreshes the visible items.

func (*List) SetOnChange 

func (l *List) SetOnChange(fn func(int))

SetOnChange sets the callback for selection changes.

func (*List) SetRenderItem 

func (l *List) SetRenderItem(fn func(int, any) *Component)

SetRenderItem sets the factory function that creates a Component for a given item index and data value.

func (*List) SetSelectable 

func (l *List) SetSelectable(enabled bool)

SetSelectable enables or disables built-in selection highlighting. When enabled, the list renders a background highlight behind the selected item.

func (*List) SetSelected 

func (l *List) SetSelected(idx int)

SetSelected sets the selected item index.

func (*List) SetSize 

func (l *List) SetSize(w, h float64)

SetSize sets the list dimensions and updates internal layout.

func (*List) Update 

func (l *List) Update()

Update processes mouse wheel input and keyboard navigation for scrolling. This is called automatically via the willow node's OnUpdate hook; no manual call needed.

type ListItem 

type ListItem struct {
	Data any
}

ListItem wraps arbitrary data for use in a List.

type ListenerHandle 

type ListenerHandle uint64

ListenerHandle identifies a registered key listener for later removal.

type MaskedInput 

type MaskedInput struct {
	Component

	// AutoHeight, when true, causes SetSize to ignore the height argument
	// and instead compute it automatically from the font size and theme padding.
	AutoHeight bool
	// contains filtered or unexported fields
}

MaskedInput is a single-line text entry field constrained by a mask pattern. The mask describes editable slot positions and literal separator characters. Supported slot characters: '9' (digit), 'a' (letter), 'A' (upper letter), 'X' (upper alphanumeric), '*' (any visible ASCII). All other characters are treated as literals.

Each mask position is rendered as its own glyph node. Clicking a filled slot positions the cursor there; clicking an empty slot or any non-slot area snaps the cursor to the first empty slot. Typing a valid character fills the current slot and automatically advances to the next slot.

func NewMaskedInput 

func NewMaskedInput(name string, source *sg.FontFamily, displaySize float64) *MaskedInput

NewMaskedInput creates a single-line masked input with the given font source and display size.

func (*MaskedInput) BindRawValue 

func (mi *MaskedInput) BindRawValue(ref *Ref[string])

BindRawValue binds the raw value (no literals) to an external Ref[string].

func (*MaskedInput) BindValue 

func (mi *MaskedInput) BindValue(ref *Ref[string])

BindValue binds the formatted value to an external Ref[string]. The ref is updated whenever the field value changes, and the field is updated whenever the ref changes externally.

func (*MaskedInput) CellCount 

func (mi *MaskedInput) CellCount() int

CellCount returns the number of rendered cells (one per mask token). Used for testing.

func (*MaskedInput) CellNodeForSlot 

func (mi *MaskedInput) CellNodeForSlot(slotIdx int) *sg.Node

CellNodeForSlot returns the glyph node for the given slot index. Used for testing.

func (*MaskedInput) Clear 

func (mi *MaskedInput) Clear()

Clear clears all slot values and resets the cursor to the start.

func (*MaskedInput) DeleteBack 

func (mi *MaskedInput) DeleteBack()

DeleteBack handles backspace: clears the previous slot and moves cursor back.

func (*MaskedInput) DeleteForward 

func (mi *MaskedInput) DeleteForward()

DeleteForward handles delete: clears the current slot without moving cursor.

func (*MaskedInput) Dispose 

func (mi *MaskedInput) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*MaskedInput) GetCursorPos 

func (mi *MaskedInput) GetCursorPos() int

GetCursorPos returns the current raw-slot cursor position. Used for testing.

func (*MaskedInput) GetSelEnd 

func (mi *MaskedInput) GetSelEnd() int

GetSelEnd returns the selection end raw-slot index. Used for testing.

func (*MaskedInput) GetSelStart 

func (mi *MaskedInput) GetSelStart() int

GetSelStart returns the selection start raw-slot index. Used for testing.

func (*MaskedInput) HasSelection 

func (mi *MaskedInput) HasSelection() bool

HasSelection reports whether any slots are selected.

func (*MaskedInput) InsertText 

func (mi *MaskedInput) InsertText(s string)

InsertText distributes pasted characters into slots starting at cursorPos. Invalid characters are skipped; literal separators in the pasted string that match the mask are also skipped.

func (*MaskedInput) IsComplete 

func (mi *MaskedInput) IsComplete() bool

IsComplete reports whether all editable slots are filled.

func (*MaskedInput) IsEmpty 

func (mi *MaskedInput) IsEmpty() bool

IsEmpty reports whether no editable slot has a value.

func (*MaskedInput) Mask 

func (mi *MaskedInput) Mask() string

Mask returns the current mask pattern string.

func (*MaskedInput) MaskPlaceholder 

func (mi *MaskedInput) MaskPlaceholder() rune

MaskPlaceholder returns the current mask placeholder character.

func (*MaskedInput) MoveCursorLeft 

func (mi *MaskedInput) MoveCursorLeft()

MoveCursorLeft moves the cursor one slot to the left.

func (*MaskedInput) MoveCursorRight 

func (mi *MaskedInput) MoveCursorRight()

MoveCursorRight moves the cursor one slot to the right.

func (*MaskedInput) Placeholder 

func (mi *MaskedInput) Placeholder() string

Placeholder returns the current field-level placeholder string.

func (*MaskedInput) RawToDisplayIndex 

func (mi *MaskedInput) RawToDisplayIndex(rawIdx int) int

RawToDisplayIndex converts a raw slot index (0..capacity) to a display character offset. rawIdx=0 is before any char (offset 0); rawIdx=n is after the n-th slot character in the display string. This is exported for testing.

func (*MaskedInput) RawValue 

func (mi *MaskedInput) RawValue() string

RawValue returns the filled slot characters without any literal separators.

func (*MaskedInput) SelectAll 

func (mi *MaskedInput) SelectAll()

SelectAll selects all editable slots.

func (*MaskedInput) SelectedText 

func (mi *MaskedInput) SelectedText() string

SelectedText returns the display text of the currently selected range, including any literal separator characters within the range.

func (*MaskedInput) SetCursorPos 

func (mi *MaskedInput) SetCursorPos(pos int)

SetCursorPos sets the raw-slot cursor position directly. Used for testing.

func (*MaskedInput) SetDebugSlots 

func (mi *MaskedInput) SetDebugSlots(v bool)

SetDebugSlots toggles a debug overlay that outlines each slot cell with a colored highlight, making the cell boundaries and padding visible.

func (*MaskedInput) SetEnabled 

func (mi *MaskedInput) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*MaskedInput) SetMask 

func (mi *MaskedInput) SetMask(mask string)

SetMask parses and applies a new mask string, resetting all slot values. Mask characters: '9'=digit, 'a'=letter, 'A'=upper letter, 'X'=upper alphanumeric, '*'=any visible ASCII. All other characters become literals.

func (*MaskedInput) SetMaskPlaceholder 

func (mi *MaskedInput) SetMaskPlaceholder(ch rune)

SetMaskPlaceholder sets the character shown for unfilled editable slots. Use 0 (default) to show blank space for unfilled slots. Note: changing this after SetMask is called rebuilds the cell layout since cell widths are derived from the placeholder character.

func (*MaskedInput) SetMaxLength 

func (mi *MaskedInput) SetMaxLength(n int)

SetMaxLength sets an optional character cap (0 = no limit beyond mask capacity).

func (*MaskedInput) SetOnBlur 

func (mi *MaskedInput) SetOnBlur(fn func())

SetOnBlur sets the callback invoked when the field loses focus.

func (*MaskedInput) SetOnChange 

func (mi *MaskedInput) SetOnChange(fn func(string))

SetOnChange sets the callback invoked with the formatted value on any change.

func (*MaskedInput) SetOnComplete 

func (mi *MaskedInput) SetOnComplete(fn func(raw, formatted string))

SetOnComplete sets the callback invoked when all slots become filled.

func (*MaskedInput) SetOnIncomplete 

func (mi *MaskedInput) SetOnIncomplete(fn func(raw, formatted string))

SetOnIncomplete sets the callback invoked when the field transitions from complete to incomplete.

func (*MaskedInput) SetOnRawChange 

func (mi *MaskedInput) SetOnRawChange(fn func(string))

SetOnRawChange sets the callback invoked with the raw value on any change.

func (*MaskedInput) SetOnSubmit 

func (mi *MaskedInput) SetOnSubmit(fn func(string))

SetOnSubmit sets the callback invoked when Enter is pressed.

func (*MaskedInput) SetPlaceholder 

func (mi *MaskedInput) SetPlaceholder(p string)

SetPlaceholder sets the field-level placeholder text shown when the mask is not set or the field is completely empty and mask placeholders are disabled.

func (*MaskedInput) SetRawValue 

func (mi *MaskedInput) SetRawValue(v string)

SetRawValue fills slots sequentially from a raw string (no literals expected).

func (*MaskedInput) SetSize 

func (mi *MaskedInput) SetSize(w, h float64)

SetSize sets the widget dimensions.

func (*MaskedInput) SetValue 

func (mi *MaskedInput) SetValue(v string)

SetValue fills slots from a formatted string. Characters that match slot types are accepted; literal separator characters in the input are ignored.

func (*MaskedInput) SetWidth 

func (mi *MaskedInput) SetWidth(w float64)

SetWidth sets only the width, computing height automatically from font and padding.

func (*MaskedInput) SnapCursorToFirstEmptyForTest 

func (mi *MaskedInput) SnapCursorToFirstEmptyForTest()

SnapCursorToFirstEmptyForTest calls snapCursorToFirstEmpty. Used for testing.

func (*MaskedInput) Submit 

func (mi *MaskedInput) Submit()

Submit fires the OnSubmit callback with the current formatted value.

func (*MaskedInput) Update 

func (mi *MaskedInput) Update()

Update handles keyboard input, cursor blink, and visual state.

func (*MaskedInput) UpdateVisuals 

func (mi *MaskedInput) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

func (*MaskedInput) Value 

func (mi *MaskedInput) Value() string

Value returns the formatted display string (filled slots + literals).

func (*MaskedInput) VisualDisplayIdxForTest 

func (mi *MaskedInput) VisualDisplayIdxForTest(rawIdx int) int

VisualDisplayIdxForTest calls visualDisplayIdx. Used for testing. 

type MenuBar struct {
	Component
	// contains filtered or unexported fields
}

MenuBar is a horizontal bar of labeled menu buttons that open dropdown MenuPopup panels. Provides the standard desktop-style application menu.

func NewMenuBar 

func NewMenuBar(name string, source *sg.FontFamily, displaySize float64) *MenuBar

NewMenuBar creates a new MenuBar with the given font source and display size. 

func (mb *MenuBar) SetEntries(entries []MenuBarEntry)

SetEntries sets the menu entries and rebuilds the bar. 

func (mb *MenuBar) SetEntry(index int, entry MenuBarEntry)

SetEntry replaces a single entry at the given index. 

func (mb *MenuBar) SetOnMenuClose(fn func())

SetOnMenuClose sets a callback fired when the active menu is closed. 

func (mb *MenuBar) SetOnMenuOpen(fn func(int))

SetOnMenuOpen sets a callback fired when a menu entry is opened. 

func (mb *MenuBar) SetSize(w, h float64)

SetSize sets the menu bar dimensions. 

type MenuBarEntry struct {
	Label string     // displayed in the bar (e.g. "File")
	Items []MenuItem // items shown when this entry is opened
}

MenuBarEntry defines one top-level menu in the bar. 

type MenuBarGroup = theme.MenuBarGroup
type MenuItem struct {
	Label     string
	OnSelect  func()
	Disabled  bool
	Separator bool   // if true renders as a thin divider; Label/OnSelect ignored
	Shortcut  string // display-only shortcut hint (e.g. "Ctrl+S"), right-aligned
}

MenuItem is a single entry in a MenuPopup. 

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

MenuPopup is a floating list of items displayed by MenuPopupManager. It is never added to the scene directly — Show/ShowAt go through the manager.

func NewMenuPopup 

func NewMenuPopup(source *sg.FontFamily, displaySize float64) *MenuPopup

NewMenuPopup creates a MenuPopup that will display items using source at displaySize. 

func (p *MenuPopup) SetItems(items []MenuItem)

SetItems sets the items to display. 

func (p *MenuPopup) SetOnDismiss(fn func())

SetOnDismiss sets a callback invoked when the popup closes without a selection. 

func (p *MenuPopup) SetVariant(v Variant)

SetVariant sets the theme variant used for styling. 

type MenuPopupGroup = theme.MenuPopupGroup
type MenuPopupManager struct {
	// contains filtered or unexported fields
}

MenuPopupManager manages the single active floating menu popup. Use DefaultMenuPopupManager; do not construct your own. 

func (m *MenuPopupManager) Hide()

Hide closes the active popup without selection. 

func (m *MenuPopupManager) IsOpen() bool

IsOpen returns true if a popup is currently visible. 

func (m *MenuPopupManager) Show(popup *MenuPopup, trigger *Component)

Show displays popup anchored below (or above) trigger component. 

func (m *MenuPopupManager) ShowAt(popup *MenuPopup, x, y float64)

ShowAt displays popup with top-left at (x, y).

type MeterBar 

type MeterBar struct {
	Component
	// contains filtered or unexported fields
}

MeterBar displays a horizontal bar that fills according to a value range. The default range is [0, 1]; call SetRange to use a custom range. It is non-interactive (no pointer callbacks needed).

func NewMeterBar 

func NewMeterBar(name string) *MeterBar

NewMeterBar creates a meter bar with range [0, 1] and value 0.

func NewProgressBar 

func NewProgressBar(name string) *MeterBar

NewProgressBar creates a MeterBar with range [0, 1]. Alias for NewMeterBar.

func (*MeterBar) BindValue 

func (mb *MeterBar) BindValue(ref *Ref[float64])

BindValue binds the meter bar to a reactive Ref[float64] (0-1 normalized).

func (*MeterBar) ClearFillColor 

func (mb *MeterBar) ClearFillColor()

ClearFillColor removes the fill color override, reverting to the theme color.

func (*MeterBar) Dispose 

func (mb *MeterBar) Dispose()

Dispose stops reactive watches and disposes children.

func (*MeterBar) FillNode 

func (mb *MeterBar) FillNode() *sg.Node

FillNode returns the fill component's willow node. Used for testing.

func (*MeterBar) FillWidth 

func (mb *MeterBar) FillWidth() float64

FillWidth returns the fill component's Width. Used for testing.

func (*MeterBar) LabelComp 

func (mb *MeterBar) LabelComp() *Label

LabelComp returns the progress label, or nil if not set. Used for testing.

func (*MeterBar) SetFillColor 

func (mb *MeterBar) SetFillColor(c sg.Color)

SetFillColor overrides the theme fill color with a custom color.

func (*MeterBar) SetProgress 

func (mb *MeterBar) SetProgress(v float64)

SetProgress sets the normalized 0-1 fill directly, bypassing range mapping. Used internally by BindValue.

func (*MeterBar) SetRange 

func (mb *MeterBar) SetRange(min, max float64)

SetRange sets the value range. Default is [0, 1].

func (*MeterBar) SetShowLabel 

func (mb *MeterBar) SetShowLabel(show bool, source *sg.FontFamily, displaySize float64)

SetShowLabel enables or disables a percentage label overlay.

func (*MeterBar) SetSize 

func (mb *MeterBar) SetSize(w, h float64)

SetSize sets the meter bar dimensions.

func (*MeterBar) SetValue 

func (mb *MeterBar) SetValue(v float64)

SetValue sets the meter value in the [min, max] range, mapping to 0-1 internally. With the default range [0, 1] this behaves identically to SetProgress.

func (*MeterBar) Value 

func (mb *MeterBar) Value() float64

Value returns the current normalized fill value (0-1), regardless of range.

type ModifierMask 

type ModifierMask uint8

ModifierMask is a bitmask of modifier keys. 

const (
	ModNone  ModifierMask = 0
	ModCtrl  ModifierMask = 1 << iota // Ctrl or Cmd
	ModShift                          // Shift
	ModAlt                            // Alt / Option
)
type NavDrawer struct {
	Component
	// contains filtered or unexported fields
}

NavDrawer is a slide-out navigation panel anchored to the left or right edge. It supports overlay mode (dims backdrop) and pinned mode (always visible, no backdrop).

func NewNavDrawer 

func NewNavDrawer(name string) *NavDrawer

NewNavDrawer creates a NavDrawer anchored to the left edge by default. 

func (d *NavDrawer) Backdrop() *sg.Node

Backdrop returns the backdrop node (for testing). 

func (d *NavDrawer) BindOpen(ref *Ref[bool])

BindOpen binds the open/closed state to a reactive Ref. Changes to the Ref open or close the drawer, and user interactions update the Ref. 

func (d *NavDrawer) Close()

Close slides the drawer out of view. 

func (d *NavDrawer) Dispose()

Dispose cleans up the drawer and its children. 

func (d *NavDrawer) DrawerPanel() *Panel

DrawerPanel returns the inner drawer panel for direct access. 

func (d *NavDrawer) IsOpen() bool

IsOpen returns whether the drawer is currently open (or opening). 

func (d *NavDrawer) IsPinned() bool

IsPinned returns whether the drawer is pinned open. 

func (d *NavDrawer) Open()

Open slides the drawer into view. 

func (d *NavDrawer) SetAnchor(anchor NavDrawerAnchor)

SetAnchor sets which edge the drawer slides from. 

func (d *NavDrawer) SetAnimationDuration(seconds float32)

SetAnimationDuration sets the slide animation duration in seconds. 

func (d *NavDrawer) SetCloseOnBackdropClick(v bool)

SetCloseOnBackdropClick sets whether clicking the backdrop closes the drawer. 

func (d *NavDrawer) SetContent(comp UIElement)

SetContent sets the drawer's content component. 

func (d *NavDrawer) SetOnClose(fn func())

SetOnClose sets the callback invoked when the drawer closes. 

func (d *NavDrawer) SetOnOpen(fn func())

SetOnOpen sets the callback invoked when the drawer opens. 

func (d *NavDrawer) SetPinned(v bool)

SetPinned sets whether the drawer is pinned open (always visible, no backdrop). 

func (d *NavDrawer) SetSize(w, h float64)

SetSize sets the overall NavDrawer container size (typically the full screen). 

func (d *NavDrawer) SetWidth(w float64)

SetWidth sets the drawer panel width. 

func (d *NavDrawer) Toggle()

Toggle opens the drawer if closed, or closes it if open. 

func (d *NavDrawer) Update(dt float32)

Update advances the slide animation. 

type NavDrawerAnchor int

NavDrawerAnchor specifies which edge the drawer slides from. 

const (
	NavDrawerLeft NavDrawerAnchor = iota
	NavDrawerRight
)

type NineSlice 

type NineSlice = render.NineSlice

NineSlice describes a nine-slice image for use as a component background.

type NineSliceNodes 

type NineSliceNodes = render.NineSliceNodes

NineSliceNodes is the public type for nine-slice node collections.

func CreateNineSliceNodes 

func CreateNineSliceNodes(name string, container *sg.Node, ns *NineSlice) *NineSliceNodes

CreateNineSliceNodes is an exported wrapper for render.CreateNineSliceNodes. Used for testing.

type NumberStepper 

type NumberStepper struct {
	Component
	// contains filtered or unexported fields
}

NumberStepper is a numeric input that pairs a text field with decrement and increment buttons. Clicking the buttons adjusts the value by the configured step; the text field accepts direct entry. Min, max, and decimal-place display are all configurable.

func NewNumberStepper 

func NewNumberStepper(name string, source *sg.FontFamily, displaySize float64) *NumberStepper

NewNumberStepper creates a NumberStepper with range (-∞, +∞), step 1, and zero decimal places.

func (*NumberStepper) BindValue 

func (ns *NumberStepper) BindValue(ref *Ref[float64])

BindValue binds the stepper to a reactive Ref[float64] for two-way sync. External changes to the ref update the stepper; stepper changes update the ref.

func (*NumberStepper) DecrementButton 

func (ns *NumberStepper) DecrementButton() *Button

DecrementButton returns the "-" button. Useful for styling.

func (*NumberStepper) Dispose 

func (ns *NumberStepper) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*NumberStepper) IncrementButton 

func (ns *NumberStepper) IncrementButton() *Button

IncrementButton returns the "+" button. Useful for styling.

func (*NumberStepper) InputField 

func (ns *NumberStepper) InputField() *TextInput

InputField returns the text input. Useful for styling.

func (*NumberStepper) SetDecimals 

func (ns *NumberStepper) SetDecimals(n int)

SetDecimals sets how many decimal places to display and accept (default 0). Changing this also reformats the current value.

func (*NumberStepper) SetEnabled 

func (ns *NumberStepper) SetEnabled(v bool)

SetEnabled enables or disables the stepper and all sub-components.

func (*NumberStepper) SetMax 

func (ns *NumberStepper) SetMax(v float64)

SetMax sets the maximum allowed value. The current value is re-clamped.

func (*NumberStepper) SetMin 

func (ns *NumberStepper) SetMin(v float64)

SetMin sets the minimum allowed value. The current value is re-clamped.

func (*NumberStepper) SetOnChange 

func (ns *NumberStepper) SetOnChange(fn func(float64))

SetOnChange sets the callback invoked whenever the value changes.

func (*NumberStepper) SetPageStep 

func (ns *NumberStepper) SetPageStep(v float64)

SetPageStep sets the step size used for Page Up / Page Down (default 0, which auto-computes as step × 10).

func (*NumberStepper) SetSize 

func (ns *NumberStepper) SetSize(w, h float64)

SetSize resizes the stepper and repositions its sub-components. The step buttons are square (height × height); the text field fills the rest.

func (*NumberStepper) SetStep 

func (ns *NumberStepper) SetStep(v float64)

SetStep sets the increment/decrement step size (default 1).

func (*NumberStepper) SetValue 

func (ns *NumberStepper) SetValue(v float64)

SetValue sets the value, clamping it to [min, max], updates the displayed text, and fires onChange and any bound Ref.

func (*NumberStepper) Value 

func (ns *NumberStepper) Value() float64

Value returns the current numeric value.

type OnSortScroll 

type OnSortScroll int

OnSortScroll controls scroll behavior after a sort operation. 

const (
	OnSortScrollNone        OnSortScroll = iota // do not scroll
	OnSortScrollToSelection                     // scroll to current selection
	OnSortScrollToTop                           // scroll to top
)

type OptionRotator 

type OptionRotator struct {
	Component
	// contains filtered or unexported fields
}

OptionRotator is a compact selection widget consisting of a left chevron, a centered value label, and a right chevron. Clicking either chevron — or pressing Left/Right arrow keys when focused — cycles through a fixed list of string options. Wraps by default.

func NewOptionRotator 

func NewOptionRotator(name string, options []string, source *sg.FontFamily, displaySize float64) *OptionRotator

NewOptionRotator creates an OptionRotator with the given name and initial options list. The selected index starts at 0 and wrapping is enabled. Panics if options is empty.

func (*OptionRotator) BindOptions 

func (or *OptionRotator) BindOptions(arr *Array[string])

BindOptions binds the options list to a reactive Array[string]. When the array changes the widget re-syncs its options and clamps the selection. Pass nil to detach.

func (*OptionRotator) BindSelected 

func (or *OptionRotator) BindSelected(ref *Ref[int])

BindSelected binds the widget to a *Ref[int] representing the selected index. External changes to the ref update the widget; user interaction updates the ref. Replaces any previous binding.

func (*OptionRotator) BindValue 

func (or *OptionRotator) BindValue(ref *Ref[string])

BindValue binds the widget to a *Ref[string] representing the current value string. On bind, the index is resolved by scanning options for an exact match. A value not present in the options list is silently ignored (index stays at 0). Replaces any previous binding.

func (*OptionRotator) Dispose 

func (or *OptionRotator) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*OptionRotator) Next 

func (or *OptionRotator) Next()

Next advances the selection by one step. Wraps to index 0 if wrap is enabled; no-op on the last option when wrap is disabled.

func (*OptionRotator) Options 

func (or *OptionRotator) Options() []string

Options returns a copy of the current options list.

func (*OptionRotator) Prev 

func (or *OptionRotator) Prev()

Prev steps the selection back by one. Wraps to the last option if wrap is enabled; no-op at index 0 when wrap is disabled.

func (*OptionRotator) Selected 

func (or *OptionRotator) Selected() int

Selected returns the current selected index.

func (*OptionRotator) SelectedRef 

func (or *OptionRotator) SelectedRef() *Ref[int]

SelectedRef returns the internal index Ref.

func (*OptionRotator) SetChevronIcons 

func (or *OptionRotator) SetChevronIcons(left, right engine.Image)

SetChevronIcons overrides the procedural chevron glyphs. Either argument may be nil to keep the procedural default for that side.

func (*OptionRotator) SetEnabled 

func (or *OptionRotator) SetEnabled(v bool)

SetEnabled enables or disables the widget and its chevron sub-components. Component.SetEnabled already fires onVisualStateChange → UpdateVisuals.

func (*OptionRotator) SetOnChange 

func (or *OptionRotator) SetOnChange(fn func(int, string))

SetOnChange registers a callback invoked after each selection change.

func (*OptionRotator) SetOptions 

func (or *OptionRotator) SetOptions(opts []string)

SetOptions replaces the options list entirely. The selected index is clamped to the new length. If the index changes as a result, OnChange fires.

func (*OptionRotator) SetSelected 

func (or *OptionRotator) SetSelected(i int)

SetSelected selects the option at index i. The index is clamped to the valid range. Fires OnChange only if the selection changes.

func (*OptionRotator) SetSize 

func (or *OptionRotator) SetSize(w, h float64)

SetSize resizes the widget and re-positions its sub-components.

func (*OptionRotator) SetWrap 

func (or *OptionRotator) SetWrap(v bool)

SetWrap controls whether cycling wraps around at the ends (default: true). When false, the corresponding chevron shows the Disabled visual state at the boundaries.

func (*OptionRotator) UpdateVisuals 

func (or *OptionRotator) UpdateVisuals()

UpdateVisuals applies theme colors and layout for the current state.

func (*OptionRotator) Value 

func (or *OptionRotator) Value() string

Value returns the current selected option string.

type Orientation 

type Orientation = core.Orientation

Orientation represents horizontal or vertical direction.

type Outline 

type Outline = markup.Outline

Outline defines a text stroke rendered behind the fill.

type Panel 

type Panel struct {
	Component
	// contains filtered or unexported fields
}

Panel is a static container with optional background color, border, and automatic child layout (VBox, HBox, Grid, or manual).

func NewPanel 

func NewPanel(name string) *Panel

NewPanel creates a Panel with no background and no border.

func (*Panel) AddChild 

func (p *Panel) AddChild(child UIElement)

AddChild adds a child component. The child's willow node is added as a child of the panel's root node, and layout is scheduled.

func (*Panel) SetAlignment 

func (p *Panel) SetAlignment(a Alignment)

SetAlignment sets the cross-axis alignment for VBox/HBox layouts.

func (*Panel) SetBackground 

func (p *Panel) SetBackground(c sg.Color)

SetBackground sets the panel's background color as a manual override. This prevents the theme from overwriting the background.

func (*Panel) SetBorder 

func (p *Panel) SetBorder(c sg.Color, width float64)

SetBorder sets the border color and width as a manual override. This prevents the theme from overwriting the border.

func (*Panel) SetCornerRadii 

func (p *Panel) SetCornerRadii(tl, tr, br, bl float64)

SetCornerRadii sets independent radii for each corner (TL, TR, BR, BL).

func (*Panel) SetJustify 

func (p *Panel) SetJustify(j Alignment)

SetJustify sets the main-axis alignment for VBox/HBox layouts.

func (*Panel) SetLayout 

func (p *Panel) SetLayout(mode LayoutMode)

SetLayout sets the child layout mode (LayoutNone, LayoutVBox, LayoutHBox, LayoutGrid).

func (*Panel) SetPadding 

func (p *Panel) SetPadding(top, right, bottom, left float64)

SetPadding sets the panel's content padding, overriding the theme default.

func (*Panel) SetSize 

func (p *Panel) SetSize(w, h float64)

SetSize sets the panel dimensions and updates background, border, and hit shape. If a layout mode is active, layout is applied immediately so callers see the final child positions without waiting for the next controller update cycle.

func (*Panel) SetSpacing 

func (p *Panel) SetSpacing(s float64)

SetSpacing sets the spacing between children for VBox/HBox/Grid layouts.

type PanelGroup 

type PanelGroup = theme.PanelGroup

type Popover 

type Popover struct {
	Component
	// contains filtered or unexported fields
}

Popover is a floating rich-content panel anchored to a trigger component. It is similar to Tooltip but dismissable, interactive, and designed for heavier content: mini-inspectors, inline documentation, quick-pick panels.

Popovers are managed by DefaultPopoverManager — only one is open at a time.

func NewPopover 

func NewPopover(name string) *Popover

NewPopover creates a new Popover with sensible defaults.

func (*Popover) Close 

func (p *Popover) Close()

Close closes the popover if it is currently open.

func (*Popover) IsOpen 

func (p *Popover) IsOpen() bool

IsOpen returns true when the popover is currently visible.

func (*Popover) Open 

func (p *Popover) Open(trigger *Component)

Open opens the popover anchored to the given trigger component. If another popover is open it will be closed first.

func (*Popover) SetContent 

func (p *Popover) SetContent(comp UIElement)

SetContent sets the component displayed in the popover body.

func (*Popover) SetContentSize 

func (p *Popover) SetContentSize(w, h float64)

SetContentSize sets the size of the content area (excluding title bar).

func (*Popover) SetOnClose 

func (p *Popover) SetOnClose(fn func())

SetOnClose sets a callback fired when the popover closes.

func (*Popover) SetOnOpen 

func (p *Popover) SetOnOpen(fn func())

SetOnOpen sets a callback fired when the popover opens.

func (*Popover) SetPreferredSide 

func (p *Popover) SetPreferredSide(side PopoverSide)

SetPreferredSide sets which side of the trigger the popover prefers to appear on.

func (*Popover) SetShowCloseButton 

func (p *Popover) SetShowCloseButton(v bool)

SetShowCloseButton controls whether an X button appears in the title bar.

func (*Popover) SetTitle 

func (p *Popover) SetTitle(text string, font *sg.FontFamily, size float64)

SetTitle sets an optional title displayed in the popover header.

type PopoverManager 

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

PopoverManager manages the single active floating popover. Use DefaultPopoverManager; do not construct your own.

func (*PopoverManager) Close 

func (m *PopoverManager) Close(p *Popover)

Close closes popover p if it is currently open on this manager.

func (*PopoverManager) Open 

func (m *PopoverManager) Open(p *Popover, trigger *Component)

Open displays popover p anchored to trigger. If another popover is open it is closed first. Callers may use this on a custom PopoverManager; otherwise prefer p.Open(trigger) which routes through DefaultPopoverManager.

type PopoverSide 

type PopoverSide int

PopoverSide controls which side of the trigger the popover prefers to appear on. 

const (
	PopoverBelow PopoverSide = iota // default
	PopoverAbove
	PopoverRight
	PopoverLeft
)

type ProgressBar 

type ProgressBar = MeterBar

ProgressBar is an alias for MeterBar.

type Radio 

type Radio struct {
	Component
	// contains filtered or unexported fields
}

Radio manages a group of mutually exclusive radio buttons.

func NewRadio 

func NewRadio(name string) *Radio

NewRadio creates a new empty Radio widget.

func (*Radio) AddOption 

func (rg *Radio) AddOption(text string, source *sg.FontFamily, displaySize float64) *RadioButton

AddOption adds a radio button with the given label to the group.

func (*Radio) BindSelected 

func (rg *Radio) BindSelected(ref *Ref[int])

BindSelected binds the selection to a reactive Ref[int].

func (*Radio) Buttons 

func (rg *Radio) Buttons() []*RadioButton

Buttons returns the slice of RadioButton widgets in this group. Used for testing radio group internals.

func (*Radio) Dispose 

func (rg *Radio) Dispose()

Dispose stops watches and disposes all buttons.

func (*Radio) Selected 

func (rg *Radio) Selected() int

Selected returns the index of the selected button, or -1 if none.

func (*Radio) SetColumns 

func (rg *Radio) SetColumns(n int)

SetColumns sets the number of columns (default 1 = single vertical stack). Call before or after adding options; triggers a layout update.

func (*Radio) SetOnChange 

func (rg *Radio) SetOnChange(fn func(int))

SetOnChange sets the callback invoked when selection changes.

func (*Radio) SetSelected 

func (rg *Radio) SetSelected(idx int)

SetSelected programmatically selects a button by index.

func (*Radio) SetVerticalFirst 

func (rg *Radio) SetVerticalFirst(v bool)

SetVerticalFirst controls fill order when columns > 1. false (default) = fill left-to-right then wrap (horizontal-first). true = fill top-to-bottom per column (vertical-first).

type RadioButton 

type RadioButton struct {
	Component
	// contains filtered or unexported fields
}

RadioButton is a single option within a Radio widget.

func (*RadioButton) Dispose 

func (rb *RadioButton) Dispose()

Dispose disposes the radio button and its label.

type ReactiveTreeNode 

type ReactiveTreeNode struct {
	Data     any
	Children *Array[*ReactiveTreeNode]
}

ReactiveTreeNode is a tree node whose children are a reactive Array. Mutations to any Children array anywhere in the subtree are automatically reflected in a TreeList bound via BindRoots.

func NewReactiveTreeNode 

func NewReactiveTreeNode(data any) *ReactiveTreeNode

NewReactiveTreeNode creates a ReactiveTreeNode with an empty Children array.

type Rect 

type Rect = render.Rect

Rect describes a rectangle with position and dimensions.

type Ref 

type Ref[T comparable] = reactive.Ref[T]

Type aliases — re-export internal types as willowui types.

func NewRef 

func NewRef[T comparable](initial T) *Ref[T]

NewRef creates a new reactive reference.

type RichText 

type RichText struct {
	Component
	// contains filtered or unexported fields
}

RichText renders multi-span styled text into a single offscreen image. Each span can have its own font, color, and outline; unset fields inherit from the RichText defaults. Word wrapping is supported across span boundaries.

func NewRichText 

func NewRichText(name string, source *sg.FontFamily, displaySize float64) *RichText

NewRichText creates a new RichText component with the given default font source and display size.

func (*RichText) AddBoldItalicSpan 

func (rt *RichText) AddBoldItalicSpan(text string, color sg.Color) *RichText

AddBoldItalicSpan appends a bold+italic text span with the given color. Returns rt for chaining.

func (*RichText) AddBoldSpan 

func (rt *RichText) AddBoldSpan(text string, color sg.Color) *RichText

AddBoldSpan appends a bold text span with the given color. Returns rt for chaining.

func (*RichText) AddItalicSpan 

func (rt *RichText) AddItalicSpan(text string, color sg.Color) *RichText

AddItalicSpan appends an italic text span with the given color. Returns rt for chaining.

func (*RichText) AddSpan 

func (rt *RichText) AddSpan(text string) *RichText

AddSpan appends a plain text span that inherits all styling from the RichText defaults. Returns rt for chaining.

func (*RichText) AddStyledSpan 

func (rt *RichText) AddStyledSpan(text string, source *sg.FontFamily, color sg.Color, outline *Outline) *RichText

AddStyledSpan appends a span with explicit styling overrides. Pass nil for source or outline to inherit from the RichText defaults. Color is always set explicitly (ColorSet = true) so the caller's color is used even if it happens to be the zero value. Returns rt for chaining.

func (*RichText) AddTextSpan 

func (rt *RichText) AddTextSpan(span TextSpan) *RichText

AddTextSpan appends a fully configured TextSpan. Returns rt for chaining.

func (*RichText) ClearSpans 

func (rt *RichText) ClearSpans() *RichText

ClearSpans removes all spans. Returns rt for chaining.

func (*RichText) Color 

func (rt *RichText) Color() sg.Color

Color returns the default text color. Used for testing.

func (*RichText) Dirty 

func (rt *RichText) Dirty() bool

Dirty returns whether the rich text needs re-rendering. Used for testing.

func (*RichText) Dispose 

func (rt *RichText) Dispose()

Dispose releases the offscreen image and disposes the component tree.

func (*RichText) HeadingScale 

func (rt *RichText) HeadingScale() [3]float64

HeadingScale returns the heading scale array. Used for testing.

func (*RichText) ImageForTest 

func (rt *RichText) ImageForTest() engine.Image

ImageForTest returns the internal offscreen image. Used for testing.

func (*RichText) LayoutLinesForTest 

func (rt *RichText) LayoutLinesForTest() []LayoutLineForTest

LayoutLinesForTest calls layoutLines and returns public views. Used for testing.

func (*RichText) OnLinkClickForTest 

func (rt *RichText) OnLinkClickForTest() func(string)

OnLinkClickForTest returns the onLinkClick callback. Used for testing.

func (*RichText) Render 

func (rt *RichText) Render()

Render composites all spans into the offscreen image and updates the sprite node. This should be called once per frame before drawing, typically in the scene's update function. It is a no-op if nothing has changed.

func (*RichText) ResolveColorForTest 

func (rt *RichText) ResolveColorForTest(span TextSpan) sg.Color

ResolveColorForTest calls resolveColor on the given span. Used for testing.

func (*RichText) ResolveFontForTest 

func (rt *RichText) ResolveFontForTest(span TextSpan) *sg.FontFamily

ResolveFontForTest calls resolveFont on the given span. Used for testing.

func (*RichText) ResolveOutlineForTest 

func (rt *RichText) ResolveOutlineForTest(span TextSpan) *Outline

ResolveOutlineForTest calls resolveOutline on the given span. Used for testing.

func (*RichText) SetAlign 

func (rt *RichText) SetAlign(a sg.TextAlign)

SetAlign sets the text alignment mode.

func (*RichText) SetColor 

func (rt *RichText) SetColor(c sg.Color)

SetColor sets the default text color for spans that do not override it.

func (*RichText) SetDirtyForTest 

func (rt *RichText) SetDirtyForTest(v bool)

SetDirtyForTest sets the dirty flag. Used for testing.

func (*RichText) SetHeadingScale 

func (rt *RichText) SetHeadingScale(h1, h2, h3 float64)

SetHeadingScale sets the size multipliers for h1, h2, and h3 headings.

func (*RichText) SetMarkup 

func (rt *RichText) SetMarkup(markup string) error

SetMarkup parses XML-like markup and replaces all spans.

func (*RichText) SetOnLinkClick 

func (rt *RichText) SetOnLinkClick(fn func(url string))

SetOnLinkClick sets a callback invoked when a <link> region is clicked.

func (*RichText) SetOutline 

func (rt *RichText) SetOutline(o *Outline)

SetOutline sets the default text outline for spans that do not override it.

func (*RichText) SetSpans 

func (rt *RichText) SetSpans(spans []TextSpan) *RichText

SetSpans replaces all spans at once. Returns rt for chaining.

func (*RichText) SetWrapWidth 

func (rt *RichText) SetWrapWidth(w float64)

SetWrapWidth sets the maximum pixel width before text wraps to the next line. A value of 0 disables wrapping.

func (*RichText) Spans 

func (rt *RichText) Spans() []TextSpan

Spans returns the current spans. Used for testing.

func (*RichText) SpriteNode 

func (rt *RichText) SpriteNode() *sg.Node

SpriteNode returns the internal sprite node. Used for testing.

type Scheduler 

type Scheduler = reactive.Scheduler

type Screen 

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

Screen bridges a Controller and the underlying willow scene. It owns the root component tree, focus manager, and scheduler, and manages the controller lifecycle.

func NewScreen 

func NewScreen(opts ...ScreenOption) *Screen

NewScreen creates a new Screen. Use WithController to attach a controller. The scene is set automatically by Stage.Add; use WithScene in tests.

func (*Screen) Add 

func (s *Screen) Add(e UIElement)

Add adds a UIElement (Component) to the screen's root.

func (*Screen) AddNode 

func (s *Screen) AddNode(n *sg.Node)

AddNode adds a raw sg.Node to the screen's root.

func (*Screen) Children 

func (s *Screen) Children() []*Component

Children returns the direct children of the screen root.

func (*Screen) ClearTemplateTree 

func (s *Screen) ClearTemplateTree()

ClearTemplateTree stops all tracked refs and removes all children from the screen root. Used by hot reload to tear down the previous component tree before re-instantiation.

func (*Screen) Destroy 

func (s *Screen) Destroy()

Destroy detaches the root node, calls OnDestroy, and disposes all tracked refs.

func (*Screen) FindByName 

func (s *Screen) FindByName(name string) *Component

FindByName searches the component tree for a component whose node name matches the given name. Returns nil if not found.

func (*Screen) FocusManager 

func (s *Screen) FocusManager() *FocusManager

FocusManager returns the focus manager used by this screen.

func (*Screen) Hide 

func (s *Screen) Hide()

Hide detaches the root node from the scene but preserves all state.

func (*Screen) InputManager 

func (s *Screen) InputManager() *InputManager

InputManager returns the input manager used by this screen.

func (*Screen) NumChildren 

func (s *Screen) NumChildren() int

NumChildren returns the number of direct children attached to the screen root.

func (*Screen) Remove 

func (s *Screen) Remove(e UIElement)

Remove detaches a UIElement from the screen's root.

func (*Screen) RemoveNode 

func (s *Screen) RemoveNode(n *sg.Node)

RemoveNode detaches a raw sg.Node from the screen's root.

func (*Screen) Scheduler 

func (s *Screen) Scheduler() *Scheduler

Scheduler returns the scheduler used by this screen.

func (*Screen) Show 

func (s *Screen) Show()

Show attaches the root node to the scene and calls OnCreate on first show.

func (*Screen) TrackRef 

func (s *Screen) TrackRef(r disposable)

TrackRef registers a disposable resource that will be automatically stopped when the screen is destroyed.

func (*Screen) Update 

func (s *Screen) Update(dt float64)

Update flushes the scheduler, reads input, runs focus dispatch, fires passthrough listeners, and calls the controller's OnUpdate.

func (*Screen) Visible 

func (s *Screen) Visible() bool

Visible returns whether the screen is currently shown.

type ScreenOption 

type ScreenOption func(*Screen)

ScreenOption configures a Screen during construction.

func WithController 

func WithController(c Controller) ScreenOption

WithController attaches a Controller to the screen.

func WithScene 

func WithScene(s *sg.Scene) ScreenOption

WithScene sets the scene on a Screen explicitly. Intended for use in tests; in production the scene is set automatically by Stage.Add.

type ScrollBar 

type ScrollBar struct {
	Component
	// contains filtered or unexported fields
}

ScrollBar is a scrollbar with a draggable thumb whose size reflects the visible portion relative to total content.

func NewScrollBar 

func NewScrollBar(name string) *ScrollBar

NewScrollBar creates a vertical scrollbar.

func (*ScrollBar) BindScrollPos 

func (sb *ScrollBar) BindScrollPos(ref *Ref[float64])

BindScrollPos binds the scrollbar to a reactive Ref[float64].

func (*ScrollBar) Dispose 

func (sb *ScrollBar) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*ScrollBar) ScrollPos 

func (sb *ScrollBar) ScrollPos() float64

ScrollPos returns the current scroll position.

func (*ScrollBar) SetContentSize 

func (sb *ScrollBar) SetContentSize(total, view float64)

SetContentSize sets the total content size and visible viewport size.

func (*ScrollBar) SetOnChange 

func (sb *ScrollBar) SetOnChange(fn func(float64))

SetOnChange sets the callback for scroll position changes.

func (*ScrollBar) SetOrientation 

func (sb *ScrollBar) SetOrientation(o Orientation)

SetOrientation sets horizontal or vertical orientation.

func (*ScrollBar) SetScrollPos 

func (sb *ScrollBar) SetScrollPos(v float64)

SetScrollPos sets the scroll position, clamping to valid range.

func (*ScrollBar) SetSize 

func (sb *ScrollBar) SetSize(w, h float64)

SetSize sets the scrollbar dimensions.

func (*ScrollBar) ThumbHeight 

func (sb *ScrollBar) ThumbHeight() float64

ThumbHeight returns the thumb component's Height. Used for testing.

func (*ScrollBar) ThumbNode 

func (sb *ScrollBar) ThumbNode() *sg.Node

ThumbNode returns the thumb component's willow node. Used for testing.

type ScrollMode 

type ScrollMode int

ScrollMode controls how the DataTable scrolls. 

const (
	ScrollModeVirtual ScrollMode = iota // virtualized: only visible rows are rendered
	ScrollModeStatic                    // static pool: all slots always present
)

type ScrollPanel 

type ScrollPanel struct {
	Panel
	// contains filtered or unexported fields
}

ScrollPanel is a Panel with built-in scrolling. Content that exceeds the viewport is clipped via a willow mask, and optional horizontal/vertical scrollbars allow the user to navigate.

func NewScrollPanel 

func NewScrollPanel(name string) *ScrollPanel

NewScrollPanel creates a scroll panel with a vertical scrollbar shown by default and a horizontal scrollbar hidden.

func (*ScrollPanel) AddChild 

func (sp *ScrollPanel) AddChild(child UIElement)

AddChild adds a child component to the scroll panel. The child's node is placed inside the scrollable content container.

func (*ScrollPanel) AddContent 

func (sp *ScrollPanel) AddContent(child UIElement)

AddContent adds a UIElement component to the scroll panel's content node.

func (*ScrollPanel) ContentH 

func (sp *ScrollPanel) ContentH() float64

ContentH returns the total content height set via SetContentSize. Used for testing scroll panel internals.

func (*ScrollPanel) ContentNode 

func (sp *ScrollPanel) ContentNode() *sg.Node

ContentNode returns the content container node. Add child willow nodes directly to this node for scrolled content that is not managed by the Component child system.

func (*ScrollPanel) Dispose 

func (sp *ScrollPanel) Dispose()

Dispose cleans up scrollbars and watches.

func (*ScrollPanel) EnsureVisible 

func (sp *ScrollPanel) EnsureVisible(child *Component)

EnsureVisible scrolls so that the given child component is fully visible within the scroll panel's viewport. If the component is already fully visible, no scrolling occurs.

func (*ScrollPanel) HScrollBar 

func (sp *ScrollPanel) HScrollBar() *ScrollBar

HScrollBar returns the horizontal scrollbar widget. Used for testing scroll panel internals.

func (*ScrollPanel) RemoveChild 

func (sp *ScrollPanel) RemoveChild(child UIElement)

RemoveChild detaches a child component from the scroll panel's content.

func (*ScrollPanel) ScrollTo 

func (sp *ScrollPanel) ScrollTo(x, y float64)

ScrollTo sets both scroll positions at once.

func (*ScrollPanel) ScrollX 

func (sp *ScrollPanel) ScrollX() float64

ScrollX returns the current horizontal scroll position.

func (*ScrollPanel) ScrollY 

func (sp *ScrollPanel) ScrollY() float64

ScrollY returns the current vertical scroll position.

func (*ScrollPanel) SetBackground 

func (sp *ScrollPanel) SetBackground(c sg.Color)

SetBackground sets the panel's background color as a manual override.

func (*ScrollPanel) SetBorder 

func (sp *ScrollPanel) SetBorder(c sg.Color, width float64)

SetBorder sets the border color and width as a manual override.

func (*ScrollPanel) SetContentSize 

func (sp *ScrollPanel) SetContentSize(w, h float64)

SetContentSize sets the total size of the scrollable content area.

func (*ScrollPanel) SetScrollX 

func (sp *ScrollPanel) SetScrollX(v float64)

SetScrollX sets the horizontal scroll position.

func (*ScrollPanel) SetScrollY 

func (sp *ScrollPanel) SetScrollY(v float64)

SetScrollY sets the vertical scroll position.

func (*ScrollPanel) SetSize 

func (sp *ScrollPanel) SetSize(w, h float64)

SetSize sets the scroll panel dimensions.

func (*ScrollPanel) ShowHScroll 

func (sp *ScrollPanel) ShowHScroll(show bool)

ShowHScroll shows or hides the horizontal scrollbar.

func (*ScrollPanel) ShowVScroll 

func (sp *ScrollPanel) ShowVScroll(show bool)

ShowVScroll shows or hides the vertical scrollbar.

func (*ScrollPanel) Update 

func (sp *ScrollPanel) Update()

Update processes mouse wheel input for scrolling. Call from your scene's UpdateFunc.

func (*ScrollPanel) VScrollBar 

func (sp *ScrollPanel) VScrollBar() *ScrollBar

VScrollBar returns the vertical scrollbar widget. Used for testing scroll panel internals.

func (*ScrollPanel) Viewport 

func (sp *ScrollPanel) Viewport() *sg.Node

Viewport returns the masked container node that clips content. Used for testing scroll panel internals. 

type SearchBox struct {
	Component

	// AutoHeight, when true, causes SetSize to ignore the height argument and
	// compute it automatically from font size and padding.
	AutoHeight bool
	// contains filtered or unexported fields
}

SearchBox is a search-oriented single-line input with a magnifier icon, optional clear button, debounce, and automatic reactive result population. It wraps a TextInput internally and adds search-specific behavior.

func NewSearchBox 

func NewSearchBox(name string, source *sg.FontFamily, displaySize float64) *SearchBox

NewSearchBox creates a SearchBox with the given name, font source, and display size. By default the search icon is shown and the clear button is enabled.

func (*SearchBox) BindValue 

func (sb *SearchBox) BindValue(ref *Ref[string])

BindValue binds the search box to a reactive Ref[string].

func (*SearchBox) CancelPendingSearch 

func (sb *SearchBox) CancelPendingSearch()

CancelPendingSearch cancels any pending debounced search without running it. Useful after programmatically setting the value (e.g. accepting an autocomplete suggestion) to prevent the dropdown from reopening.

func (*SearchBox) Clear 

func (sb *SearchBox) Clear()

Clear empties the query, hides the clear button, clears results, and fires OnClear.

func (*SearchBox) ClearVisible 

func (sb *SearchBox) ClearVisible() bool

ClearVisible returns whether the clear button is visible. Used for testing.

func (*SearchBox) Debounce 

func (sb *SearchBox) Debounce() time.Duration

Debounce returns the current debounce duration.

func (*SearchBox) DeleteBack 

func (sb *SearchBox) DeleteBack()

DeleteBack deletes the character before the cursor.

func (*SearchBox) DeleteForward 

func (sb *SearchBox) DeleteForward()

DeleteForward deletes the character after the cursor.

func (*SearchBox) Dispose 

func (sb *SearchBox) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*SearchBox) GetCursorPos 

func (sb *SearchBox) GetCursorPos() int

GetCursorPos returns the current cursor rune position. Used for testing.

func (*SearchBox) GetPlaceholder 

func (sb *SearchBox) GetPlaceholder() string

GetPlaceholder returns the placeholder string. Used for testing.

func (*SearchBox) HasSelection 

func (sb *SearchBox) HasSelection() bool

HasSelection returns true when text is selected.

func (*SearchBox) Input 

func (sb *SearchBox) Input() *TextInput

Input returns the inner TextInput for advanced configuration.

func (*SearchBox) InsertText 

func (sb *SearchBox) InsertText(s string)

InsertText inserts text at the cursor.

func (*SearchBox) IsSearching 

func (sb *SearchBox) IsSearching() bool

IsSearching returns true if a search is currently running.

func (*SearchBox) MinQueryLength 

func (sb *SearchBox) MinQueryLength() int

MinQueryLength returns the minimum query length.

func (*SearchBox) ResultsCount 

func (sb *SearchBox) ResultsCount() int

ResultsCount returns the number of results from the last search.

func (*SearchBox) SelectAll 

func (sb *SearchBox) SelectAll()

SelectAll selects the entire text.

func (*SearchBox) SetDebounce 

func (sb *SearchBox) SetDebounce(d time.Duration)

SetDebounce sets the debounce duration. Default is 150ms.

func (*SearchBox) SetEnabled 

func (sb *SearchBox) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*SearchBox) SetMinQueryLength 

func (sb *SearchBox) SetMinQueryLength(n int)

SetMinQueryLength sets the minimum character count before automatic search.

func (*SearchBox) SetOnBlur 

func (sb *SearchBox) SetOnBlur(fn func())

SetOnBlur sets the callback fired when the field loses focus.

func (*SearchBox) SetOnChange 

func (sb *SearchBox) SetOnChange(fn func(query string))

SetOnChange sets the callback fired when the query text changes.

func (*SearchBox) SetOnClear 

func (sb *SearchBox) SetOnClear(fn func())

SetOnClear sets the callback fired when the clear button is pressed.

func (*SearchBox) SetOnSearchEmpty 

func (sb *SearchBox) SetOnSearchEmpty(fn func(query string))

SetOnSearchEmpty sets the callback fired when search returns zero results.

func (*SearchBox) SetOnSearchFinish 

func (sb *SearchBox) SetOnSearchFinish(fn func(query string, count int))

SetOnSearchFinish sets the callback fired after each search with result count.

func (*SearchBox) SetOnSearchStart 

func (sb *SearchBox) SetOnSearchStart(fn func(query string))

SetOnSearchStart sets the callback fired before each search execution.

func (*SearchBox) SetOnSubmit 

func (sb *SearchBox) SetOnSubmit(fn func(query string))

SetOnSubmit sets the callback fired on Enter.

func (*SearchBox) SetPlaceholder 

func (sb *SearchBox) SetPlaceholder(v string)

SetPlaceholder sets the placeholder text.

func (*SearchBox) SetSearchOnChange 

func (sb *SearchBox) SetSearchOnChange(v bool)

SetSearchOnChange controls whether typing triggers automatic search.

func (*SearchBox) SetSearchOnSubmit 

func (sb *SearchBox) SetSearchOnSubmit(v bool)

SetSearchOnSubmit controls whether Enter triggers automatic search.

func (*SearchBox) SetShowClearButton 

func (sb *SearchBox) SetShowClearButton(v bool)

SetShowClearButton toggles the clear button.

func (*SearchBox) SetShowSearchIcon 

func (sb *SearchBox) SetShowSearchIcon(v bool)

SetShowSearchIcon toggles the magnifier icon.

func (*SearchBox) SetSize 

func (sb *SearchBox) SetSize(w, h float64)

SetSize sets the SearchBox dimensions.

func (*SearchBox) SetValue 

func (sb *SearchBox) SetValue(v string)

SetValue sets the query text.

func (*SearchBox) SetWidth 

func (sb *SearchBox) SetWidth(w float64)

SetWidth sets only the width; height is computed automatically.

func (*SearchBox) Submit 

func (sb *SearchBox) Submit()

Submit fires OnSubmit and optionally triggers search.

func (*SearchBox) TextNode 

func (sb *SearchBox) TextNode() *sg.Node

TextNode returns the willow text node. Used for testing.

func (*SearchBox) TriggerSearchNow 

func (sb *SearchBox) TriggerSearchNow()

TriggerSearchNow bypasses the debounce and runs the search immediately.

func (*SearchBox) UpdateVisuals 

func (sb *SearchBox) UpdateVisuals()

UpdateVisuals applies theme colors based on state.

func (*SearchBox) Value 

func (sb *SearchBox) Value() string

Value returns the current query text.

type SearchBoxGroup 

type SearchBoxGroup = theme.SearchBoxGroup

type Select 

type Select struct {
	Component
	// contains filtered or unexported fields
}

Select is a dropdown widget: shows the currently selected option and opens a MenuPopup when clicked.

func NewSelect 

func NewSelect(name string, options []SelectOption, source *sg.FontFamily, displaySize float64) *Select

NewSelect creates a Select with the given name, options list, font source, and display size.

func (*Select) BindOptions 

func (s *Select) BindOptions(arr *Array[SelectOption])

BindOptions binds the options list to a reactive Array[SelectOption]. When the array changes the dropdown re-syncs and clamps the selection. Pass nil to detach.

func (*Select) BindSelected 

func (s *Select) BindSelected(ref *Ref[int])

BindSelected binds the selection index to a reactive Ref[int]. External changes to the ref update the widget; user interaction updates the ref. Replaces any previous binding.

func (*Select) Dispose 

func (s *Select) Dispose()

Dispose stops reactive watches and disposes the component.

func (*Select) Selected 

func (s *Select) Selected() int

Selected returns the index of the currently selected option.

func (*Select) SelectedOption 

func (s *Select) SelectedOption() SelectOption

SelectedOption returns the currently selected SelectOption.

func (*Select) SelectedRef 

func (s *Select) SelectedRef() *Ref[int]

SelectedRef returns the reactive Ref backing the selection, or nil if BindSelected has not been called.

func (*Select) SetOnChange 

func (s *Select) SetOnChange(fn func(index int, option SelectOption))

SetOnChange registers a callback fired when the user selects an option.

func (*Select) SetOptions 

func (s *Select) SetOptions(options []SelectOption)

SetOptions replaces the option list. The selection resets to index 0.

func (*Select) SetSelected 

func (s *Select) SetSelected(idx int)

SetSelected selects the option at the given index.

func (*Select) SetSize 

func (s *Select) SetSize(w, h float64)

SetSize sets the explicit dimensions of the trigger button.

func (*Select) UpdateVisuals 

func (s *Select) UpdateVisuals()

UpdateVisuals applies theme colors and repositions children.

type SelectOption 

type SelectOption struct {
	Label string
	Value any // optional typed payload
}

SelectOption is a single choice in a Select widget.

type SelectionMode 

type SelectionMode int

SelectionMode controls row selection behavior. 

const (
	SelectionModeNone   SelectionMode = iota // no selection
	SelectionModeSingle                      // single row selection
	SelectionModeMulti                       // multi-row selection
)

type Slider 

type Slider struct {
	Component
	// contains filtered or unexported fields
}

Slider is a draggable range control for selecting a numeric value.

func NewSlider 

func NewSlider(name string) *Slider

NewSlider creates a horizontal slider with range [0, 1].

func (*Slider) BindValue 

func (s *Slider) BindValue(ref *Ref[float64])

BindValue binds the slider to a reactive Ref[float64].

func (*Slider) Dispose 

func (s *Slider) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*Slider) GetOrientation 

func (s *Slider) GetOrientation() Orientation

GetOrientation returns the current orientation. Used for testing.

func (*Slider) SetEnabled 

func (s *Slider) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*Slider) SetOnChange 

func (s *Slider) SetOnChange(fn func(float64))

SetOnChange sets the callback for value changes.

func (*Slider) SetOrientation 

func (s *Slider) SetOrientation(o Orientation)

SetOrientation sets horizontal or vertical orientation.

func (*Slider) SetRange 

func (s *Slider) SetRange(min, max float64)

SetRange sets the min and max values.

func (*Slider) SetSize 

func (s *Slider) SetSize(w, h float64)

SetSize sets the slider dimensions.

func (*Slider) SetStep 

func (s *Slider) SetStep(step float64)

SetStep sets the step increment (0 = continuous).

func (*Slider) SetValue 

func (s *Slider) SetValue(v float64)

SetValue sets the slider value, clamping and snapping as needed.

func (*Slider) ThumbNode 

func (s *Slider) ThumbNode() *sg.Node

ThumbNode returns the thumb component's willow node. Used for testing.

func (*Slider) UpdateVisuals 

func (s *Slider) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

func (*Slider) Value 

func (s *Slider) Value() float64

Value returns the current slider value.

type SortDir 

type SortDir int

SortDir indicates the sort order for a TreeTable column. 

const (
	SortDirAsc SortDir = iota
	SortDirDesc
)

type SortDirection 

type SortDirection int

SortDirection indicates the sort order for a column. 

const (
	SortNone SortDirection = iota // no sort
	SortAsc                       // ascending
	SortDesc                      // descending
)

type SortHandleSide 

type SortHandleSide int

SortHandleSide specifies which side of each row the drag handle appears on. 

const (
	SortHandleLeft SortHandleSide = iota
	SortHandleRight
)

type SortKey 

type SortKey struct {
	ColKey string
	Dir    SortDirection
}

SortKey identifies a column and its sort direction in a multi-sort stack.

type SortType 

type SortType int

SortType controls how a column's values are compared during sort. 

const (
	SortAlpha   SortType = iota // lexicographic (string) comparison
	SortNumeric                 // numeric comparison
	SortCustom                  // use the column's Comparator function
)

type SortableList 

type SortableList struct {
	Component
	// contains filtered or unexported fields
}

SortableList is a vertical list widget specialized for ordered collections. It supports drag-handle-based reordering, keyboard reorder commands, and reactive array binding.

func NewSortableList 

func NewSortableList(name string, itemHeight float64) *SortableList

NewSortableList creates a new sortable list with fixed item height.

func (*SortableList) BindSelected 

func (sl *SortableList) BindSelected(ref *Ref[int])

BindSelected binds the selection to a reactive Ref[int].

func (*SortableList) Dispose 

func (sl *SortableList) Dispose()

Dispose cleans up watches and child components.

func (*SortableList) ItemCount 

func (sl *SortableList) ItemCount() int

ItemCount returns the number of items.

func (*SortableList) MoveItem 

func (sl *SortableList) MoveItem(from, to int)

MoveItem moves an item from one index to another.

func (*SortableList) MoveSelectedDown 

func (sl *SortableList) MoveSelectedDown()

MoveSelectedDown moves the selected item down by one position.

func (*SortableList) MoveSelectedUp 

func (sl *SortableList) MoveSelectedUp()

MoveSelectedUp moves the selected item up by one position.

func (*SortableList) ScrollToIndex 

func (sl *SortableList) ScrollToIndex(idx int)

ScrollToIndex scrolls so that the given item index is visible.

func (*SortableList) Selected 

func (sl *SortableList) Selected() int

Selected returns the currently selected item index, or -1 if none.

func (*SortableList) SelectedItem 

func (sl *SortableList) SelectedItem() any

SelectedItem returns the data of the currently selected item, or nil.

func (*SortableList) SetDragEnabled 

func (sl *SortableList) SetDragEnabled(v bool)

SetDragEnabled enables or disables pointer-based drag reordering.

func (*SortableList) SetHandleSide 

func (sl *SortableList) SetHandleSide(side SortHandleSide)

SetHandleSide sets which side of each row the drag handle appears on.

func (*SortableList) SetKeyboardReorderEnabled 

func (sl *SortableList) SetKeyboardReorderEnabled(v bool)

SetKeyboardReorderEnabled enables or disables Alt+Up/Down reordering.

func (*SortableList) SetOnChange 

func (sl *SortableList) SetOnChange(fn func(int))

SetOnChange sets the callback for selection changes.

func (*SortableList) SetOnMoveDenied 

func (sl *SortableList) SetOnMoveDenied(fn func(from, to int))

SetOnMoveDenied sets the callback fired when a reorder is denied.

func (*SortableList) SetOnReorder 

func (sl *SortableList) SetOnReorder(fn func(from, to int))

SetOnReorder sets the callback fired after a successful reorder.

func (*SortableList) SetRenderItem 

func (sl *SortableList) SetRenderItem(fn func(int, any) *Component)

SetRenderItem sets the factory function that creates a Component for a given item index and data value.

func (*SortableList) SetSelected 

func (sl *SortableList) SetSelected(idx int)

SetSelected sets the selected item index.

func (*SortableList) SetShowHandles 

func (sl *SortableList) SetShowHandles(v bool)

SetShowHandles shows or hides drag handles.

func (*SortableList) SetSize 

func (sl *SortableList) SetSize(w, h float64)

SetSize sets the list dimensions and updates internal layout.

func (*SortableList) SetUpdateItem 

func (sl *SortableList) SetUpdateItem(fn func(int, any, *Component))

SetUpdateItem sets a function that updates an existing Component for a given item index and data value without recreating it.

func (*SortableList) SortableListScrollBar 

func (sl *SortableList) SortableListScrollBar() *ScrollBar

SortableListScrollBar returns the internal scrollbar. Used for testing.

func (*SortableList) Update 

func (sl *SortableList) Update()

Update processes mouse wheel input and keyboard navigation/reorder.

type SortableListGroup 

type SortableListGroup = theme.SortableListGroup

type SortableTreeItem 

type SortableTreeItem struct {
	ID       string
	ParentID string // empty = root
	Label    string
	Icon     sg.TextureRegion
	Depth    int // computed from ParentID if 0
}

SortableTreeItem represents a node in a sortable tree hierarchy.

type SortableTreeList 

type SortableTreeList struct {
	Component
	// contains filtered or unexported fields
}

SortableTreeList is a hierarchical list where nodes can be reordered by drag within their level and optionally reparented by dragging onto another node.

func NewSortableTreeList 

func NewSortableTreeList(name string, source *sg.FontFamily, displaySize float64) *SortableTreeList

NewSortableTreeList creates a new sortable tree list.

func (*SortableTreeList) BindSelected 

func (st *SortableTreeList) BindSelected(ref *Ref[int])

BindSelected two-way binds the selected index to an external Ref.

func (*SortableTreeList) CollapseAll 

func (st *SortableTreeList) CollapseAll()

CollapseAll collapses all items.

func (*SortableTreeList) Dispose 

func (st *SortableTreeList) Dispose()

Dispose cleans up resources.

func (*SortableTreeList) ExpandAll 

func (st *SortableTreeList) ExpandAll()

ExpandAll expands all items that have children.

func (*SortableTreeList) IndentSelected 

func (st *SortableTreeList) IndentSelected()

IndentSelected moves the selected item under its preceding sibling.

func (*SortableTreeList) IsExpanded 

func (st *SortableTreeList) IsExpanded(id string) bool

IsExpanded reports whether the given item ID is expanded.

func (*SortableTreeList) Items 

func (st *SortableTreeList) Items() []SortableTreeItem

Items returns the current items.

func (*SortableTreeList) MoveSelectedDown 

func (st *SortableTreeList) MoveSelectedDown()

MoveSelectedDown moves the selected item one position down within its parent.

func (*SortableTreeList) MoveSelectedUp 

func (st *SortableTreeList) MoveSelectedUp()

MoveSelectedUp moves the selected item one position up within its parent.

func (*SortableTreeList) OutdentSelected 

func (st *SortableTreeList) OutdentSelected()

OutdentSelected moves the selected item to its grandparent level.

func (*SortableTreeList) Selected 

func (st *SortableTreeList) Selected() int

Selected returns the currently selected flat list index, or -1.

func (*SortableTreeList) SetAllowCrossLevel 

func (st *SortableTreeList) SetAllowCrossLevel(v bool)

SetAllowCrossLevel enables or disables moving items to different depth levels.

func (*SortableTreeList) SetAllowReparent 

func (st *SortableTreeList) SetAllowReparent(v bool)

SetAllowReparent enables or disables reparenting by dragging onto a node.

func (*SortableTreeList) SetExpanded 

func (st *SortableTreeList) SetExpanded(id string, v bool)

SetExpanded sets the expansion state for a given item ID.

func (*SortableTreeList) SetItems 

func (st *SortableTreeList) SetItems(items []SortableTreeItem)

SetItems sets the tree items and refreshes the view.

func (*SortableTreeList) SetOnChange 

func (st *SortableTreeList) SetOnChange(fn func(int))

SetOnChange sets the callback for selection changes.

func (*SortableTreeList) SetOnReorder 

func (st *SortableTreeList) SetOnReorder(fn func(itemID, newParentID string, newIndex int))

SetOnReorder sets the callback for reorder/reparent completion.

func (*SortableTreeList) SetSelected 

func (st *SortableTreeList) SetSelected(idx int)

SetSelected sets the selected flat list index.

func (*SortableTreeList) SetSize 

func (st *SortableTreeList) SetSize(w, h float64)

SetSize sets the list dimensions.

func (*SortableTreeList) Update 

func (st *SortableTreeList) Update()

Update processes mouse wheel and keyboard input.

type SortableTreeListGroup 

type SortableTreeListGroup = theme.SortableTreeListGroup

type Spacer 

type Spacer struct {
	Component
}

Spacer is an invisible fixed-size gap for use in VBox/HBox layouts. It occupies space without rendering anything.

func NewSpacer 

func NewSpacer(name string, w, h float64) *Spacer

NewSpacer creates a Spacer with the given dimensions.

func (*Spacer) SetSize 

func (s *Spacer) SetSize(w, h float64)

SetSize updates the spacer's dimensions.

type StageManager 

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

StageManager manages a stack of screens. The package-level DefaultStage is wired automatically by ui.Setup. Use ui.Stage to access it in applications.

func NewStageManager 

func NewStageManager() *StageManager

NewStageManager creates a new StageManager. Primarily used for test isolation; in production use ui.Stage.

func (*StageManager) Add 

func (st *StageManager) Add(screen *Screen)

Add pushes screen onto the stack and shows it.

func (*StageManager) CloseAll 

func (st *StageManager) CloseAll()

CloseAll destroys all screens on the stack.

func (*StageManager) Remove 

func (st *StageManager) Remove(screen *Screen)

Remove destroys and removes a specific screen from the stack.

func (*StageManager) Replace 

func (st *StageManager) Replace(screen *Screen)

Replace destroys the top screen and shows the new screen in its place.

func (*StageManager) SetScene 

func (st *StageManager) SetScene(s *sg.Scene)

SetScene sets the scene used for attaching screen nodes. Called by ui.Setup; can also be called in tests.

func (*StageManager) Size 

func (st *StageManager) Size() int

Size returns the number of screens on the stack.

func (*StageManager) Top 

func (st *StageManager) Top() *Screen

Top returns the topmost screen, or nil if the stack is empty.

func (*StageManager) Update 

func (st *StageManager) Update(dt float64)

Update calls Update on all visible screens.

type StatAxis 

type StatAxis struct {
	Name  string
	Min   float64
	Max   float64
	Value float64
}

StatAxis defines a single spoke on a StatWeb.

type StatWeb 

type StatWeb struct {
	Component
	// contains filtered or unexported fields
}

StatWeb is an editable polygon stat display (spider/radar chart) with named axes and optional draggable handles for attribute editing.

func NewStatWeb 

func NewStatWeb(name string, source *sg.FontFamily, fontSize float64) *StatWeb

NewStatWeb creates a StatWeb with the given name, font source, and font size.

func (*StatWeb) Axes 

func (s *StatWeb) Axes() []StatAxis

Axes returns a copy of the current axes.

func (*StatWeb) IsEditable 

func (s *StatWeb) IsEditable() bool

IsEditable returns whether the stat web is in editable mode.

func (*StatWeb) SetAxes 

func (s *StatWeb) SetAxes(axes []StatAxis)

SetAxes defines all spokes at once.

func (*StatWeb) SetEditable 

func (s *StatWeb) SetEditable(v bool)

SetEditable enables or disables draggable axis handles.

func (*StatWeb) SetFillEnabled 

func (s *StatWeb) SetFillEnabled(v bool)

SetFillEnabled shows or hides the semi-transparent polygon fill.

func (*StatWeb) SetOnValueChanged 

func (s *StatWeb) SetOnValueChanged(fn func(index int, value float64))

SetOnValueChanged sets the callback for when a handle is dragged.

func (*StatWeb) SetSize 

func (s *StatWeb) SetSize(w, h float64)

SetSize sets the widget dimensions.

func (*StatWeb) SetValue 

func (s *StatWeb) SetValue(index int, value float64)

SetValue sets a single axis value by index.

func (*StatWeb) SetValues 

func (s *StatWeb) SetValues(values []float64)

SetValues bulk-sets values by index (parallel to axes).

func (*StatWeb) UpdateVisuals 

func (s *StatWeb) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

func (*StatWeb) Value 

func (s *StatWeb) Value(index int) float64

Value returns a single axis value by index.

func (*StatWeb) Values 

func (s *StatWeb) Values() []float64

Values returns a copy of all axis values.

type TabBar 

type TabBar struct {
	Component
	// contains filtered or unexported fields
}

TabBar is a horizontal row of tab buttons. Selecting a tab shows its associated panel and hides all others.

func NewTabBar 

func NewTabBar(name string, source *sg.FontFamily, displaySize float64) *TabBar

NewTabBar creates a new tab bar with the given font source and display size.

func (*TabBar) AddTab 

func (tb *TabBar) AddTab(label string, content *Component) int

AddTab adds a new tab with the given label and content panel, returning the tab index.

func (*TabBar) AddTabPage 

func (tb *TabBar) AddTabPage(label string, layout LayoutMode, spacing float64, padding Insets) (*Component, int)

AddTabPage creates a new page component with the given layout, spacing, and padding, adds it as a tab with the given label, and returns the page and its tab index. The page is sized to match the tab body.

func (*TabBar) BindSelected 

func (tb *TabBar) BindSelected(ref *Ref[int])

BindSelected binds the tab selection to a reactive Ref[int].

func (*TabBar) Dispose 

func (tb *TabBar) Dispose()

Dispose cleans up the tab bar.

func (*TabBar) LeftArrowVisible 

func (tb *TabBar) LeftArrowVisible() bool

LeftArrowVisible reports whether the left scroll arrow is visible.

func (*TabBar) OverflowMode 

func (tb *TabBar) OverflowMode() TabOverflowMode

OverflowMode returns the current overflow mode.

func (*TabBar) RemoveTab 

func (tb *TabBar) RemoveTab(index int)

RemoveTab removes a tab at the given index.

func (*TabBar) RightArrowVisible 

func (tb *TabBar) RightArrowVisible() bool

RightArrowVisible reports whether the right scroll arrow is visible.

func (*TabBar) ScrollOffset 

func (tb *TabBar) ScrollOffset() float64

ScrollOffset returns the current scroll offset in pixels. Always 0 when OverflowMode is TabOverflowClip.

func (*TabBar) ScrollToTab 

func (tb *TabBar) ScrollToTab(idx int)

ScrollToTab scrolls the bar so that the tab at idx is fully visible. No-op when OverflowMode is TabOverflowClip or when the tab is already visible.

func (*TabBar) Selected 

func (tb *TabBar) Selected() int

Selected returns the currently selected tab index.

func (*TabBar) SetOnChange 

func (tb *TabBar) SetOnChange(fn func(int))

SetOnChange sets the callback for tab selection changes.

func (*TabBar) SetOverflowMode 

func (tb *TabBar) SetOverflowMode(mode TabOverflowMode)

SetOverflowMode sets the overflow mode for the tab bar.

func (*TabBar) SetSelected 

func (tb *TabBar) SetSelected(idx int)

SetSelected sets the selected tab index.

func (*TabBar) SetSize 

func (tb *TabBar) SetSize(w, h float64)

SetSize sets the tab bar dimensions.

func (*TabBar) TabCount 

func (tb *TabBar) TabCount() int

TabCount returns the number of tabs.

type TabOverflowMode 

type TabOverflowMode int

TabOverflowMode controls what happens when tabs overflow the bar width. 

const (
	TabOverflowClip   TabOverflowMode = iota // default — tabs are clipped at the edge
	TabOverflowScroll                        // scroll arrows appear on overflow
)

type TableColumn 

type TableColumn struct {
	Key      string
	Label    string
	Width    float64
	Sortable bool
}

TableColumn defines a column in a TreeTable.

type Tag 

type Tag struct {
	Component
	// contains filtered or unexported fields
}

Tag is a compact pill widget used as a category marker, filter chip, or item classifier. It supports optional remove (×) and selectable (toggle) modes that may be combined.

func NewTag 

func NewTag(name string, source *sg.FontFamily, displaySize float64) *Tag

NewTag creates a Tag with the given name, font source, and display size.

func (*Tag) Selected 

func (t *Tag) Selected() bool

Selected returns the current toggle state.

func (*Tag) SetOnRemove 

func (t *Tag) SetOnRemove(fn func())

SetOnRemove sets the callback invoked when the × button is clicked.

func (*Tag) SetOnToggle 

func (t *Tag) SetOnToggle(fn func(selected bool))

SetOnToggle sets the callback invoked when the tag is toggled.

func (*Tag) SetPadding 

func (t *Tag) SetPadding(top, right, bottom, left float64)

SetPadding overrides the theme padding with per-instance values.

func (*Tag) SetRemovable 

func (t *Tag) SetRemovable(v bool)

SetRemovable shows or hides the × affordance.

func (*Tag) SetSelectable 

func (t *Tag) SetSelectable(v bool)

SetSelectable enables or disables toggle behaviour on click.

func (*Tag) SetSelected 

func (t *Tag) SetSelected(v bool)

SetSelected sets the toggle state (only meaningful when selectable).

func (*Tag) SetSize 

func (t *Tag) SetSize(w, h float64)

SetSize overrides the auto-size dimensions.

func (*Tag) SetText 

func (t *Tag) SetText(text string)

SetText updates the displayed text.

func (*Tag) SizeToContent 

func (t *Tag) SizeToContent()

SizeToContent auto-sizes the tag to fit its text plus padding.

func (*Tag) Text 

func (t *Tag) Text() string

Text returns the current text content.

func (*Tag) UpdateVisuals 

func (t *Tag) UpdateVisuals()

UpdateVisuals applies theme colors and corner radius.

type TagBar 

type TagBar struct {
	Component
	// contains filtered or unexported fields
}

TagBar is a tag-input widget where the user types text and presses Space (or Enter) to create a Tag chip. Each tag shows a × to delete it. The TagBar owns the list of tag values and renders them using Tag internally.

func NewTagBar 

func NewTagBar(name string, source *sg.FontFamily, displaySize float64) *TagBar

NewTagBar creates a TagBar with the given name, font source, and display size.

func (*TagBar) AddTag 

func (tb *TagBar) AddTag(text string)

AddTag adds a tag with the given text.

func (*TagBar) Dispose 

func (tb *TagBar) Dispose()

Dispose cleans up all tags and the inner TextInput.

func (*TagBar) RemoveTagAt 

func (tb *TagBar) RemoveTagAt(idx int)

RemoveTagAt removes the tag at the given index.

func (*TagBar) SetOnAddTag 

func (tb *TagBar) SetOnAddTag(fn func(text string))

SetOnAddTag sets a callback fired when a new tag is added.

func (*TagBar) SetOnChange 

func (tb *TagBar) SetOnChange(fn func(tags []string))

SetOnChange sets a callback fired whenever the tag list changes.

func (*TagBar) SetOnRemoveTag 

func (tb *TagBar) SetOnRemoveTag(fn func(text string))

SetOnRemoveTag sets a callback fired when a tag is removed.

func (*TagBar) SetPlaceholder 

func (tb *TagBar) SetPlaceholder(text string)

SetPlaceholder sets the placeholder text shown when the input is empty.

func (*TagBar) SetSize 

func (tb *TagBar) SetSize(w, h float64)

SetSize sets the outer dimensions of the TagBar.

func (*TagBar) SetTags 

func (tb *TagBar) SetTags(tags []string)

SetTags replaces the entire tag list.

func (*TagBar) Tags 

func (tb *TagBar) Tags() []string

Tags returns the current list of tag strings.

func (*TagBar) UpdateVisuals 

func (tb *TagBar) UpdateVisuals()

UpdateVisuals applies theme styling to the TagBar and its children.

type TextArea 

type TextArea struct {
	Component
	// contains filtered or unexported fields
}

TextArea is a multi-line text entry field with word wrapping and scrolling.

func NewTextArea 

func NewTextArea(name string, source *sg.FontFamily, displaySize float64) *TextArea

NewTextArea creates a multi-line text area with the given font source and display size.

func (*TextArea) BindValue 

func (ta *TextArea) BindValue(ref *Ref[string])

BindValue binds the text area to a reactive Ref[string].

func (*TextArea) ClearSelectionForTest 

func (ta *TextArea) ClearSelectionForTest()

ClearSelectionForTest calls the internal clearSelection method. Used for testing.

func (*TextArea) CursorVisualLineColForTest 

func (ta *TextArea) CursorVisualLineColForTest(pos int) (line, col int)

CursorVisualLineColForTest calls cursorVisualLineCol. Used for testing.

func (*TextArea) DeleteBack 

func (ta *TextArea) DeleteBack()

DeleteBack deletes the character before the cursor (backspace). If there is a selection, it deletes the selected text instead.

func (*TextArea) DeleteForward 

func (ta *TextArea) DeleteForward()

DeleteForward deletes the character after the cursor (delete key). If there is a selection, it deletes the selected text instead.

func (*TextArea) DeleteSelectionForTest 

func (ta *TextArea) DeleteSelectionForTest()

DeleteSelectionForTest calls the internal deleteSelection method. Used for testing.

func (*TextArea) Dispose 

func (ta *TextArea) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*TextArea) GetCursorPos 

func (ta *TextArea) GetCursorPos() int

GetCursorPos returns the current cursor rune position. Used for testing.

func (*TextArea) GetScrollY 

func (ta *TextArea) GetScrollY() float64

GetScrollY returns the current vertical scroll offset. Used for testing.

func (*TextArea) GetSelEnd 

func (ta *TextArea) GetSelEnd() int

GetSelEnd returns the selection end rune index. Used for testing.

func (*TextArea) GetSelStart 

func (ta *TextArea) GetSelStart() int

GetSelStart returns the selection start rune index. Used for testing.

func (*TextArea) GetVisualLinesForTest 

func (ta *TextArea) GetVisualLinesForTest() []VisualLine

GetVisualLinesForTest returns the current visual lines as public VisualLine structs. Used for testing.

func (*TextArea) HasSelection 

func (ta *TextArea) HasSelection() bool

HasSelection returns true when text is selected.

func (*TextArea) InsertText 

func (ta *TextArea) InsertText(s string)

InsertText inserts text at the current cursor position. If there is a selection, it replaces the selected text.

func (*TextArea) MoveCursorDown 

func (ta *TextArea) MoveCursorDown()

MoveCursorDown moves the cursor to the same horizontal position on the next visual line (or to the end of the text if already on the last line).

func (*TextArea) MoveCursorEndShiftForTest 

func (ta *TextArea) MoveCursorEndShiftForTest(shift bool)

MoveCursorEndShiftForTest calls moveCursorEndShift. Used for testing.

func (*TextArea) MoveCursorHomeShiftForTest 

func (ta *TextArea) MoveCursorHomeShiftForTest(shift bool)

MoveCursorHomeShiftForTest calls moveCursorHomeShift. Used for testing.

func (*TextArea) MoveCursorLeft 

func (ta *TextArea) MoveCursorLeft()

MoveCursorLeft moves the cursor one position to the left.

func (*TextArea) MoveCursorPageDownShiftForTest 

func (ta *TextArea) MoveCursorPageDownShiftForTest(shift bool)

MoveCursorPageDownShiftForTest calls moveCursorPageDownShift. Used for testing.

func (*TextArea) MoveCursorPageUpShiftForTest 

func (ta *TextArea) MoveCursorPageUpShiftForTest(shift bool)

MoveCursorPageUpShiftForTest calls moveCursorPageUpShift. Used for testing.

func (*TextArea) MoveCursorRight 

func (ta *TextArea) MoveCursorRight()

MoveCursorRight moves the cursor one position to the right.

func (*TextArea) MoveCursorRightShiftForTest 

func (ta *TextArea) MoveCursorRightShiftForTest(shift bool)

MoveCursorRightShiftForTest calls moveCursorRightShift. Used for testing.

func (*TextArea) MoveCursorUp 

func (ta *TextArea) MoveCursorUp()

MoveCursorUp moves the cursor to the same horizontal position on the previous visual line (or to the start of the text if already on the first line).

func (*TextArea) MoveCursorUpShiftForTest 

func (ta *TextArea) MoveCursorUpShiftForTest(shift bool)

MoveCursorUpShiftForTest calls moveCursorUpShift. Used for testing.

func (*TextArea) ScrollBar 

func (ta *TextArea) ScrollBar() *ScrollBar

ScrollBar returns the textarea's scrollbar widget. Used for testing.

func (*TextArea) SelectAll 

func (ta *TextArea) SelectAll()

SelectAll selects the entire text content.

func (*TextArea) SelectWordAtCursorForTest 

func (ta *TextArea) SelectWordAtCursorForTest()

SelectWordAtCursorForTest calls selectWordAtCursor. Used for testing.

func (*TextArea) SelectedText 

func (ta *TextArea) SelectedText() string

SelectedText returns the currently selected text.

func (*TextArea) SetAllowedChars 

func (ta *TextArea) SetAllowedChars(chars string)

SetAllowedChars restricts input to characters present in the given string.

func (*TextArea) SetAlphanumericOnly 

func (ta *TextArea) SetAlphanumericOnly()

SetAlphanumericOnly restricts input to ASCII letters and digits.

func (*TextArea) SetCharFilter 

func (ta *TextArea) SetCharFilter(fn func(rune) bool)

SetCharFilter sets a function called for each typed or pasted character. Return true to accept the character, false to reject it. Newlines are always allowed regardless of the filter. Passing nil clears any existing filter.

func (*TextArea) SetCursorPos 

func (ta *TextArea) SetCursorPos(pos int)

SetCursorPos sets the cursor rune position directly. Used for testing.

func (*TextArea) SetEnabled 

func (ta *TextArea) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*TextArea) SetMaxLength 

func (ta *TextArea) SetMaxLength(n int)

SetMaxLength limits the number of characters (0 = no limit).

func (*TextArea) SetNumericOnly 

func (ta *TextArea) SetNumericOnly()

SetNumericOnly restricts input to digit characters (0–9).

func (*TextArea) SetOnChange 

func (ta *TextArea) SetOnChange(fn func(string))

SetOnChange sets the callback for text changes.

func (*TextArea) SetRows 

func (ta *TextArea) SetRows(n int)

SetRows sets the number of visible rows.

func (*TextArea) SetSelEnd 

func (ta *TextArea) SetSelEnd(v int)

SetSelEnd sets the selection end directly. Used for testing.

func (*TextArea) SetSelStart 

func (ta *TextArea) SetSelStart(v int)

SetSelStart sets the selection start directly. Used for testing.

func (*TextArea) SetSize 

func (ta *TextArea) SetSize(w, h float64)

SetSize sets the textarea dimensions.

func (*TextArea) SetValue 

func (ta *TextArea) SetValue(v string)

SetValue sets the text content.

func (*TextArea) Update 

func (ta *TextArea) Update()

Update handles keyboard input, cursor blink, and visual state.

func (*TextArea) UpdateVisuals 

func (ta *TextArea) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

func (*TextArea) Value 

func (ta *TextArea) Value() string

Value returns the current text.

type TextInput 

type TextInput struct {
	Component

	// AutoHeight, when true, causes SetSize to ignore the height argument and
	// instead compute it automatically from the font size and theme padding.
	// This is equivalent to calling SetWidth instead of SetSize.
	AutoHeight bool
	// contains filtered or unexported fields
}

TextInput is a single-line text entry field.

func NewTextInput 

func NewTextInput(name string, source *sg.FontFamily, displaySize float64) *TextInput

NewTextInput creates a single-line text input with the given font source and display size.

func (*TextInput) BindPasswordMode 

func (ti *TextInput) BindPasswordMode(ref *Ref[bool])

BindPasswordMode binds password mode to a reactive Ref[bool].

func (*TextInput) BindValue 

func (ti *TextInput) BindValue(ref *Ref[string])

BindValue binds the text input to a reactive Ref[string].

func (*TextInput) ClearSelectionForTest 

func (ti *TextInput) ClearSelectionForTest()

ClearSelectionForTest calls the internal clearSelection method. Used for testing.

func (*TextInput) CursorNode 

func (ti *TextInput) CursorNode() *sg.Node

CursorNode returns the cursor sprite node. Used for testing.

func (*TextInput) DeleteBack 

func (ti *TextInput) DeleteBack()

DeleteBack deletes the character before the cursor (backspace). If there is a selection, it deletes the selected text instead.

func (*TextInput) DeleteForward 

func (ti *TextInput) DeleteForward()

DeleteForward deletes the character after the cursor (delete key). If there is a selection, it deletes the selected text instead.

func (*TextInput) DeleteSelectionForTest 

func (ti *TextInput) DeleteSelectionForTest()

DeleteSelectionForTest calls the internal deleteSelection method. Used for testing.

func (*TextInput) Dispose 

func (ti *TextInput) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*TextInput) GetCursorPos 

func (ti *TextInput) GetCursorPos() int

GetCursorPos returns the current cursor rune position. Used for testing.

func (*TextInput) GetPlaceholder 

func (ti *TextInput) GetPlaceholder() string

Placeholder returns the current placeholder string. Used for testing.

func (*TextInput) GetScrollX 

func (ti *TextInput) GetScrollX() float64

GetScrollX returns the current horizontal scroll offset. Used for testing.

func (*TextInput) GetSelEnd 

func (ti *TextInput) GetSelEnd() int

GetSelEnd returns the selection end rune index. Used for testing.

func (*TextInput) GetSelStart 

func (ti *TextInput) GetSelStart() int

GetSelStart returns the selection start rune index. Used for testing.

func (*TextInput) HasSelection 

func (ti *TextInput) HasSelection() bool

HasSelection returns true when text is selected.

func (*TextInput) InsertText 

func (ti *TextInput) InsertText(s string)

InsertText inserts text at the current cursor position. If there is a selection, it replaces the selected text. Newlines and carriage returns are stripped since TextInput is single-line.

func (*TextInput) IsPasswordMode 

func (ti *TextInput) IsPasswordMode() bool

IsPasswordMode returns true when password masking is active.

func (*TextInput) MoveCursorEndShiftForTest 

func (ti *TextInput) MoveCursorEndShiftForTest(shift bool)

MoveCursorEndShiftForTest calls moveCursorEndShift. Used for testing.

func (*TextInput) MoveCursorHomeShiftForTest 

func (ti *TextInput) MoveCursorHomeShiftForTest(shift bool)

MoveCursorHomeShiftForTest calls moveCursorHomeShift. Used for testing.

func (*TextInput) MoveCursorLeft 

func (ti *TextInput) MoveCursorLeft()

MoveCursorLeft moves the cursor one position to the left. If shift is true, the selection is extended; otherwise it collapses.

func (*TextInput) MoveCursorLeftShiftForTest 

func (ti *TextInput) MoveCursorLeftShiftForTest(shift bool)

MoveCursorLeftShiftForTest calls moveCursorLeftShift. Used for testing.

func (*TextInput) MoveCursorRight 

func (ti *TextInput) MoveCursorRight()

MoveCursorRight moves the cursor one position to the right. If shift is true, the selection is extended; otherwise it collapses.

func (*TextInput) MoveCursorRightShiftForTest 

func (ti *TextInput) MoveCursorRightShiftForTest(shift bool)

MoveCursorRightShiftForTest calls moveCursorRightShift. Used for testing.

func (*TextInput) PasswordDots 

func (ti *TextInput) PasswordDots() []*sg.Node

PasswordDots returns the password dot sprite pool. Used for testing.

func (*TextInput) SelRectNode 

func (ti *TextInput) SelRectNode() *sg.Node

SelRectNode returns the selection rectangle node, or nil if not created. Used for testing.

func (*TextInput) SelRectVisible 

func (ti *TextInput) SelRectVisible() bool

SelRectVisible reports whether the selection rectangle is visible. Used for testing.

func (*TextInput) SelectAll 

func (ti *TextInput) SelectAll()

SelectAll selects the entire text content.

func (*TextInput) SelectWordAtCursorForTest 

func (ti *TextInput) SelectWordAtCursorForTest()

SelectWordAtCursorForTest calls selectWordAtCursor. Used for testing.

func (*TextInput) SelectedText 

func (ti *TextInput) SelectedText() string

SelectedText returns the currently selected text.

func (*TextInput) SetAllowedChars 

func (ti *TextInput) SetAllowedChars(chars string)

SetAllowedChars restricts input to characters present in the given string.

func (*TextInput) SetAlphanumericOnly 

func (ti *TextInput) SetAlphanumericOnly()

SetAlphanumericOnly restricts input to ASCII letters and digits.

func (*TextInput) SetCharFilter 

func (ti *TextInput) SetCharFilter(fn func(rune) bool)

SetCharFilter sets a function called for each typed or pasted character. Return true to accept the character, false to reject it. Passing nil clears any existing filter.

func (*TextInput) SetCursorPos 

func (ti *TextInput) SetCursorPos(pos int)

SetCursorPos sets the cursor rune position directly. Used for testing.

func (*TextInput) SetEnabled 

func (ti *TextInput) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*TextInput) SetKeyFilter 

func (ti *TextInput) SetKeyFilter(fn func(engine.Key) bool)

SetKeyFilter sets an optional function called before special-key processing. If it returns true for a key, TextInput skips its default handling of that key. This lets composite widgets (e.g. NumberStepper) intercept keys like Home/End.

func (*TextInput) SetMaxLength 

func (ti *TextInput) SetMaxLength(n int)

SetMaxLength limits the number of characters (0 = no limit).

func (*TextInput) SetNumericOnly 

func (ti *TextInput) SetNumericOnly()

SetNumericOnly restricts input to digit characters (0–9).

func (*TextInput) SetOnBlur 

func (ti *TextInput) SetOnBlur(fn func())

SetOnBlur sets the callback invoked when the text input loses focus.

func (*TextInput) SetOnChange 

func (ti *TextInput) SetOnChange(fn func(string))

SetOnChange sets the callback for text changes.

func (*TextInput) SetOnSubmit 

func (ti *TextInput) SetOnSubmit(fn func(string))

SetOnSubmit sets the callback for enter/submit.

func (*TextInput) SetPasswordMode 

func (ti *TextInput) SetPasswordMode(v bool)

SetPasswordMode enables or disables password masking.

func (*TextInput) SetPlaceholder 

func (ti *TextInput) SetPlaceholder(p string)

SetPlaceholder sets the placeholder text shown when empty.

func (*TextInput) SetSelEnd 

func (ti *TextInput) SetSelEnd(v int)

SetSelEnd sets the selection end directly. Used for testing.

func (*TextInput) SetSelStart 

func (ti *TextInput) SetSelStart(v int)

SetSelStart sets the selection start directly. Used for testing.

func (*TextInput) SetSize 

func (ti *TextInput) SetSize(w, h float64)

SetSize sets the input dimensions. If AutoHeight is true, the height argument is ignored and computed automatically from the font size and padding.

func (*TextInput) SetValue 

func (ti *TextInput) SetValue(v string)

SetValue sets the text content.

func (*TextInput) SetWidth 

func (ti *TextInput) SetWidth(w float64)

SetWidth sets only the width, computing the height automatically from the font size and theme padding. This is the preferred way to size a TextInput when you don't need a custom height.

func (*TextInput) Submit 

func (ti *TextInput) Submit()

Submit triggers the onSubmit callback.

func (*TextInput) TextNode 

func (ti *TextInput) TextNode() *sg.Node

TextNode returns the willow text node used for displaying input content. Used for testing text input internals.

func (*TextInput) Update 

func (ti *TextInput) Update()

Update handles keyboard input, cursor blink, and visual state.

func (*TextInput) UpdateSelectionRectForTest 

func (ti *TextInput) UpdateSelectionRectForTest()

UpdateSelectionRectForTest calls the internal updateSelectionRect method. Used for testing.

func (*TextInput) UpdateVisuals 

func (ti *TextInput) UpdateVisuals()

UpdateVisuals applies theme colors based on current state.

func (*TextInput) Value 

func (ti *TextInput) Value() string

Value returns the current text.

func (*TextInput) ValueRef 

func (ti *TextInput) ValueRef() *Ref[string]

ValueRef returns the reactive Ref[string] backing this input's text value.

type TextInputGroup 

type TextInputGroup = theme.TextInputGroup

type TextSpan 

type TextSpan = markup.TextSpan

TextSpan represents a styled segment of text within a RichText component. Fields left at their zero values inherit from the parent RichText.

type Theme 

type Theme = theme.Theme

Theme holds the complete visual configuration for all WillowUI components.

type TileList 

type TileList struct {
	Component

	// ItemAlign controls horizontal alignment of each rendered item within
	// its tile cell. Default is AlignCenter.
	ItemAlign Alignment
	// ItemVAlign controls vertical alignment of each rendered item within
	// its tile cell. Default is AlignCenter.
	ItemVAlign Alignment
	// contains filtered or unexported fields
}

TileList is a grid-layout variant of List. Items are arranged in rows and columns, and only visible rows are rendered (virtualized).

func NewTileList 

func NewTileList(name string, tileW, tileH float64) *TileList

NewTileList creates a new tile list with the given tile dimensions.

func (*TileList) BindItems 

func (tl *TileList) BindItems(arr *Array[ListItem])

BindItems binds the tile list to a reactive Array[ListItem]. Any mutation to the array is automatically reflected in the tile list without resetting the scroll position.

Pass nil to detach the current binding.

func (*TileList) BindSelected 

func (tl *TileList) BindSelected(ref *Ref[int])

BindSelected binds the selection to a reactive Ref[int].

func (*TileList) ClearSelection 

func (tl *TileList) ClearSelection()

ClearSelection deselects the current tile.

func (*TileList) Dispose 

func (tl *TileList) Dispose()

Dispose cleans up the tile list.

func (*TileList) EffectiveColumns 

func (tl *TileList) EffectiveColumns() int

EffectiveColumns returns the computed number of columns.

func (*TileList) Items 

func (tl *TileList) Items() []ListItem

Items returns the current tile list items.

func (*TileList) PoolSize 

func (tl *TileList) PoolSize() int

PoolSize returns active component count for testing virtualization.

func (*TileList) ScrollToIndex 

func (tl *TileList) ScrollToIndex(idx int)

ScrollToIndex scrolls so that the given tile index is visible.

func (*TileList) ScrollToSelection 

func (tl *TileList) ScrollToSelection()

ScrollToSelection scrolls so that the currently selected tile is visible.

func (*TileList) SelectFirst 

func (tl *TileList) SelectFirst()

SelectFirst selects the first tile and scrolls to it.

func (*TileList) SelectLast 

func (tl *TileList) SelectLast()

SelectLast selects the last tile and scrolls to it.

func (*TileList) SelectNext 

func (tl *TileList) SelectNext()

SelectNext moves the selection to the next tile. If nothing is selected, selects the first tile. Scrolls to keep the selection visible.

func (*TileList) SelectPrevious 

func (tl *TileList) SelectPrevious()

SelectPrevious moves the selection to the previous tile. If nothing is selected, selects the last tile. Scrolls to keep the selection visible.

func (*TileList) Selectable 

func (tl *TileList) Selectable() bool

Selectable returns whether built-in selection highlighting is enabled.

func (*TileList) Selected 

func (tl *TileList) Selected() int

Selected returns the currently selected tile index.

func (*TileList) SelectedItem 

func (tl *TileList) SelectedItem() any

SelectedItem returns the data of the currently selected tile, or nil if no tile is selected.

func (*TileList) SelectedRef 

func (tl *TileList) SelectedRef() *Ref[int]

SelectedRef returns the reactive Ref backing the selection index.

func (*TileList) SetColumns 

func (tl *TileList) SetColumns(n int)

SetColumns sets the number of columns. 0 means auto-fit to width.

func (*TileList) SetItems 

func (tl *TileList) SetItems(items []ListItem)

SetItems replaces the tile list data and refreshes visible tiles. If SetUpdateItem has been configured, existing pool components are updated in place rather than destroyed and recreated, saving node allocation cost.

func (*TileList) SetOnChange 

func (tl *TileList) SetOnChange(fn func(int))

SetOnChange sets the callback for selection changes.

func (*TileList) SetRenderItem 

func (tl *TileList) SetRenderItem(fn func(int, any) *Component)

SetRenderItem sets the factory function for tile components.

func (*TileList) SetSelectable 

func (tl *TileList) SetSelectable(enabled bool)

SetSelectable enables or disables built-in selection highlighting.

func (*TileList) SetSelected 

func (tl *TileList) SetSelected(idx int)

SetSelected sets the selected tile index.

func (*TileList) SetSize 

func (tl *TileList) SetSize(w, h float64)

SetSize sets the tile list dimensions.

func (*TileList) SetUpdateItem 

func (tl *TileList) SetUpdateItem(fn func(int, any, *Component))

SetUpdateItem registers an optional callback for in-place component updates. When set, SetItems will call fn for each currently pooled tile instead of disposing and recreating it. Use this to update only the data-driven parts of a tile component (text, colors, progress bars) while keeping the node tree structure intact. 

tileList.SetUpdateItem(func(idx int, data any, comp *ui.Component) {
    spell := data.(Spell)
    // update name label, color bar, etc. on comp
})

func (*TileList) TileScrollBar 

func (tl *TileList) TileScrollBar() *ScrollBar

TileScrollBar returns the internal scrollbar. Used for testing.

func (*TileList) TileScrollPos 

func (tl *TileList) TileScrollPos() *Ref[float64]

TileScrollPos returns the reactive scroll position ref. Used for testing.

func (*TileList) Update 

func (tl *TileList) Update()

Update processes mouse wheel input and keyboard navigation for scrolling. This is called automatically via the willow node's OnUpdate hook; no manual call needed.

type TimeFormat 

type TimeFormat int

TimeFormat selects 12-hour or 24-hour time display. 

const (
	TimeFormat24h TimeFormat = iota
	TimeFormat12h
)

type TimePicker 

type TimePicker struct {
	Component
	// contains filtered or unexported fields
}

TimePicker is a compact hour/minute/second picker using up/down stepper columns separated by ":" dividers, with an optional AM/PM toggle in 12h mode.

func NewTimePicker 

func NewTimePicker(name string, source *sg.FontFamily, displaySize float64) *TimePicker

NewTimePicker creates a TimePicker with default 24h format, no seconds.

func (*TimePicker) AmPmButton 

func (tp *TimePicker) AmPmButton() *Button

AmPmButton returns the AM/PM toggle button. Useful for styling.

func (*TimePicker) BindTime 

func (tp *TimePicker) BindTime(ref *Ref[TimeValue])

BindTime binds the time value to a reactive Ref. Changes to the Ref update the picker, and user interactions update the Ref.

func (*TimePicker) Dispose 

func (tp *TimePicker) Dispose()

Dispose cleans up the picker.

func (*TimePicker) Hour 

func (tp *TimePicker) Hour() int

Hour returns the current hour in 24h format (0-23).

func (*TimePicker) HourDownButton 

func (tp *TimePicker) HourDownButton() *Button

HourDownButton returns the hour column's down button.

func (*TimePicker) HourUpButton 

func (tp *TimePicker) HourUpButton() *Button

HourUpButton returns the hour column's up button. Useful for testing.

func (*TimePicker) Minute 

func (tp *TimePicker) Minute() int

Minute returns the current minute (0-59).

func (*TimePicker) MinuteDownButton 

func (tp *TimePicker) MinuteDownButton() *Button

MinuteDownButton returns the minute column's down button.

func (*TimePicker) MinuteUpButton 

func (tp *TimePicker) MinuteUpButton() *Button

MinuteUpButton returns the minute column's up button.

func (*TimePicker) Second 

func (tp *TimePicker) Second() int

Second returns the current second (0-59).

func (*TimePicker) SecondDownButton 

func (tp *TimePicker) SecondDownButton() *Button

SecondDownButton returns the second column's down button.

func (*TimePicker) SecondUpButton 

func (tp *TimePicker) SecondUpButton() *Button

SecondUpButton returns the second column's up button.

func (*TimePicker) SetEnabled 

func (tp *TimePicker) SetEnabled(v bool)

SetEnabled enables or disables the picker and all sub-components.

func (*TimePicker) SetFormat 

func (tp *TimePicker) SetFormat(format TimeFormat)

SetFormat sets 12h or 24h display format.

func (*TimePicker) SetOnTimeChanged 

func (tp *TimePicker) SetOnTimeChanged(fn func(h, m, s int))

SetOnTimeChanged sets the callback invoked when any time field changes.

func (*TimePicker) SetShowSeconds 

func (tp *TimePicker) SetShowSeconds(v bool)

SetShowSeconds shows or hides the seconds column.

func (*TimePicker) SetSize 

func (tp *TimePicker) SetSize(w, h float64)

SetSize resizes the picker and repositions sub-components.

func (*TimePicker) SetTime 

func (tp *TimePicker) SetTime(h, m, s int)

SetTime sets the time. h is in 24h range (0-23).

func (*TimePicker) UpdateVisuals 

func (tp *TimePicker) UpdateVisuals()

UpdateVisuals applies theme colors to all sub-components.

type TimeValue 

type TimeValue struct {
	Hour, Minute, Second int
}

TimeValue represents a time-of-day as hour (0-23), minute, and second. It is comparable and suitable for use with Ref[TimeValue].

type ToastAnchor 

type ToastAnchor int

ToastAnchor specifies which screen corner toasts stack at. 

const (
	ToastBottomRight ToastAnchor = iota // default
	ToastBottomLeft
	ToastTopRight
	ToastTopLeft
)

type ToastManager 

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

ToastManager manages a stack of transient toast notifications. Use DefaultToastManager; do not construct your own.

func (*ToastManager) DismissAll 

func (m *ToastManager) DismissAll()

DismissAll removes all active toasts immediately.

func (*ToastManager) SetAnchor 

func (m *ToastManager) SetAnchor(corner ToastAnchor)

SetAnchor sets the screen corner where toasts appear.

func (*ToastManager) SetFont 

func (m *ToastManager) SetFont(source *sg.FontFamily, size float64)

SetFont configures the font source used to render toast messages. Call this once at startup before showing toasts. Without a font, messages are not rendered but the toast still appears with icon and progress bar.

func (*ToastManager) SetMargin 

func (m *ToastManager) SetMargin(x, y float64)

SetMargin sets the pixel gap between the toast stack and the screen edge (default 16×16).

func (*ToastManager) SetMaxStack 

func (m *ToastManager) SetMaxStack(n int)

SetMaxStack sets the maximum number of toasts visible simultaneously (default 4). When the stack is full the oldest toast is dropped immediately.

func (*ToastManager) Show 

func (m *ToastManager) Show(message string, variant Variant, opts ...ToastOption)

Show displays a toast with the given message and variant.

type ToastOption 

type ToastOption func(*toastConfig)

ToastOption is a functional option for configuring a toast.

func WithDismissOnClick 

func WithDismissOnClick(v bool) ToastOption

WithDismissOnClick enables or disables click-to-dismiss (default true).

func WithDuration 

func WithDuration(d time.Duration) ToastOption

WithDuration sets the auto-dismiss duration.

func WithOnDismiss 

func WithOnDismiss(fn func()) ToastOption

WithOnDismiss sets a callback invoked when the toast is dismissed.

func WithProgress 

func WithProgress(v bool) ToastOption

WithProgress shows a shrinking remaining-time bar at the bottom of the toast.

type Toggle 

type Toggle struct {
	Component
	// contains filtered or unexported fields
}

Toggle is a binary on/off switch with an animated sliding thumb.

func NewToggle 

func NewToggle(name string) *Toggle

NewToggle creates a Toggle switch with default dimensions.

func (*Toggle) BindValue 

func (t *Toggle) BindValue(ref *Ref[bool])

BindValue binds the toggle to a reactive Ref[bool] for two-way binding.

func (*Toggle) Dispose 

func (t *Toggle) Dispose()

Dispose stops reactive watches and disposes the component tree.

func (*Toggle) SetEnabled 

func (t *Toggle) SetEnabled(v bool)

SetEnabled overrides Component.SetEnabled to also update visuals.

func (*Toggle) SetOnChange 

func (t *Toggle) SetOnChange(fn func(bool))

SetOnChange sets the callback invoked when the toggle changes.

func (*Toggle) SetValue 

func (t *Toggle) SetValue(v bool)

SetValue sets the toggle state.

func (*Toggle) ThumbNode 

func (t *Toggle) ThumbNode() *sg.Node

ThumbNode returns the flat thumb sprite node. Used for testing.

func (*Toggle) ThumbPoly 

func (t *Toggle) ThumbPoly() *sg.Node

ThumbPoly returns the rounded thumb polygon node, or nil if not yet created. Used for testing.

func (*Toggle) TrackNode 

func (t *Toggle) TrackNode() *sg.Node

TrackNode returns the flat track sprite node. Used for testing.

func (*Toggle) TrackPoly 

func (t *Toggle) TrackPoly() *sg.Node

TrackPoly returns the rounded track polygon node, or nil if not yet created. Used for testing.

func (*Toggle) Update 

func (t *Toggle) Update(dt float32)

Update advances any active thumb animation. Call from your scene's UpdateFunc.

func (*Toggle) UpdateVisuals 

func (t *Toggle) UpdateVisuals()

UpdateVisuals applies theme colors based on the current state.

func (*Toggle) Value 

func (t *Toggle) Value() bool

Value returns the current toggle state.

type ToggleButtonBar 

type ToggleButtonBar struct {
	Component
	// contains filtered or unexported fields
}

ToggleButtonBar is a segmented control for single-selection among a set of labeled buttons. Only one button is selected at a time.

func NewToggleButtonBar 

func NewToggleButtonBar(name string, source *sg.FontFamily, displaySize float64) *ToggleButtonBar

NewToggleButtonBar creates a new toggle button bar with the given font and display size. If displaySize is 0, the native atlas size is used.

func (*ToggleButtonBar) AddButton 

func (t *ToggleButtonBar) AddButton(label string)

AddButton adds a labeled button to the bar and updates layout and visuals.

func (*ToggleButtonBar) BindButtons 

func (t *ToggleButtonBar) BindButtons(arr *Array[string])

BindButtons binds the button labels to a reactive Array[string]. When the array changes the bar is rebuilt from the new labels, preserving the selection index where possible. Pass nil to detach.

func (*ToggleButtonBar) BindSelected 

func (t *ToggleButtonBar) BindSelected(ref *Ref[int])

BindSelected binds the selection to a reactive Ref[int].

func (*ToggleButtonBar) ButtonCount 

func (t *ToggleButtonBar) ButtonCount() int

ButtonCount returns the number of buttons.

func (*ToggleButtonBar) Dispose 

func (t *ToggleButtonBar) Dispose()

Dispose cleans up the toggle button bar and all its entries.

func (*ToggleButtonBar) EntriesIsNil 

func (t *ToggleButtonBar) EntriesIsNil() bool

EntriesIsNil reports whether the entries slice is nil (after dispose). Used for testing.

func (*ToggleButtonBar) RemoveButton 

func (t *ToggleButtonBar) RemoveButton(idx int)

RemoveButton removes the button at the given index.

func (*ToggleButtonBar) Selected 

func (t *ToggleButtonBar) Selected() int

Selected returns the currently selected button index.

func (*ToggleButtonBar) SetOnChange 

func (t *ToggleButtonBar) SetOnChange(fn func(int))

SetOnChange sets the callback for selection changes.

func (*ToggleButtonBar) SetSelected 

func (t *ToggleButtonBar) SetSelected(idx int)

SetSelected sets the selected button index.

func (*ToggleButtonBar) SetSize 

func (t *ToggleButtonBar) SetSize(w, h float64)

SetSize sets the toggle button bar dimensions and updates layout.

type ToolBar 

type ToolBar struct {
	Component
	// contains filtered or unexported fields
}

ToolBar is a horizontal or vertical command strip for housing actions, toggle groups, separators, and compact controls.

func NewToolBar 

func NewToolBar(name string) *ToolBar

NewToolBar creates a new ToolBar with horizontal orientation and clip overflow.

func (*ToolBar) AddItem 

func (tb *ToolBar) AddItem(comp interface{ Node() *sg.Node })

AddItem adds a component as a toolbar item.

func (*ToolBar) AddSeparator 

func (tb *ToolBar) AddSeparator()

AddSeparator adds a visual divider between items.

func (*ToolBar) AddSpacer 

func (tb *ToolBar) AddSpacer()

AddSpacer adds a flexible space that pushes remaining items to the opposite end.

func (*ToolBar) Clear 

func (tb *ToolBar) Clear()

Clear removes all items from the toolbar.

func (*ToolBar) Dispose 

func (tb *ToolBar) Dispose()

Dispose cleans up the toolbar and all its items.

func (*ToolBar) Orientation 

func (tb *ToolBar) Orientation() Orientation

Orientation returns the current toolbar orientation.

func (*ToolBar) RemoveItem 

func (tb *ToolBar) RemoveItem(name string)

RemoveItem removes an item by name. Only component items are matched.

func (*ToolBar) SetOrientation 

func (tb *ToolBar) SetOrientation(o Orientation)

SetOrientation sets the toolbar orientation (Horizontal or Vertical).

func (*ToolBar) SetOverflowMode 

func (tb *ToolBar) SetOverflowMode(mode ToolBarOverflowMode)

SetOverflowMode sets how overflow is handled.

func (*ToolBar) SetSize 

func (tb *ToolBar) SetSize(w, h float64)

SetSize sets the toolbar dimensions and updates layout.

func (*ToolBar) SetWrap 

func (tb *ToolBar) SetWrap(v bool)

SetWrap is a shorthand for setting ToolBarWrap overflow mode.

type ToolBarOverflowMode 

type ToolBarOverflowMode int

ToolBarOverflowMode controls how items behave when they exceed the toolbar's bounds. 

const (
	ToolBarClip   ToolBarOverflowMode = iota // items clip at edge (default)
	ToolBarScroll                            // reserved for future scroll arrows
	ToolBarWrap                              // items wrap to new row/column
)

type ToolGroup 

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

ToolGroup manages mutually-exclusive selection among a set of IconButtons. When one button is activated, all others in the group are deactivated — similar to a radio group but for toolbar icon buttons.

func NewToolGroup 

func NewToolGroup() *ToolGroup

NewToolGroup creates a new ToolGroup. By default one button must always be selected; call SetAllowNone(true) to permit deselecting all.

func (*ToolGroup) Add 

func (tg *ToolGroup) Add(btn *IconButton)

Add appends an IconButton to the group and wires its click handler to select it (deselecting any previously active button in the group).

func (*ToolGroup) BindSelected 

func (tg *ToolGroup) BindSelected(ref *Ref[int])

BindSelected binds the group's selection to an external Ref[int].

func (*ToolGroup) ButtonCount 

func (tg *ToolGroup) ButtonCount() int

ButtonCount returns the number of buttons in the group.

func (*ToolGroup) Dispose 

func (tg *ToolGroup) Dispose()

Dispose stops any reactive watches.

func (*ToolGroup) Selected 

func (tg *ToolGroup) Selected() int

Selected returns the index of the currently active button, or -1 if none.

func (*ToolGroup) SetAllowNone 

func (tg *ToolGroup) SetAllowNone(v bool)

SetAllowNone controls whether clicking the active button deselects it (selected becomes -1). Default is false.

func (*ToolGroup) SetOnChange 

func (tg *ToolGroup) SetOnChange(fn func(int))

SetOnChange sets the callback invoked when the selection changes. The callback receives the new selected index (-1 if deselected).

func (*ToolGroup) SetSelected 

func (tg *ToolGroup) SetSelected(idx int)

SetSelected activates the button at idx (pass -1 to deselect all).

type Tooltip 

type Tooltip struct {
	Component

	// Configuration — set before first show; take effect on next show.
	ShowDelay       int           // frames of hover before appearing (default 30)
	HideDelay       int           // frames after cursor leaves before hiding (default 0)
	Anchor          TooltipAnchor // placement strategy (default TooltipAuto)
	OffsetX         float64       // horizontal nudge after placement (+right)
	OffsetY         float64       // vertical nudge after placement (+down) (default 4)
	FadeInDuration  float32       // fade-in duration in seconds (0 = instant)
	FadeOutDuration float32       // fade-out duration in seconds (0 = instant)
	FadeInEase      sg.EaseFunc   // easing for fade-in (nil = linear)
	FadeOutEase     sg.EaseFunc   // easing for fade-out (nil = linear)
	ClampToScreen   bool          // keep fully inside viewport (default true)
	ClampMargin     float64       // minimum gap from each viewport edge (default 4)
	// contains filtered or unexported fields
}

Tooltip is a floating overlay that appears after a hover delay, anchored relative to the triggering widget. It embeds Component, giving it full layout and child-management capabilities.

Tooltips are never added directly to the scene — the DefaultTooltipManager manages their lifecycle.

func NewTooltip 

func NewTooltip(name string) *Tooltip

NewTooltip creates a Tooltip with sensible defaults.

func (*Tooltip) Dispose 

func (tt *Tooltip) Dispose()

Dispose hides the tooltip and releases resources.

func (*Tooltip) Hide 

func (tt *Tooltip) Hide()

Hide hides the tooltip immediately, bypassing HideDelay and FadeOut.

func (*Tooltip) IsShowing 

func (tt *Tooltip) IsShowing() bool

IsShowing returns true when the tooltip is currently visible.

func (*Tooltip) SetAnchor 

func (tt *Tooltip) SetAnchor(a TooltipAnchor)

SetAnchor sets the Anchor placement strategy.

func (*Tooltip) SetClampMargin 

func (tt *Tooltip) SetClampMargin(px float64)

SetClampMargin sets the minimum pixel gap from each viewport edge.

func (*Tooltip) SetClampToScreen 

func (tt *Tooltip) SetClampToScreen(v bool)

SetClampToScreen enables or disables viewport clamping.

func (*Tooltip) SetFadeIn 

func (tt *Tooltip) SetFadeIn(seconds float32)

SetFadeIn sets the fade-in duration in seconds.

func (*Tooltip) SetFadeOut 

func (tt *Tooltip) SetFadeOut(seconds float32)

SetFadeOut sets the fade-out duration in seconds.

func (*Tooltip) SetHideDelay 

func (tt *Tooltip) SetHideDelay(frames int)

SetHideDelay sets the HideDelay.

func (*Tooltip) SetOffset 

func (tt *Tooltip) SetOffset(x, y float64)

SetOffset sets OffsetX and OffsetY simultaneously.

func (*Tooltip) SetShowDelay 

func (tt *Tooltip) SetShowDelay(frames int)

SetShowDelay sets the ShowDelay.

func (*Tooltip) SetSize 

func (tt *Tooltip) SetSize(w, h float64)

SetSize sets explicit dimensions, bypassing auto-sizing.

func (*Tooltip) SetText 

func (tt *Tooltip) SetText(text string, source *sg.FontFamily, size float64)

SetText replaces all children with a single Label displaying text.

func (*Tooltip) Show 

func (tt *Tooltip) Show(x, y float64)

Show displays the tooltip at the given screen position, bypassing the hover delay. The tooltip is not associated with any trigger; hide it with Hide().

type TooltipAnchor 

type TooltipAnchor int

TooltipAnchor controls where a tooltip is placed relative to its trigger. 

const (
	// Trigger-relative anchors.
	TooltipAuto  TooltipAnchor = iota // pick direction with most available space
	TooltipAbove                      // centered horizontally, flush above trigger
	TooltipBelow                      // centered horizontally, flush below trigger
	TooltipLeft                       // centered vertically, flush left of trigger
	TooltipRight                      // centered vertically, flush right of trigger

	// Viewport-corner anchors.
	TooltipCornerTopLeft
	TooltipCornerTopRight
	TooltipCornerBottomLeft
	TooltipCornerBottomRight

	// Mouse-tracking anchor.
	TooltipFollowMouse // repositions every frame at cursor + OffsetX/OffsetY
)

type TooltipManager 

type TooltipManager struct {
	// Enabled controls whether tooltips are shown at all (default true).
	Enabled bool
	// contains filtered or unexported fields
}

TooltipManager manages tooltip visibility for the scene. It is driven by a ticker node added to the scene root when SetScene is called.

The package-level DefaultTooltipManager is used by all components.

type TreeList 

type TreeList struct {
	Component
	// contains filtered or unexported fields
}

TreeList is a hierarchical list with expand/collapse support. Visible nodes are flattened into a list and rendered using the same virtualization as List.

func NewTreeList 

func NewTreeList(name string, itemHeight float64) *TreeList

NewTreeList creates a new tree list with the given item height.

func (*TreeList) BindRoots 

func (tl *TreeList) BindRoots(arr *Array[*ReactiveTreeNode])

BindRoots binds the tree list to a reactive Array[*ReactiveTreeNode]. Changes to any Children array anywhere in the subtree — at any depth — are automatically reflected in the tree view without resetting the scroll position or expand/collapse state.

The binding uses a stable internal map so that the *TreeNode pointers backing the selection ref remain valid across tree mutations.

Pass nil to detach the current binding.

func (*TreeList) BindSelected 

func (tl *TreeList) BindSelected(ref *Ref[*TreeNode])

BindSelected binds the selection to a reactive Ref[*TreeNode].

func (*TreeList) ClearSelection 

func (tl *TreeList) ClearSelection()

ClearSelection deselects the current node.

func (*TreeList) Collapse 

func (tl *TreeList) Collapse(node *TreeNode)

Collapse marks a tree node as collapsed and refreshes the view.

func (*TreeList) CollapseAll 

func (tl *TreeList) CollapseAll()

CollapseAll collapses all tree nodes.

func (*TreeList) Dispose 

func (tl *TreeList) Dispose()

Dispose cleans up the tree list.

func (*TreeList) Expand 

func (tl *TreeList) Expand(node *TreeNode)

Expand marks a tree node as expanded and refreshes the view.

func (*TreeList) ExpandAll 

func (tl *TreeList) ExpandAll()

ExpandAll expands all tree nodes that have children.

func (*TreeList) FlatCount 

func (tl *TreeList) FlatCount() int

FlatCount returns the number of visible (flattened) entries.

func (*TreeList) IsExpanded 

func (tl *TreeList) IsExpanded(node *TreeNode) bool

IsExpanded reports whether a tree node is expanded.

func (*TreeList) LeafOnlySelection 

func (tl *TreeList) LeafOnlySelection() bool

LeafOnlySelection reports whether only leaf nodes can be selected.

func (*TreeList) PoolSize 

func (tl *TreeList) PoolSize() int

PoolSize returns active component count for testing virtualization.

func (*TreeList) Selectable 

func (tl *TreeList) Selectable() bool

Selectable reports whether built-in selection highlighting is enabled.

func (*TreeList) Selected 

func (tl *TreeList) Selected() *TreeNode

Selected returns the currently selected TreeNode, or nil if none.

func (*TreeList) SelectedRef 

func (tl *TreeList) SelectedRef() *Ref[*TreeNode]

SelectedRef returns the reactive Ref backing the selection.

func (*TreeList) SetDefaultTextRenderer 

func (tl *TreeList) SetDefaultTextRenderer(source *sg.FontFamily, displaySize float64, rowW, rowH float64)

SetDefaultTextRenderer configures a standard text rendering function for the tree list. Each node's Data is expected to be a string. Rows include depth-based indentation, a toggle button (or spacer for leaves), and a label.

func (*TreeList) SetLeafOnlySelection 

func (tl *TreeList) SetLeafOnlySelection(enabled bool)

SetLeafOnlySelection restricts selection to leaf nodes (nodes with no children). Parent nodes remain clickable for expand/collapse but cannot be selected. Has no effect when selectable is false.

func (*TreeList) SetOnChange 

func (tl *TreeList) SetOnChange(fn func(*TreeNode))

SetOnChange sets the callback invoked when the selection changes.

func (*TreeList) SetRenderItem 

func (tl *TreeList) SetRenderItem(fn func(*TreeNode, int) *Component)

SetRenderItem sets the factory function for rendering tree nodes.

func (*TreeList) SetRoots 

func (tl *TreeList) SetRoots(roots []*TreeNode)

SetRoots sets the root nodes of the tree and refreshes the view.

func (*TreeList) SetSelectable 

func (tl *TreeList) SetSelectable(enabled bool)

SetSelectable enables or disables built-in selection highlighting. When enabled, clicking a row selects it and a highlight bar is shown.

func (*TreeList) SetSelected 

func (tl *TreeList) SetSelected(node *TreeNode)

SetSelected sets the selected node.

func (*TreeList) SetSize 

func (tl *TreeList) SetSize(w, h float64)

SetSize sets the tree list dimensions.

func (*TreeList) SetToggleIcons 

func (tl *TreeList) SetToggleIcons(expand, collapse engine.Image)

SetToggleIcons sets custom expand and collapse icon images for tree toggle buttons created by NewTreeToggle. When set, these are used instead of the default procedural glyphs.

func (*TreeList) Toggle 

func (tl *TreeList) Toggle(node *TreeNode)

Toggle toggles the expanded state of a tree node.

func (*TreeList) Update 

func (tl *TreeList) Update()

Update processes mouse wheel input and keyboard navigation for scrolling. This is called automatically via the willow node's OnUpdate hook; no manual call needed.

type TreeNode 

type TreeNode struct {
	Data     any
	Children []*TreeNode
}

TreeNode represents a node in a hierarchical tree structure.

type TreeTable 

type TreeTable struct {
	Component
	// contains filtered or unexported fields
}

TreeTable is a hybrid tree + column grid where rows can be expanded/collapsed while each row spans multiple data columns.

func NewTreeTable 

func NewTreeTable(name string, source *sg.FontFamily, displaySize float64) *TreeTable

NewTreeTable creates a new TreeTable with the given name, font, and display size.

func (*TreeTable) CollapseAll 

func (tt *TreeTable) CollapseAll()

CollapseAll collapses all rows.

func (*TreeTable) Columns 

func (tt *TreeTable) Columns() []TableColumn

Columns returns a copy of the current column definitions.

func (*TreeTable) Dispose 

func (tt *TreeTable) Dispose()

Dispose cleans up resources.

func (*TreeTable) ExpandAll 

func (tt *TreeTable) ExpandAll()

ExpandAll expands all rows that have children.

func (*TreeTable) IsExpanded 

func (tt *TreeTable) IsExpanded(id string) bool

IsExpanded reports whether the given row ID is expanded.

func (*TreeTable) Node 

func (tt *TreeTable) Node() *sg.Node

Node returns the root node for adding to a scene.

func (*TreeTable) RowIDAt 

func (tt *TreeTable) RowIDAt(idx int) string

RowIDAt returns the row ID at the given flat list index, or "" if out of range.

func (*TreeTable) Rows 

func (tt *TreeTable) Rows() []TreeTableRow

Rows returns a copy of the original row data.

func (*TreeTable) Selected 

func (tt *TreeTable) Selected() int

Selected returns the currently selected flat list index, or -1.

func (*TreeTable) SetColumns 

func (tt *TreeTable) SetColumns(cols []TableColumn)

SetColumns sets the column definitions.

func (*TreeTable) SetExpanded 

func (tt *TreeTable) SetExpanded(id string, v bool)

SetExpanded sets the expansion state for a given row ID.

func (*TreeTable) SetOnRowClick 

func (tt *TreeTable) SetOnRowClick(fn func(id string))

SetOnRowClick sets the callback for interactive row clicks.

func (*TreeTable) SetOnRowExpand 

func (tt *TreeTable) SetOnRowExpand(fn func(id string, expanded bool))

SetOnRowExpand sets the callback for expand/collapse events.

func (*TreeTable) SetRows 

func (tt *TreeTable) SetRows(rows []TreeTableRow)

SetRows sets the row data. Rows may be nested via Children or flat via ParentID.

func (*TreeTable) SetSelected 

func (tt *TreeTable) SetSelected(idx int)

SetSelected sets the selected flat list index programmatically. This does NOT fire OnRowClick.

func (*TreeTable) SetSize 

func (tt *TreeTable) SetSize(w, h float64)

SetSize sets the widget dimensions.

func (*TreeTable) SetSortColumn 

func (tt *TreeTable) SetSortColumn(key string, dir SortDir)

SetSortColumn sets the sort column key and direction.

func (*TreeTable) VisibleRowCount 

func (tt *TreeTable) VisibleRowCount() int

VisibleRowCount returns the number of rows currently in the flat list.

type TreeTableRow 

type TreeTableRow struct {
	ID       string
	ParentID string // empty = root row
	Cells    map[string]string
	Children []TreeTableRow
}

TreeTableRow represents a row in the TreeTable hierarchy.

type TwoColumnLayout 

type TwoColumnLayout struct {
	Panel

	// LeftAlign controls alignment within the left column.
	// Default: AlignEnd (right-aligned, suits labels).
	LeftAlign Alignment

	// RightAlign controls alignment within the right column.
	// Default: AlignStart (left-aligned, suits inputs).
	RightAlign Alignment

	// LeftWidth sets a fixed pixel width for the left column.
	// When zero, ColumnRatio or an even split determines the width.
	LeftWidth float64

	// ColumnRatio sets the fraction of available width (after Gap) given to the
	// left column. 0.3 means left=30%, right=70%. Only used when LeftWidth is 0.
	// When both are zero, the columns split evenly (ratio 0.5).
	ColumnRatio float64

	// Gap is the horizontal space between the two columns.
	Gap float64

	// RowSpacing is the vertical space between rows.
	RowSpacing float64
	// contains filtered or unexported fields
}

TwoColumnLayout arranges children in labeled two-column rows. Each column is independently aligned. The primary use case is settings screens, stat sheets, and form dialogs where the left column contains labels and the right column contains input widgets.

Children are added in pairs via AddRow. The left column defaults to right-aligned (AlignEnd) for labels; the right column defaults to left-aligned (AlignStart) for values and inputs.

func NewTwoColumnLayout 

func NewTwoColumnLayout(name string) *TwoColumnLayout

NewTwoColumnLayout creates a TwoColumnLayout container with sensible defaults: left column right-aligned, right column left-aligned, 12px gap, 8px row spacing.

func (*TwoColumnLayout) AddRow 

func (tl *TwoColumnLayout) AddRow(left, right UIElement)

AddRow adds a row. When both left and right are provided, they are placed in their respective columns. When right is nil, left spans the full available width across both columns (clear:both equivalent).

func (*TwoColumnLayout) RemoveRow 

func (tl *TwoColumnLayout) RemoveRow(left UIElement)

RemoveRow removes the row containing left (or the spanning child), detaching it.

func (*TwoColumnLayout) SizeToContent 

func (tl *TwoColumnLayout) SizeToContent()

SizeToContent resizes the layout to tightly wrap all rows. Children must have their sizes set before calling this. UpdateLayout is called internally.

type UIElement 

type UIElement interface {
	// contains filtered or unexported methods
}

UIElement is implemented by all UI component types in this package. The unexported method prevents external types from implementing it.

type ValidationState 

type ValidationState int

ValidationState indicates the current validation status of an InputField. 

const (
	ValidationNone    ValidationState = iota // no validation state
	ValidationError                          // error state
	ValidationWarning                        // warning state
	ValidationSuccess                        // success state
)

type Variant 

type Variant = theme.Variant

Variant selects a color group for a component (e.g. Primary, Danger).

type VisualLine 

type VisualLine struct {
	RuneStart int // first rune index (inclusive)
	RuneEnd   int // end rune index (exclusive)
}

VisualLine is the exported representation of a visual line for testing.

type WatchHandle 

type WatchHandle = reactive.WatchHandle

func WatchEffect 

func WatchEffect(fn func()) WatchHandle

WatchEffect creates a reactive effect that re-runs when dependencies change.

func WatchValue 

func WatchValue[T comparable](ref *Ref[T], fn func(old, new T)) WatchHandle

WatchValue watches a specific Ref and calls fn with old and new values.

type Window 

type Window struct {
	Component
	// contains filtered or unexported fields
}

Window is a draggable, closeable, optionally resizable container with a title bar and body panel.

func NewWindow 

func NewWindow(name string, title string, source *sg.FontFamily, displaySize float64) *Window

NewWindow creates a window with the given title, font source, and display size. The window is draggable by the title bar and includes a close button.

func (*Window) Body 

func (w *Window) Body() *Panel

Body returns the body panel where content should be added.

func (*Window) BringToFront 

func (w *Window) BringToFront()

BringToFront moves this window in front of siblings by setting a high Z-index via the DefaultWindowManager.

func (*Window) Close 

func (w *Window) Close()

Close hides the window and fires the onClose callback.

func (*Window) CloseBtn 

func (w *Window) CloseBtn() *IconButton

CloseBtn returns the window's close IconButton widget. Used for testing window internals.

func (*Window) Dispose 

func (w *Window) Dispose()

Dispose cleans up the window and its children.

func (*Window) FireResult 

func (w *Window) FireResult(key string, data any)

FireResult hides the window and delivers a result to the registered handler. Typical use: button clicks or keyboard shortcuts inside the modal call FireResult("confirm", nil), FireResult("cancel", nil), etc.

func (*Window) IsModal 

func (w *Window) IsModal() bool

IsModal reports whether the window is in modal mode.

func (*Window) IsMovable 

func (w *Window) IsMovable() bool

IsMovable reports whether the window can be dragged.

func (*Window) MinSize 

func (w *Window) MinSize() (float64, float64)

MinSize returns the current minimum window dimensions.

func (*Window) ResizeFlat 

func (w *Window) ResizeFlat() *sg.Node

ResizeFlat returns the flat sprite resize handle node. Used for testing resize handle visibility.

func (*Window) ResizeHandle 

func (w *Window) ResizeHandle() *sg.Node

ResizeHandle returns the polygon resize grip node. Used for testing resize handle visibility.

func (*Window) SetCloseIcon 

func (w *Window) SetCloseIcon(img engine.Image)

SetCloseIcon sets a custom image for the close button icon at its native size and centers it within the button.

func (*Window) SetCloseable 

func (w *Window) SetCloseable(v bool)

SetCloseable shows or hides the close button.

func (*Window) SetEnterResult 

func (w *Window) SetEnterResult(key string)

SetEnterResult configures Enter to call FireResult(key, nil) while the window is visible. Pass "" to disable. Note: if a TextInput inside the dialog has focus, Enter is consumed by that input first.

func (*Window) SetEscResult 

func (w *Window) SetEscResult(key string)

SetEscResult configures Escape to call FireResult(key, nil) while the window is visible. Pass "" to disable.

func (*Window) SetMinHeight 

func (w *Window) SetMinHeight(v float64)

SetMinHeight sets the minimum height constraint for the window. Used for testing resize clamping.

func (*Window) SetMinSize 

func (w *Window) SetMinSize(minW, minH float64)

SetMinSize sets the minimum window dimensions enforced during resize.

func (*Window) SetMinWidth 

func (w *Window) SetMinWidth(v float64)

SetMinWidth sets the minimum width constraint for the window. Used for testing resize clamping.

func (*Window) SetModal 

func (w *Window) SetModal(v bool)

SetModal enables or disables modal mode. When modal, a semi-transparent overlay fills the viewport behind the window and intercepts all pointer input so nothing below it can be clicked. The overlay is created lazily the first time the window has a parent in the scene graph; call this after adding the window to the scene (or show it after SetModal) to guarantee the overlay is attached.

func (*Window) SetModalOverlayColor 

func (w *Window) SetModalOverlayColor(c sg.Color)

SetModalOverlayColor sets the color of the modal backdrop overlay. The default is semi-transparent black (RGBA 0,0,0,0.5).

func (*Window) SetMovable 

func (w *Window) SetMovable(v bool)

SetMovable controls whether the window can be repositioned by dragging the title bar. Defaults to true. Set to false for fixed-position dialogs.

func (*Window) SetOnClose 

func (w *Window) SetOnClose(fn func())

SetOnClose sets the callback invoked when the window is closed.

func (*Window) SetOnModalOverlayClick 

func (w *Window) SetOnModalOverlayClick(fn func())

SetOnModalOverlayClick sets a callback invoked when the user clicks the modal backdrop overlay. Set to nil to disable. Use this to implement "click outside to dismiss" behavior.

func (*Window) SetOnResult 

func (w *Window) SetOnResult(fn func(key string, data any))

SetOnResult registers the handler called when FireResult is invoked. key identifies the outcome (e.g. "confirm", "cancel"); data is optional payload. Set to nil to remove. Intended to be set by the caller each time the modal is opened so each invocation can handle its own outcome independently.

func (*Window) SetResizable 

func (w *Window) SetResizable(v bool)

SetResizable enables or disables the resize handle at the bottom-right.

func (*Window) SetSize 

func (w *Window) SetSize(width, height float64)

SetSize sets the window dimensions and recalculates internal layout.

func (*Window) SetTitle 

func (w *Window) SetTitle(t string)

SetTitle updates the window title text.

func (*Window) SetTitleBarHeight 

func (w *Window) SetTitleBarHeight(h float64)

SetTitleBarHeight sets the title bar height and recalculates layout.

func (*Window) SetVisible 

func (w *Window) SetVisible(v bool)

SetVisible overrides Component.SetVisible to keep the modal overlay in sync.

func (*Window) SizeToContent 

func (w *Window) SizeToContent()

SizeToContent sizes the window body to fit its children, then resizes the window to match (adding the title bar height). The resulting size is also set as the minimum size.

func (*Window) TitleLabel 

func (w *Window) TitleLabel() *Label

TitleLabel returns the window's title Label widget. Used for testing window internals.

type WindowManager 

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

WindowManager tracks a set of windows and handles z-ordering so that clicking any registered window automatically brings it to the front. It also tracks the active window and updates title bar colors.

func NewWindowManager 

func NewWindowManager() *WindowManager

NewWindowManager creates an empty WindowManager.

func (*WindowManager) Active 

func (wm *WindowManager) Active() *Window

Active returns the currently active (foremost) window, or nil.

func (*WindowManager) Add 

func (wm *WindowManager) Add(w *Window)

Add registers a window with the manager. Clicking anywhere on the window (title bar, body, resize handle) automatically brings it to the front.

func (*WindowManager) BringToFront 

func (wm *WindowManager) BringToFront(w *Window)

BringToFront moves the given window in front of all other managed windows and marks it as the active window, updating title bar colors.

func (*WindowManager) Remove 

func (wm *WindowManager) Remove(w *Window)

Remove unregisters a window from the manager.

func (*WindowManager) Windows 

func (wm *WindowManager) Windows() []*Window

Windows returns the currently registered windows.

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.