Documentation
¶
Overview ¶
Package badge provides a small notification badge widget that displays a count or a status dot.
A badge is typically overlaid on another widget (an icon, an avatar, a tab) to draw attention to unread items, pending notifications, or status. Because gogpu/ui favors composition, the badge itself is a self-contained leaf widget: position it over another widget using a stacking container rather than attaching it directly.
Construction uses functional options for immutable configuration, while fluent methods handle mutable styling:
b := badge.New(
badge.Count(5),
badge.Max(99),
).Padding(2)
Modes ¶
A badge renders in one of two modes:
- Count mode (default): displays a number inside a pill shape. A single digit renders as a circle; multiple digits widen into a pill. Counts greater than Max are shown as "N+" (for example "99+").
- Dot mode (enabled via Dot): displays a small filled circle with no text, used as a lightweight "has updates" indicator.
Visibility ¶
In count mode, a badge with a non-positive count is hidden (it reports a zero size and draws nothing) unless ShowZero is set. Dot badges are always visible.
Visual Style ¶
The visual rendering is provided by a Painter implementation. Each design system (Material 3, Fluent, Cupertino) may supply its own painter to render badges in the appropriate visual style.
If no painter is set, DefaultPainter is used, which draws a minimal badge suitable for testing and prototyping.
Signal Binding ¶
Badge properties can be bound to reactive signals from the state package. When a signal value changes, the badge automatically reflects the new state.
- CountSignal / CountReadonlySignal -- one-way read binding for the count
- CountFn -- dynamic function evaluated on each draw
- DisabledSignal / DisabledReadonlySignal -- one-way read binding for disabled state
Example:
unread := state.NewSignal[int](0) b := badge.New(badge.CountSignal(unread)) unread.Set(3) // badge updates to show "3"
Accessibility ¶
Badges are display-only widgets. They do not accept focus or handle input events. Screen readers should announce the badge's meaning via the accessibility tree of the widget the badge annotates.
Index ¶
- type BadgeColorScheme
- type DefaultPainter
- type Option
- func ColorSchemeOpt(cs BadgeColorScheme) Option
- func Count(n int) Option
- func CountFn(fn func() int) Option
- func CountReadonlySignal(sig state.ReadonlySignal[int]) Option
- func CountSignal(sig state.Signal[int]) 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 Dot(enabled bool) Option
- func Max(n int) Option
- func PainterOpt(p Painter) Option
- func ShowZero(show bool) Option
- type PaintState
- type Painter
- type Widget
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) Count() int
- func (w *Widget) Draw(_ widget.Context, canvas widget.Canvas)
- func (w *Widget) Event(_ widget.Context, _ event.Event) bool
- func (w *Widget) IsHidden() 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) SetCount(n int)
- func (w *Widget) Unmount()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BadgeColorScheme ¶
type BadgeColorScheme struct {
Background widget.Color // pill/dot fill color
Label widget.Color // count text color
DisabledBackground widget.Color // fill color when disabled
DisabledLabel widget.Color // text color when disabled
}
BadgeColorScheme provides theme-derived colors for badge 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 red pill (or dot) with a centered count label -- useful for testing and as a base reference.
func (DefaultPainter) PaintBadge ¶
func (p DefaultPainter) PaintBadge(canvas widget.Canvas, ps PaintState)
PaintBadge renders the badge. In dot mode it draws a small filled circle. In count mode it draws a pill (a rounded rectangle whose radius is half its height) with the count label centered inside.
If state.ColorScheme is non-zero, its colors are used instead of the built-in defaults.
type Option ¶
type Option func(*config)
Option configures a badge during construction.
func ColorSchemeOpt ¶
func ColorSchemeOpt(cs BadgeColorScheme) Option
ColorSchemeOpt sets the color scheme for painting. This overrides the painter's built-in defaults.
func CountFn ¶
CountFn sets a dynamic count function that is evaluated on each draw. When set, this takes precedence over the static count but not over a signal set via CountSignal or CountReadonlySignal.
func CountReadonlySignal ¶
func CountReadonlySignal(sig state.ReadonlySignal[int]) Option
CountReadonlySignal binds the badge's count to a read-only signal. This is useful for computed signals created via state.NewComputed. When set, this takes highest precedence over all other count sources.
func CountSignal ¶
CountSignal binds the badge's count 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 CountFn and Count but not over CountReadonlySignal.
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 Dot ¶
Dot enables dot mode, rendering a small filled circle with no text. In dot mode the count is ignored and the badge is always visible.
func Max ¶
Max sets the count threshold above which the badge renders "N+". For example, with Max(99) a count of 100 displays as "99+". The default is 99. Values <= 0 are ignored.
func PainterOpt ¶
PainterOpt sets the painter used to render the badge. Each design system provides its own painter. If not set, DefaultPainter is used.
type PaintState ¶
type PaintState struct {
Bounds geometry.Rect // total widget bounds (excludes outer padding)
Dot bool // true for dot mode (no label)
Label string // pre-formatted count label (empty in dot mode)
Disabled bool // widget is disabled
ColorScheme BadgeColorScheme // theme-derived colors (zero = use defaults)
}
PaintState provides the current badge state to the painter.
type Painter ¶
type Painter interface {
PaintBadge(canvas widget.Canvas, state PaintState)
}
Painter draws the visual representation of a badge. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render the badge in its visual style.
If no Painter is set, the badge uses DefaultPainter.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a small notification badge displaying a count or a dot.
A badge is created with New using functional options:
b := badge.New(
badge.Count(5),
badge.Max(99),
)
Fluent styling methods may be chained after construction:
b.Padding(2)
func New ¶
New creates a new badge Widget with the given options.
The returned widget is visible and enabled by default. It is not focusable because badges are display-only widgets.
func (*Widget) Event ¶
Event handles an input event. Badges are display-only and always return false (events are never consumed).
func (*Widget) IsHidden ¶
IsHidden reports whether the badge currently renders nothing. A count badge is hidden when its count is non-positive and ShowZero is not set. Dot badges are never hidden.
func (*Widget) Mount ¶
Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.
The count signal binding deduplicates notifications: if the signal fires with the same count that was last drawn, the widget is not marked dirty.
func (*Widget) Padding ¶
Padding sets the outer padding around the badge content. Returns the widget for method chaining.
func (*Widget) SetCount ¶
SetCount updates the badge's static count. Negative values are treated as zero. The widget is marked for redraw when the value changes.
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the badge is removed from the widget tree. Implements widget.Lifecycle.
Source Files