chartificial library
Cartesian charts built on Flutter's two-dimensional viewport: scrollable time series with lazy data loading, widget-based axis labels, value-space color scales, and pluggable rendering layers.
Classes
- AutoAxisRange
- Derives the range from every point currently loaded, plus padding.
- AutoAxisTicks
- AutoTimeAxisTicks
- AxisLabelConfig
- Axis label band configuration.
- AxisRange
- How an axis determines its value range when it fits the viewport (non-scrollable axes; the y axis always).
- AxisRangeContext
- Everything a range policy may consult for the current frame.
- AxisResolution
- How many pixels one unit of the axis occupies — this is what decides whether the axis scrolls.
- AxisScale
- Linearizes a typed axis domain into a monotonic scalar (double) space.
- AxisTickContext
- Everything a label builder gets to know about one tick.
- AxisTicks
- A tick-generation strategy for an axis.
- BandsColorScale
- BarBackground
- Passive bar painted behind the main bar — a full-scale track that shows how much of the range the value fills.
- BarPoint
- One bar. Stored as a ChartPoint whose y is toY, so trackball snapping, gap handling, and x/y extent tracking work unchanged.
- BarSeries
- Bars anchored at each data point's x value.
- BarStackSegment
- One colored slice of a stacked bar.
- BarStyle
- Visual style of a bar; series-level default, overridable per BarPoint.
- BarWidth
- Bar thickness — either fixed in pixels, or proportional to the x domain (scaling with ResolvedAxis.pixelsPerScalar, so bars keep their proportion while scrolling).
- ChartAxis
- Base configuration shared by all cartesian axes.
- ChartColorScale
- Maps series stroke color to the values being drawn (e.g. AQI good/medium/poor bands).
- ChartDecoration
- A pluggable canvas layer of the chart.
- ChartHitInfo
- What a tap/long-press/hover landed on.
- Chartificial
- A cartesian chart on a two-dimensional viewport. Line series are built in; custom series plug in by subclassing ChartSeries.
- ChartificialController
- Owns chart data and scroll-domain state.
- ChartificialTheme
- Visual defaults for chart chrome.
- ChartLoader
- Lazy-loading configuration: callbacks per direction plus the prefetch margin. Requires a scrollable x axis.
- ChartLoadRequest
- A request for more data, issued when the user scrolls near the edge of what is loaded.
- ChartPaintContext
- Everything a ChartDecoration or series painter needs to draw a frame.
- ChartPoint
- A single data point.
- ChartPrefetch
- When to trigger a load, measured in scrollable pixels between the scroll position and the loaded edge.
- ChartSeries
- A pluggable series of the chart.
- ChartVisibleRange
- The x-domain range currently visible in the plot area.
- ColorBand
-
A hard-edged color band in value space:
[from, to)renders as color. - ColorStop
- A gradient stop in value space (y-axis domain values, not fractions).
- CountAxisTicks
- DateTimeAxis
- A time axis whose domain is milliseconds since the Unix epoch.
- DecadeAxisTicks
- EdgeCrossing
- Where a series polyline crosses a vertical line (e.g. a plot edge).
- FitAxisResolution
- FixedAxisRange
- A range pinned to constant bounds, ignoring the data entirely.
- GradientSpec
- Ascending value/color arrays ready to become a gradient.
- GridDecoration
- The standard tick-aligned grid.
- GridLineStyle
- Styling of one family of grid lines.
- IntervalAxisTicks
- LinearScale
- Identity scale used by numeric and date-time axes.
- LineSeries
- Configuration of one line series.
- LineSeriesFill
-
Fills the area between a LineSeries and the plot bottom. Provide a solid
color or a gradient (mapped over the series' below-fill rect — see
belowFillRect). - LogarithmicAxis
- A logarithmic axis, for data spanning several orders of magnitude.
- LogScale
- Logarithmic scale: scalar = log_base(value).
- NumericAxis
- A linear axis over plain numbers.
- PerUnitAxisResolution
- PixelBarWidth
- A fixed on-screen thickness in logical pixels.
- PixelIntervalAxisTicks
- PointMarker
- Marker drawn on each data point of a series.
- RangePadding
- Headroom applied around a derived range, expressed in scalar space.
- ResolvedAxes
- The pair of resolved axes for a frame, as exposed to paint-time consumers and hit testing.
- ResolvedAxis
- The per-frame transform between an axis' scalar space and viewport pixels.
- ResolvedTicks
- An immutable, index-addressable tick sequence.
- ScalarRange
-
A closed range in scalar space (the linearized coordinate space of an
axis — see
AxisScale). - SeriesRenderSnapshot
- A series' paint-ready data for the current frame.
- SnapContext
-
Everything a
ChartSeries.snapimplementation may consult for one query. - SnappedPoint
- A data point matched to a touch position.
- StopsColorScale
- TickResolveContext
- Everything a tick strategy may need to resolve into concrete ticks.
- TrackballBehavior
- Trackball configuration: a tracker line that snaps to the nearest data point with a builder-based tooltip.
- TrackballDetails
- A live trackball position with its snapped points.
- VisibleAxisRange
- Derives the range from the data inside the visible window, so the axis rescales while scrolling instead of growing monotonically with everything ever loaded.
- XSpanBarWidth
- A thickness expressed in x-domain units.
Enums
- AxisAnchor
- Which end of the data the chart anchors to.
- AxisSide
-
Which side of the plot an axis' label band occupies. Only the y-axis
honors this today (
leftdefault,right= opposed). - ChartLayerPosition
- Whether a decoration paints under or over the series layer (both are always under the label widgets and trackball).
- GapPolicy
-
What to do at gap points (
ChartPoint(y: null)). - LineCurve
- How a line series connects its points.
- LoadDirection
- Which end of the data a load request targets.
- TrackballActivation
- Gesture that shows the trackball.
Functions
-
addCardinal(
Path path, List< Offset> points, {required bool continueFrom, double smoothness = 0.35}) → void -
Appends a cubic "cardinal spline" through
pointsontopath. -
addMonotoneHalfX(
Path path, List< Offset> points, {required bool continueFrom}) → void -
Appends a "monotone half-x" cubic curve through
pointsontopath. -
barClusterOffset(
{required int slot, required int count, required double barWidthPx, double spacingPx = 2}) → double -
BarSeries.xOffsetPx for bar
slotofcountside-by-side series:(slot - (count - 1) / 2) * (barWidthPx + spacingPx). -
belowFillRect(
List< Offset> points, double baseline) → Rect -
The gradient shader rect for a below-line fill: the series' left-most x, its
top-most point (smallest dy), its right-most x, down to
baseline. A top→bottom gradient therefore anchors at the highest data point and fades to the plot bottom.pointsmust be non-empty. -
boundsOf(
List< Offset> points) → Rect -
Bounding box of
points:Rect.fromLTRB(leftmostX, topmostY, rightmostX, bottommostY). Non-empty. -
cardinalTangent(
List< Offset> points, int i, double smoothness) → Offset -
The cardinal-spline tangent at
points[i]:((points[i+1] - points[i-1]) / 2) * smoothness, zero at the first point, with the last point clampingnext = current. See addCardinal. -
dashPath(
Path source, List< double> pattern) → Path -
A dashed copy of
source: walk each contour from its origin, alternating draw/skip runs whose lengths cycle throughpattern(starting on a draw run).patternempty ⇒sourcereturned unchanged. -
effectiveSegments(
List< Offset?> polyline, {GapPolicy gapPolicy = GapPolicy.break_}) → List<(Offset, Offset)> - The drawable segments of a pixel polyline with nulls as gaps, honoring the series' GapPolicy (GapPolicy.skip bridges across gaps exactly like the painter does).
-
formatCompactNumber(
double value) → String - Compact default number formatting: trims trailing zeros, abbreviates thousands/millions (1.5k, 2M).
-
niceStepAtLeast(
double rawStep) → double -
Smallest "nice" step (1, 2, or 5 × 10ⁿ) that is >=
rawStep. -
verticalLineCrossings(
List< (Offset, Offset)> segments, double edgeX) → List<EdgeCrossing> -
Crossings of
segmentswith the vertical linex = edgeX, in order.
Typedefs
- AxisLabelBuilder = Widget Function(BuildContext context, AxisTickContext tick)
- Builds the widget shown at an axis tick. Labels are real widgets managed by the chart's two-dimensional viewport: they keep state and are recycled (not rebuilt) while scrolling.
-
ChartLoadCallback
= Future<
bool> Function(ChartLoadRequest request) -
Fetches a page and feeds it into the controller
(
prependPoints/appendPoints), then returns whether more data exists in that direction. Returning false latches the direction as exhausted (seeChartificialController.resetLoader). Returning true without having added any points is also treated as exhausted, to prevent request loops. - MarkerPainter = void Function(Canvas canvas, Offset center, ChartPoint point, ResolvedAxes axes)
-
Paints a marker at a data point.
centeris the point's pixel position. - TrackballLinePainter = void Function(ChartPaintContext context, TrackballDetails details)
- Custom painter for the tracker line/markers layer.
- TrackballTooltipBuilder = Widget Function(BuildContext context, TrackballDetails details)
- Builds the tooltip widget shown while the trackball is active. The tooltip is a real widget (lives in the viewport's tooltip lane, above the labels) and is rebuilt only while the trackball moves.