Documentation
¶
Overview ¶
Package progressbar provides a linear progress bar widget for displaying a value between 0% and 100%.
Construction uses functional options for immutable configuration, while fluent methods handle mutable styling:
bar := progressbar.New(
progressbar.Value(0.65),
progressbar.ShowLabel(true),
progressbar.Height(20),
).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 progress bars in the appropriate visual style.
If no painter is set, DefaultPainter is used, which draws a minimal progress bar suitable for testing and prototyping.
Value Range ¶
The progress bar displays a value in the range [0, 1], where 0 represents 0% completion and 1 represents 100%. Values outside this range are clamped.
Label ¶
When ShowLabel is enabled, the progress bar displays a percentage label centered over the bar. A custom label formatter can be provided via FormatLabelFn.
Signal Binding ¶
Progress bar properties can be bound to reactive signals from the state package. When a signal value changes, the progress bar automatically reflects the new state.
- ValueSignal -- one-way read binding (read from writable signal)
- ValueReadonlySignal -- one-way read binding (read from computed/readonly signal)
- ValueFn -- dynamic function evaluated on each draw
Example:
progress := state.NewSignal[float64](0.0)
bar := progressbar.New(
progressbar.ValueSignal(progress),
progressbar.ShowLabel(true),
)
progress.Set(0.75) // bar updates to 75%
Accessibility ¶
Progress bars are display-only widgets. They do not accept focus or handle input events. Screen readers should announce the current progress value via the accessibility tree.
Index ¶
- type DefaultPainter
- type Option
- func ColorSchemeOpt(cs ProgressBarColorScheme) 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 Height(h float32) Option
- func PainterOpt(p Painter) Option
- func Radius(r float32) Option
- func ShowLabel(show bool) 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 ProgressBarColorScheme
- type Widget
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) Draw(_ widget.Context, canvas widget.Canvas)
- func (w *Widget) Event(_ widget.Context, _ event.Event) 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) 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 simple progress bar -- useful for testing and as a base reference.
func (DefaultPainter) PaintProgressBar ¶
func (p DefaultPainter) PaintProgressBar(canvas widget.Canvas, ps PaintState)
PaintProgressBar renders a minimal progress bar with a gray track, blue fill, and optional centered label. If state.ProgressBarColorScheme is non-zero, its colors are used instead of built-in defaults.
type Option ¶
type Option func(*config)
Option configures a progress bar during construction.
func ColorSchemeOpt ¶
func ColorSchemeOpt(cs ProgressBarColorScheme) Option
ColorSchemeOpt sets the 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 PainterOpt ¶
PainterOpt sets the painter used to render the progress bar. Each design system provides its own painter. If not set, DefaultPainter is used.
func Radius ¶
Radius sets the corner radius for rounded bar ends. Default is 4. Set to 0 for square corners.
func ShowLabel ¶
ShowLabel enables or disables the percentage label overlay. When enabled, the label is drawn centered over the bar.
func Value ¶
Value sets the progress bar'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 progress bar'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 progress bar'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]
Bounds geometry.Rect // total widget bounds
BarHeight float32 // height of the bar in logical pixels
Radius float32 // corner radius for rounded ends
ShowLabel bool // whether to show percentage label
Label string // pre-formatted label text (empty if ShowLabel is false)
Disabled bool // widget is disabled
ProgressBarColorScheme ProgressBarColorScheme // theme-derived colors (zero = use defaults)
}
PaintState provides the current progress bar state to the painter.
type Painter ¶
type Painter interface {
PaintProgressBar(canvas widget.Canvas, state PaintState)
}
Painter draws the visual representation of a progress bar. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render the bar in its visual style.
If no Painter is set, the progress bar uses DefaultPainter.
type ProgressBarColorScheme ¶
type ProgressBarColorScheme struct {
Bar widget.Color // filled portion color
Track widget.Color // background track color
Label widget.Color // label text color
DisabledBar widget.Color // filled portion when disabled
DisabledTrack widget.Color // background track when disabled
}
ProgressBarColorScheme provides theme-derived colors for progress bar 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 linear progress bar showing a value between 0 and 1.
A progress bar is created with New using functional options:
bar := progressbar.New(
progressbar.Value(0.65),
progressbar.ShowLabel(true),
progressbar.Height(20),
)
Fluent styling methods may be chained after construction:
bar.Padding(8)
func New ¶
New creates a new progress bar Widget with the given options.
The returned widget is visible and enabled by default. It is not focusable because progress bars are display-only widgets.
func (*Widget) Event ¶
Event handles an input event. Progress bars are display-only and always return false (events are never consumed).
func (*Widget) Layout ¶
Layout calculates the progress bar'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 progress bar. Returns the widget for method chaining.
func (*Widget) SetValue ¶
SetValue updates the progress bar's static value. The value is clamped to [0, 1].
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the progress bar is removed from the widget tree. Implements widget.Lifecycle.
Source Files