Documentation
¶
Overview ¶
Package checkbox provides a toggleable checkbox widget.
Construction uses functional options for immutable configuration, while fluent methods handle mutable styling:
cb := checkbox.New(
checkbox.Label("Accept terms"),
checkbox.OnToggle(handleToggle),
checkbox.Checked(true),
).Padding(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 checkboxes in the appropriate visual style.
If no painter is set, DefaultPainter is used, which draws a minimal gray checkbox suitable for testing and prototyping.
States ¶
A checkbox has three visual check states:
- Unchecked (default) -- empty box with a border
- Checked -- filled box with a checkmark
- Indeterminate -- filled box with a horizontal dash
The indeterminate state is used for "select all" checkboxes when only some items are selected.
Signal Binding ¶
Checkbox properties can be bound to reactive signals from the state package. Signals take highest priority in value resolution (Signal > Fn > Static).
- LabelSignal — one-way binding for the display label
- CheckedSignal — TWO-WAY binding: reads from signal AND writes back on toggle
- DisabledSignal — one-way binding for the disabled state
Example:
checked := state.NewSignal(false)
cb := checkbox.New(
checkbox.Label("Accept"),
checkbox.CheckedSignal(checked),
)
// User toggles checkbox → checked.Get() returns new value
// checked.Set(true) → checkbox reflects new state on next draw
Interaction ¶
Checkboxes respond to mouse click (left button) and keyboard activation (Space when focused). Each activation toggles the checked state and invokes the OnToggle callback. Disabled checkboxes ignore all interaction and are drawn with a dimmed appearance.
Focus ¶
Checkboxes implement widget.Focusable and participate in tab navigation. A focus ring is drawn when the checkbox has keyboard focus.
Index ¶
- type CheckboxColorScheme
- type DefaultPainter
- type Option
- func A11yHint(hint string) Option
- func Background(color widget.Color) Option
- func BackgroundOpt(color widget.Color) Option
- func Checked(b bool) Option
- func CheckedFn(fn func() bool) Option
- func CheckedSignal(sig state.Signal[bool]) 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 Indeterminate(b bool) Option
- func Label(s string) Option
- func LabelFn(fn func() string) Option
- func LabelOpt(s string) Option
- func LabelReadonlySignal(sig state.ReadonlySignal[string]) Option
- func LabelSignal(sig state.Signal[string]) Option
- func OnToggle(fn func(checked bool)) Option
- func PainterOpt(p Painter) Option
- type PaintState
- type Painter
- 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) Mount(ctx widget.Context)
- func (w *Widget) Padding(v float32) *Widget
- func (w *Widget) SetBackground(c widget.Color) *Widget
- func (w *Widget) Unmount()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CheckboxColorScheme ¶
type CheckboxColorScheme struct {
CheckedBg widget.Color // Filled box background when checked
CheckedFg widget.Color // Checkmark color
UncheckedBorder widget.Color // Border color when unchecked
LabelColor widget.Color // Label text color
DisabledBg widget.Color
DisabledFg widget.Color
FocusRing widget.Color
}
CheckboxColorScheme provides theme-derived colors for checkbox 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 checkbox -- useful for testing and as a base reference.
func (DefaultPainter) PaintCheckbox ¶
func (p DefaultPainter) PaintCheckbox(canvas widget.Canvas, state PaintState)
PaintCheckbox renders a minimal checkbox with gray colors. If state.ColorScheme is non-zero, its colors are used instead of built-in defaults.
type Option ¶
type Option func(*config)
Option configures a checkbox 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 CheckedFn ¶
CheckedFn sets a dynamic function that is evaluated to determine whether the checkbox is checked. When set, this takes precedence over the static value but not over a signal set via CheckedSignal.
func CheckedSignal ¶
CheckedSignal binds the checkbox's checked state to a reactive signal. This is a TWO-WAY binding: the widget reads the checked state from the signal, and when the user toggles the checkbox, the new state is written back to the signal. When set, the signal value takes precedence over both CheckedFn and Checked.
func Disabled ¶
Disabled sets the checkbox's disabled state. A disabled checkbox 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 checkbox 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 checkbox'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 checkbox's disabled state to a reactive signal. When set, the signal value takes precedence over both DisabledFn and Disabled but not over DisabledReadonlySignal.
func Indeterminate ¶
Indeterminate sets the checkbox to the indeterminate (mixed) state. An indeterminate checkbox displays a horizontal dash instead of a checkmark.
func Label ¶
Label sets the checkbox's static display label.
This is a convenience alias for LabelOpt.
func LabelFn ¶
LabelFn sets a dynamic label function that is evaluated on each draw. When set, this takes precedence over the static label but not over a signal set via LabelSignal.
func LabelReadonlySignal ¶
func LabelReadonlySignal(sig state.ReadonlySignal[string]) Option
LabelReadonlySignal binds the checkbox's display label to a read-only signal. This is useful for computed signals created via state.NewComputed. When set, this takes highest precedence over all other label sources.
func LabelSignal ¶
LabelSignal binds the checkbox's display label to a reactive signal. When set, the signal value takes precedence over both LabelFn and LabelOpt but not over LabelReadonlySignal.
func OnToggle ¶
OnToggle sets the callback invoked when the checkbox is toggled. The callback receives the new checked state.
func PainterOpt ¶
PainterOpt sets the painter used to render the checkbox. Each design system provides its own painter. If not set, DefaultPainter is used.
type PaintState ¶
type PaintState struct {
Label string
Checked bool
Indeterminate bool
Hovered bool
Pressed bool
Focused bool
Disabled bool
Bounds geometry.Rect
// Styling overrides (zero value means use design system defaults).
Background *widget.Color
ColorScheme CheckboxColorScheme
}
PaintState provides the current checkbox state to the painter.
type Painter ¶
type Painter interface {
PaintCheckbox(canvas widget.Canvas, state PaintState)
}
Painter draws the visual representation of a checkbox. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render the checkbox in its visual style.
If no Painter is set, the checkbox uses DefaultPainter.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a toggleable checkbox with configurable appearance and behavior.
A checkbox is created with New using functional options:
cb := checkbox.New(
checkbox.Label("Accept terms"),
checkbox.OnToggle(handleToggle),
checkbox.Checked(true),
)
Fluent styling methods may be chained after construction:
cb.Padding(8).SetBackground(theme.Primary)
func New ¶
New creates a new checkbox Widget with the given options.
The returned widget is visible, enabled, and focusable by default. Use options to configure label, toggle handler, and checked state.
func (*Widget) IsFocusable ¶
IsFocusable reports whether the checkbox can currently receive focus. A checkbox is focusable when it is visible, enabled, and not disabled.
func (*Widget) Layout ¶
Layout calculates the checkbox's preferred size within the given constraints.
func (*Widget) Mount ¶
Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.
func (*Widget) Padding ¶
Padding sets the padding around the checkbox box. Returns the widget for method chaining.
func (*Widget) SetBackground ¶
SetBackground sets a custom background color, overriding the default. Returns the widget for method chaining.
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the checkbox is removed from the widget tree. Implements widget.Lifecycle.
Source Files