200 lines
4.6 KiB
Markdown
200 lines
4.6 KiB
Markdown
# Tooltip, Trackball & Crosshair
|
|
|
|
## Table of Contents
|
|
- [Tooltip](#tooltip)
|
|
- [Tooltip Appearance](#tooltip-appearance)
|
|
- [Tooltip Format](#tooltip-format)
|
|
- [Shared Tooltip](#shared-tooltip)
|
|
- [Custom Tooltip Template](#custom-tooltip-template)
|
|
- [Trackball](#trackball)
|
|
- [Crosshair](#crosshair)
|
|
|
|
---
|
|
|
|
## Tooltip
|
|
|
|
Tooltip shows data values when the user taps a data point. Initialize `TooltipBehavior` in `initState` — avoid creating it inline in `build` to prevent recreation on every rebuild.
|
|
|
|
```dart
|
|
late TooltipBehavior _tooltip;
|
|
|
|
@override
|
|
void initState() {
|
|
_tooltip = TooltipBehavior(enable: true);
|
|
super.initState();
|
|
}
|
|
|
|
@override
|
|
Widget build(BuildContext context) {
|
|
return SfCartesianChart(
|
|
tooltipBehavior: _tooltip,
|
|
series: <CartesianSeries>[
|
|
LineSeries<ChartData, String>(
|
|
enableTooltip: true,
|
|
dataSource: chartData,
|
|
xValueMapper: (d, _) => d.x,
|
|
yValueMapper: (d, _) => d.y,
|
|
),
|
|
],
|
|
);
|
|
}
|
|
```
|
|
|
|
> `TooltipBehavior(enable: true)` enables tooltip globally for the chart. `enableTooltip: true` on a series additionally opts that series in. Both must be set for the tooltip to show.
|
|
|
|
---
|
|
|
|
## Tooltip Appearance
|
|
|
|
```dart
|
|
TooltipBehavior(
|
|
enable: true,
|
|
color: Colors.black87,
|
|
borderColor: Colors.white,
|
|
borderWidth: 1,
|
|
textStyle: const TextStyle(color: Colors.white, fontSize: 12),
|
|
opacity: 0.9,
|
|
duration: 4000,
|
|
animationDuration: 300,
|
|
elevation: 4,
|
|
canShowMarker: true,
|
|
shouldAlwaysShow: false,
|
|
header: '',
|
|
shadowColor: Colors.grey,
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Tooltip Format
|
|
|
|
Use `format` to customize the tooltip text using placeholders:
|
|
|
|
```dart
|
|
TooltipBehavior(
|
|
enable: true,
|
|
format: 'point.x : point.y USD',
|
|
)
|
|
```
|
|
|
|
**Examples:**
|
|
- `'point.x — point.y'` → `Jan — 35`
|
|
- `'series.name\nX: point.x\nY: point.y'` → multi-line tooltip
|
|
- `'\$point.y'` → `$35`
|
|
|
|
---
|
|
|
|
## Shared Tooltip
|
|
|
|
Show one tooltip that displays values for all series at the same x position simultaneously:
|
|
|
|
```dart
|
|
TooltipBehavior(
|
|
enable: true,
|
|
shared: true,
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Custom Tooltip Template
|
|
|
|
Replace the default tooltip with a completely custom Flutter widget:
|
|
|
|
```dart
|
|
TooltipBehavior(
|
|
enable: true,
|
|
builder: (dynamic data, dynamic point, dynamic series, int pointIndex, int seriesIndex) {
|
|
final ChartData chartPoint = data as ChartData;
|
|
return Container(
|
|
padding: const EdgeInsets.all(8),
|
|
decoration: BoxDecoration(
|
|
color: Colors.black87,
|
|
borderRadius: BorderRadius.circular(6),
|
|
),
|
|
child: Text(
|
|
'${chartPoint.x}: \$${chartPoint.y}',
|
|
style: const TextStyle(color: Colors.white, fontSize: 12),
|
|
),
|
|
);
|
|
},
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Trackball
|
|
|
|
The trackball displays a vertical line that snaps to the nearest data point as the user drags across the chart. It's ideal for comparing multiple series at the same x position.
|
|
|
|
```dart
|
|
late TrackballBehavior _trackball;
|
|
|
|
@override
|
|
void initState() {
|
|
_trackball = TrackballBehavior(
|
|
enable: true,
|
|
activationMode: ActivationMode.singleTap,
|
|
// Options: singleTap | doubleTap | longPress
|
|
tooltipSettings: const InteractiveTooltip(
|
|
enable: true,
|
|
color: Colors.black,
|
|
textStyle: TextStyle(color: Colors.white),
|
|
),
|
|
lineType: TrackballLineType.vertical,
|
|
// Options: vertical | none
|
|
lineColor: Colors.grey,
|
|
lineWidth: 1,
|
|
lineDashArray: <double>[5, 5],
|
|
markerSettings: const TrackballMarkerSettings(
|
|
markerVisibility: TrackballVisibilityMode.visible,
|
|
height: 10,
|
|
width: 10,
|
|
),
|
|
tooltipDisplayMode: TrackballDisplayMode.groupAllPoints,
|
|
// Options: floatAllPoints | groupAllPoints | nearestPoint | none
|
|
);
|
|
super.initState();
|
|
}
|
|
|
|
trackballBehavior: _trackball,
|
|
```
|
|
|
|
---
|
|
|
|
## Crosshair
|
|
|
|
The crosshair draws horizontal and vertical lines at the tapped/hovered position, with axis labels showing the exact value at that coordinate.
|
|
|
|
```dart
|
|
late CrosshairBehavior _crosshair;
|
|
|
|
@override
|
|
void initState() {
|
|
_crosshair = CrosshairBehavior(
|
|
enable: true,
|
|
activationMode: ActivationMode.singleTap,
|
|
lineType: CrosshairLineType.both,
|
|
// Options: horizontal | vertical | both | none
|
|
lineColor: Colors.grey,
|
|
lineWidth: 1,
|
|
lineDashArray: <double>[5, 5],
|
|
shouldAlwaysShow: false,
|
|
);
|
|
super.initState();
|
|
}
|
|
|
|
crosshairBehavior: _crosshair,
|
|
```
|
|
|
|
---
|
|
|
|
## Choosing Between Tooltip, Trackball, and Crosshair
|
|
|
|
| Need | Use |
|
|
|------|-----|
|
|
| Show value on tap of a single point | `TooltipBehavior` |
|
|
| Compare all series values at an x position | `TrackballBehavior` |
|
|
| Show exact x/y coordinates at cursor/finger | `CrosshairBehavior` |
|
|
| Show a custom overlay widget | `TooltipBehavior` with `builder` |
|