Documentation
¶
Overview ¶
Package progress provides a circular progress indicator widget with determinate and indeterminate modes.
In determinate mode, the indicator shows a progress arc from 0% to 100%. In indeterminate mode, a rotating arc spins continuously to indicate ongoing activity.
Construction uses functional options for immutable configuration:
// Determinate (65% complete)
indicator := progress.New(
progress.Value(0.65),
progress.Size(48),
progress.StrokeWidth(4),
progress.ShowLabel(true),
)
// Indeterminate (spinner)
spinner := progress.New(
progress.Indeterminate(true),
progress.Size(32),
)
Visual Style ¶
The visual rendering is provided by a Painter implementation. Each design system (Material 3, Fluent, Cupertino) supplies its own painter to render the indicator in the appropriate visual style.
If no painter is set, DefaultPainter is used, which draws the indicator using polyline arc approximation.
Signal Binding ¶
The value property supports 4-level signal binding priority:
- ValueReadonlySignal -- highest priority (computed/readonly signal)
- ValueSignal -- writable signal binding
- ValueFn -- dynamic function evaluated on each draw
- Value -- static value (lowest priority)
Accessibility ¶
Circular progress indicators are display-only widgets. They do not accept focus or handle input events.
Index ¶
- type DefaultPainter
- type Option
- func ColorSchemeOpt(cs ProgressColorScheme) 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 FormatLabelFn(fn func(float64) string) Option
- func Indeterminate(v bool) Option
- func IndicatorColor(color widget.Color) Option
- func PainterOpt(p Painter) Option
- func ShowLabel(show bool) Option
- func Size(diameter float32) Option
- func StrokeWidth(w float32) Option
- func TrackColor(color widget.Color) Option
- func Value(v float64) Option
- func ValueFn(fn func() float64) Option
- func ValueReadonlySignal(sig state.ReadonlySignal[float64]) Option
- func ValueSignal(sig state.Signal[float64]) Option
- type PaintState
- type Painter
- type ProgressColorScheme
- type Widget
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) Draw(ctx widget.Context, canvas widget.Canvas)
- func (w *Widget) Event(_ widget.Context, _ event.Event) bool
- func (w *Widget) IsIndeterminate() bool
- func (w *Widget) Layout(_ widget.Context, constraints geometry.Constraints) geometry.Size
- func (w *Widget) Mount(ctx widget.Context)
- func (w *Widget) SetValue(v float64)
- func (w *Widget) Unmount()
- func (w *Widget) Value() float64
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DefaultPainter ¶
type DefaultPainter struct{}
DefaultPainter provides a minimal fallback painter with no design system styling. It draws a circular progress indicator using cubic Bézier arc strokes.
func (DefaultPainter) PaintProgress ¶
func (p DefaultPainter) PaintProgress(canvas widget.Canvas, ps PaintState)
PaintProgress renders the circular progress indicator. In determinate mode, it draws a track circle and a progress arc. In indeterminate mode, it draws a rotating partial arc.
type Option ¶
type Option func(*config)
Option configures a circular progress indicator during construction.
func ColorSchemeOpt ¶
func ColorSchemeOpt(cs ProgressColorScheme) Option
ColorSchemeOpt sets the full color scheme for painting. This overrides the painter's built-in defaults.
func DisabledFn ¶
DisabledFn sets a dynamic function for the disabled state. 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 disabled state to a read-only signal. When set, this takes highest precedence over all other disabled sources.
func DisabledSignal ¶
DisabledSignal binds the disabled state to a reactive signal. When set, the signal value takes precedence over both DisabledFn and Disabled but not over DisabledReadonlySignal.
func FormatLabelFn ¶
FormatLabelFn sets a custom label formatting function. The function receives the current value (0.0 to 1.0) and returns the label string. If nil, the default "65%" format is used.
func Indeterminate ¶
Indeterminate sets whether the indicator shows as a spinning arc. When true, the value is ignored and the arc rotates continuously.
func IndicatorColor ¶
IndicatorColor sets the progress arc color.
func PainterOpt ¶
PainterOpt sets the painter used to render the progress indicator. Each design system provides its own painter. If not set, DefaultPainter is used.
func ShowLabel ¶
ShowLabel enables or disables the percentage label in the center. Only applies to determinate mode.
func StrokeWidth ¶
StrokeWidth sets the arc stroke width in logical pixels. Default is 4.
func TrackColor ¶
TrackColor sets the background circle color.
func Value ¶
Value sets the indicator's initial static value (0.0 to 1.0). Values outside [0, 1] are clamped during rendering.
func ValueFn ¶
ValueFn sets a dynamic value function that is evaluated on each draw. When set, this takes precedence over the static value but not over a signal set via ValueSignal or ValueReadonlySignal.
func ValueReadonlySignal ¶
func ValueReadonlySignal(sig state.ReadonlySignal[float64]) Option
ValueReadonlySignal binds the indicator's value to a read-only signal. This is useful for computed signals created via state.NewComputed. When set, this takes highest precedence over all other value sources.
func ValueSignal ¶
ValueSignal binds the indicator's value to a reactive signal. This is a one-way read binding: the widget reads the value from the signal. When set, the signal value takes precedence over both ValueFn and Value but not over ValueReadonlySignal.
type PaintState ¶
type PaintState struct {
Value float64 // current value clamped to [0, 1] (determinate mode)
Bounds geometry.Rect // total widget bounds
Diameter float32 // indicator diameter in logical pixels
StrokeWidth float32 // arc stroke width in logical pixels
ShowLabel bool // whether to show percentage label (determinate only)
Label string // pre-formatted label text (empty if ShowLabel is false)
Indeterminate bool // true for spinner mode
Rotation float64 // current rotation in radians (indeterminate mode)
AnimationPhase float64 // 0-1 sawtooth phase within one grow/shrink cycle
Disabled bool // widget is disabled
ColorScheme ProgressColorScheme // theme-derived colors (zero = use defaults)
}
PaintState provides the current progress indicator state to the painter.
type Painter ¶
type Painter interface {
PaintProgress(canvas widget.Canvas, state PaintState)
}
Painter draws the visual representation of a circular progress indicator. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render the indicator in its visual style.
If no Painter is set, the progress indicator uses DefaultPainter.
type ProgressColorScheme ¶
type ProgressColorScheme struct {
Indicator widget.Color // progress arc color
Track widget.Color // background circle color
Label widget.Color // label text color
DisabledIndicator widget.Color // arc color when disabled
DisabledTrack widget.Color // track color when disabled
// contains filtered or unexported fields
}
ProgressColorScheme provides theme-derived colors for progress indicator painting. Zero value means the painter should use its built-in defaults.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a circular progress indicator with determinate and indeterminate modes.
A circular progress indicator is created with New using functional options:
indicator := progress.New(
progress.Value(0.65),
progress.Size(48),
progress.ShowLabel(true),
)
func New ¶
New creates a new circular progress indicator with the given options.
The returned widget is visible and enabled by default. It is not focusable because progress indicators are display-only widgets.
func (*Widget) Event ¶
Event handles an input event. Progress indicators are display-only and always return false (events are never consumed).
func (*Widget) IsIndeterminate ¶
IsIndeterminate returns true if the indicator is in indeterminate (spinner) mode.
func (*Widget) Layout ¶
Layout calculates the indicator's preferred size within the given constraints.
func (*Widget) Mount ¶
Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.
func (*Widget) SetValue ¶
SetValue updates the indicator's static value. The value is clamped to [0, 1].
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the progress indicator is removed from the widget tree. Implements widget.Lifecycle.
Source Files