Documentation
¶
Overview ¶
Package button provides a clickable button widget.
Construction uses functional options for immutable configuration, while fluent methods handle mutable styling:
btn := button.New(
button.Text("Submit"),
button.OnClick(handleSubmit),
button.VariantOpt(button.Filled),
).Padding(16).Rounded(8)
Visual Style ¶
The visual rendering is provided by a Painter implementation. Each design system (Material 3, Fluent, Cupertino) supplies its own painter to render buttons in the appropriate visual style.
If no painter is set, DefaultPainter is used, which draws a minimal gray button suitable for testing and prototyping.
Variants ¶
Four semantic variants are available:
- Filled (default) -- solid background with contrasting text
- Outlined -- transparent background with a border
- TextOnly -- no background or border, only text
- Tonal -- tinted background (lower emphasis than Filled)
The interpretation of each variant depends on the active Painter.
Sizes ¶
Three sizes control the button height:
Interaction ¶
Buttons respond to mouse events (hover, press, click) and keyboard activation (Enter or Space when focused). Disabled buttons ignore all interaction and are drawn with a dimmed appearance.
Signal Binding ¶
Button properties can be bound to reactive signals from the state package. When a signal value changes, the button automatically reflects the new state. Signal values take highest priority over dynamic functions and static values.
label := state.NewSignal("Click me")
disabled := state.NewSignal(false)
btn := button.New(
button.TextSignal(label),
button.DisabledSignal(disabled),
button.OnClick(func() {
label.Set("Clicked!")
disabled.Set(true)
}),
)
Focus ¶
Buttons implement widget.Focusable and participate in tab navigation. A focus ring is drawn when the button has keyboard focus.
Index ¶
- type ButtonColorScheme
- type DefaultPainter
- type Option
- func A11yHint(hint string) Option
- func Background(color widget.Color) Option
- func BackgroundOpt(color widget.Color) Option
- func Disabled(d bool) Option
- func DisabledFn(fn func() bool) Option
- func DisabledReadonlySignal(sig state.ReadonlySignal[bool]) Option
- func DisabledSignal(sig state.Signal[bool]) Option
- func OnClick(fn func()) Option
- func PainterOpt(p Painter) Option
- func Rounded(radius float32) Option
- func RoundedOpt(radius float32) Option
- func SizeOpt(s Size) Option
- func Text(s string) Option
- func TextFn(fn func() string) Option
- func TextOpt(s string) Option
- func TextReadonlySignal(sig state.ReadonlySignal[string]) Option
- func TextSignal(sig state.Signal[string]) Option
- func VariantOpt(v Variant) Option
- type PaintState
- type Painter
- type Size
- type Variant
- type Widget
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) Draw(ctx widget.Context, canvas widget.Canvas)
- func (w *Widget) Event(ctx widget.Context, e event.Event) bool
- func (w *Widget) IsFocusable() bool
- func (w *Widget) Layout(_ widget.Context, constraints geometry.Constraints) geometry.Size
- func (w *Widget) MaxWidth(v float32) *Widget
- func (w *Widget) MinWidth(v float32) *Widget
- func (w *Widget) Mount(ctx widget.Context)
- func (w *Widget) Padding(v float32) *Widget
- func (w *Widget) PaddingXY(x, y float32) *Widget
- func (w *Widget) SetBackground(c widget.Color) *Widget
- func (w *Widget) SetRounded(radius float32) *Widget
- func (w *Widget) Unmount()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ButtonColorScheme ¶
type ButtonColorScheme struct {
FilledBg widget.Color
FilledFg widget.Color
OutlinedBorder widget.Color
TextBgHover widget.Color
TonalBg widget.Color
TonalFg widget.Color
Primary widget.Color
DisabledBg widget.Color
DisabledFg widget.Color
FocusRing widget.Color
}
ButtonColorScheme provides theme-derived colors for button painting. Zero value means the painter should use its built-in defaults.
type DefaultPainter ¶
type DefaultPainter struct{}
DefaultPainter provides a minimal fallback painter with no design system styling. It draws a simple gray button -- useful for testing and as a base reference.
func (DefaultPainter) PaintButton ¶
func (p DefaultPainter) PaintButton(canvas widget.Canvas, state PaintState)
PaintButton renders a minimal button with gray background and black text. If state.ColorScheme is non-zero, its colors are used instead of built-in defaults.
type Option ¶
type Option func(*config)
Option configures a button during construction.
func Background ¶
Background sets a custom background color override via option.
This is a convenience alias for BackgroundOpt.
func BackgroundOpt ¶
BackgroundOpt sets a custom background color override.
func Disabled ¶
Disabled sets the button's disabled state. A disabled button does not respond to user input and is drawn with a dimmed appearance.
func DisabledFn ¶
DisabledFn sets a dynamic function that is evaluated to determine whether the button is disabled. When set, this takes precedence over the static value but not over a signal set via DisabledSignal.
func DisabledReadonlySignal ¶
func DisabledReadonlySignal(sig state.ReadonlySignal[bool]) Option
DisabledReadonlySignal binds the button's disabled state to a read-only signal. This is useful for computed signals created via state.NewComputed. When set, this takes highest precedence over all other disabled sources.
func DisabledSignal ¶
DisabledSignal binds the button's disabled state to a reactive signal. When set, the signal value takes precedence over both DisabledFn and Disabled but not over DisabledReadonlySignal.
func OnClick ¶
func OnClick(fn func()) Option
OnClick sets the callback invoked when the button is activated (mouse click or keyboard Enter/Space).
func PainterOpt ¶
PainterOpt sets the painter used to render the button. Each design system provides its own painter. If not set, DefaultPainter is used.
func Rounded ¶
Rounded sets a custom corner radius override via option.
This is a convenience alias for RoundedOpt.
func RoundedOpt ¶
RoundedOpt sets a custom corner radius override.
func TextFn ¶
TextFn sets a dynamic text function that is evaluated on each draw. When set, this takes precedence over the static text but not over a signal set via TextSignal.
func TextReadonlySignal ¶
func TextReadonlySignal(sig state.ReadonlySignal[string]) Option
TextReadonlySignal binds the button's display text to a read-only signal. This is useful for computed signals created via state.NewComputed. When set, this takes highest precedence over all other text sources.
func TextSignal ¶
TextSignal binds the button's display text to a reactive signal. When set, the signal value takes precedence over both TextFn and TextOpt but not over TextReadonlySignal.
type PaintState ¶
type PaintState struct {
Text string
Variant Variant
Size Size
Hovered bool
Pressed bool
Focused bool
Disabled bool
Bounds geometry.Rect
// Styling overrides (zero value means use design system defaults).
Background *widget.Color
Radius *float32
ColorScheme ButtonColorScheme
}
PaintState provides the current button state to the painter.
type Painter ¶
type Painter interface {
PaintButton(canvas widget.Canvas, state PaintState)
}
Painter draws the visual representation of a button. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render the button in its visual style.
If no Painter is set, the button uses DefaultPainter.
type Size ¶
type Size uint8
Size controls the dimensions of a button.
type Variant ¶
type Variant uint8
Variant controls the visual style of a button.
const ( // Filled renders a solid-colored button with contrasting text. // This is the default and highest-emphasis variant. Filled Variant = iota // Outlined renders a button with a border and transparent background. Outlined // TextOnly renders a button with no background or border, only text. TextOnly // Tonal renders a button with a tinted background (lower emphasis than Filled). Tonal )
Button variant constants.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a clickable button with configurable appearance and behavior.
A button is created with New using functional options:
btn := button.New(
button.Text("Submit"),
button.OnClick(handleSubmit),
button.VariantOpt(button.Filled),
)
Fluent styling methods may be chained after construction:
btn.Padding(16).Background(theme.Primary).Rounded(8)
func New ¶
New creates a new button Widget with the given options.
The returned widget is visible, enabled, and focusable by default. Use options to configure text, click handler, variant, and size.
func (*Widget) IsFocusable ¶
IsFocusable reports whether the button can currently receive focus. A button is focusable when it is visible, enabled, and not disabled.
func (*Widget) MaxWidth ¶
MaxWidth sets the maximum width for the button. Returns the widget for method chaining.
func (*Widget) MinWidth ¶
MinWidth sets the minimum width for the button. Returns the widget for method chaining.
func (*Widget) Mount ¶
Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.
func (*Widget) Padding ¶
Padding sets equal horizontal and vertical padding. Returns the widget for method chaining.
func (*Widget) PaddingXY ¶
PaddingXY sets horizontal and vertical padding separately. Returns the widget for method chaining.
func (*Widget) SetBackground ¶
SetBackground sets a custom background color, overriding the variant default. Returns the widget for method chaining.
func (*Widget) SetRounded ¶
SetRounded sets the corner radius for the button. Returns the widget for method chaining.
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the button is removed from the widget tree. Implements widget.Lifecycle.
Source Files