Documentation
¶
Overview ¶
Package linechart provides a real-time line chart widget for visualizing time-series data such as CPU usage, memory consumption, or network throughput.
Construction uses functional options for immutable configuration:
chart := linechart.New(
linechart.MaxPoints(60),
linechart.YRange(0, 100),
linechart.ShowGrid(true),
linechart.ShowLabels(true),
)
Data Management ¶
Data is organized into named series, each with its own color and rolling window of data points:
chart.AddSeries("CPU", cpuColor)
chart.PushValue("CPU", 45.2) // adds point, shifts oldest if at MaxPoints
Multiple series can be displayed simultaneously with different colors. [PushValue] is safe to call from any goroutine.
Visual Style ¶
The visual rendering is provided by a Painter implementation. Each design system (Material 3, Fluent, Cupertino) can supply its own painter to render charts in the appropriate visual style.
If no painter is set, DefaultPainter is used, which draws a minimal chart suitable for testing and prototyping.
Signal Binding ¶
Chart data can be bound to reactive signals from the state package. When the signal value changes, the chart automatically reflects the new data:
seriesSig := state.NewSignal([]linechart.Series{...})
chart := linechart.New(
linechart.SeriesSignal(seriesSig),
)
Retained Mode ¶
The chart calls widget.WidgetBase.SetNeedsRedraw when data changes via Widget.PushValue or Widget.AddSeries, enabling efficient retained-mode rendering.
Index ¶
- type DataPoint
- type DefaultPainter
- type Option
- func BackgroundColor(color widget.Color) Option
- func GridColor(color widget.Color) Option
- func MaxPoints(n int) Option
- func PainterOpt(p Painter) Option
- func SeriesData(s []Series) Option
- func SeriesFn(fn func() []Series) Option
- func SeriesReadonlySignal(sig state.ReadonlySignal[[]Series]) Option
- func SeriesSignal(sig state.Signal[[]Series]) Option
- func ShowGrid(v bool) Option
- func ShowLabels(v bool) Option
- func YRange(yMin, yMax float64) Option
- type PaintState
- type Painter
- type Series
- type Widget
- func (w *Widget) AddSeries(label string, color widget.Color)
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) ClearSeries(label string)
- 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) PushValue(label string, value float64)
- func (w *Widget) SeriesCount() int
- func (w *Widget) Unmount()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DataPoint ¶
type DataPoint struct {
Value float64
}
DataPoint represents a single data value in a series.
type DefaultPainter ¶
type DefaultPainter struct{}
DefaultPainter provides a minimal fallback painter with no design system styling. It draws background, grid lines, Y-axis labels, and line segments for each series.
func (DefaultPainter) PaintChart ¶
func (p DefaultPainter) PaintChart(canvas widget.Canvas, bounds geometry.Rect, cs PaintState)
PaintChart renders the chart with background, optional grid, optional labels, and line segments for each data series.
type Option ¶
type Option func(*config)
Option configures a line chart during construction.
func BackgroundColor ¶
BackgroundColor sets the chart background fill color.
func MaxPoints ¶
MaxPoints sets the rolling window size (number of data points displayed). Default is 60.
func PainterOpt ¶
PainterOpt sets the painter used to render the chart. Each design system provides its own painter. If not set, DefaultPainter is used.
func SeriesData ¶
SeriesData sets the initial static series data.
func SeriesFn ¶
SeriesFn sets a dynamic function that returns the current series data. When set, this takes precedence over the static data but not over a signal set via SeriesSignal.
func SeriesReadonlySignal ¶
func SeriesReadonlySignal(sig state.ReadonlySignal[[]Series]) Option
SeriesReadonlySignal binds the chart's series data to a read-only signal. This is useful for computed signals. When set, this takes highest precedence.
func SeriesSignal ¶
SeriesSignal binds the chart's series data to a reactive signal. This is a TWO-WAY binding: the widget reads series from the signal, and when PushValue modifies series, the signal is updated.
func ShowLabels ¶
ShowLabels enables or disables Y axis labels. Default is false.
type PaintState ¶
type PaintState struct {
Series []Series
MaxPoints int
YMin float64
YMax float64
ShowGrid bool
ShowLabels bool
GridColor widget.Color
Background widget.Color
}
PaintState holds the read-only snapshot passed to the painter.
type Painter ¶
type Painter interface {
PaintChart(canvas widget.Canvas, bounds geometry.Rect, state PaintState)
}
Painter renders the chart visuals. Each design system (Material 3, Fluent, Cupertino) provides its own Painter implementation to render the chart in its visual style.
If no Painter is set, DefaultPainter is used.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget implements a real-time line chart for visualizing time-series data.
A line chart is created with New using functional options:
chart := linechart.New(
linechart.MaxPoints(60),
linechart.YRange(0, 100),
linechart.ShowGrid(true),
)
Data is pushed with Widget.AddSeries and Widget.PushValue, which are safe to call from any goroutine.
func New ¶
New creates a new line chart Widget with the given options.
The returned widget is visible and enabled by default. The default Y range is [0, 100] with a rolling window of 60 points.
func (*Widget) AddSeries ¶
AddSeries adds a named data series with the given color. If a series with the same label already exists, this is a no-op. Safe to call from any goroutine.
func (*Widget) ClearSeries ¶
ClearSeries removes all data points from the named series. Safe to call from any goroutine.
func (*Widget) Event ¶
Event handles an input event and returns true if consumed. LineChart is a display-only widget and does not consume events.
func (*Widget) Mount ¶
Mount creates signal bindings for push-based invalidation. Implements widget.Lifecycle.
func (*Widget) Padding ¶
Padding sets the padding around the chart area. Returns the widget for method chaining.
func (*Widget) PushValue ¶
PushValue appends a data point to the named series. If the series has reached MaxPoints, the oldest point is removed (rolling window). Safe to call from any goroutine.
func (*Widget) SeriesCount ¶
SeriesCount returns the number of series. Safe to call from any goroutine.
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the chart is removed from the widget tree. Implements widget.Lifecycle.
Source Files