feat: add gradientArea property for LineChartBarData (#1925)

* feat: add `gradientArea` property for `LineChartBarData`

* test: add test for `gradientArea`

* docs: add documents for `gradientArea`

* Set the default value for `gradientArea` in `LineChartBarData`'s constructor and add docs for `LineChartGradientArea`

* updated CHANGELOG.md

Author: huanghui1998hhh

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 1.1.0
+* **FEATURE** (by @huanghui1998hhh) Add `gradientArea` property to `LineChartBarData` to allow you to control the scope of gradient effects, #1925
+
 ## 1.0.0
 <img width="600" alt="Image" src="https://github.com/user-attachments/assets/3d8b58f4-4ce7-489f-ba45-27ece063f57c" />
 

lib/src/chart/line_chart/line_chart_data.dart

@@ -184,6 +184,15 @@ class LineChartData extends AxisChartData with EquatableMixin {
       ];
 }
 
+enum LineChartGradientArea {
+  /// The gradient area will be around the line only, meaning
+  /// the gradient will exactly wrap around the curve.
+  rectAroundTheLine,
+
+  /// The entire chart area will be used as the gradient area for the curve.
+  wholeChart;
+}
+
 /// Holds data for drawing each individual line in the [LineChart]
 class LineChartBarData with EquatableMixin {
   /// [BarChart] draws some lines and overlaps them in the chart's view,
@@ -232,6 +241,7 @@ class LineChartBarData with EquatableMixin {
     this.show = true,
     Color? color,
     this.gradient,
+    this.gradientArea = LineChartGradientArea.rectAroundTheLine,
     this.barWidth = 2.0,
     this.isCurved = false,
     this.curveSmoothness = 0.35,
@@ -324,6 +334,11 @@ class LineChartBarData with EquatableMixin {
   /// It throws an exception if you provide both [color] and [gradient]
   final Gradient? gradient;
 
+  /// Only effective if [gradient] is provided.
+  ///
+  /// It will be used to determine the area of the gradient.
+  final LineChartGradientArea gradientArea;
+
   /// Determines thickness of drawing line.
   final double barWidth;
 
@@ -405,6 +420,7 @@ class LineChartBarData with EquatableMixin {
         dashArray: lerpIntList(a.dashArray, b.dashArray, t),
         color: Color.lerp(a.color, b.color, t),
         gradient: Gradient.lerp(a.gradient, b.gradient, t),
+        gradientArea: b.gradientArea,
         spots: lerpFlSpotList(a.spots, b.spots, t)!,
         showingIndicators: b.showingIndicators,
         shadow: Shadow.lerp(a.shadow, b.shadow, t)!,
@@ -420,6 +436,7 @@ class LineChartBarData with EquatableMixin {
     bool? show,
     Color? color,
     Gradient? gradient,
+    LineChartGradientArea? gradientArea,
     double? barWidth,
     bool? isCurved,
     double? curveSmoothness,
@@ -443,6 +460,7 @@ class LineChartBarData with EquatableMixin {
         show: show ?? this.show,
         color: color ?? this.color,
         gradient: gradient ?? this.gradient,
+        gradientArea: gradientArea ?? this.gradientArea,
         barWidth: barWidth ?? this.barWidth,
         isCurved: isCurved ?? this.isCurved,
         curveSmoothness: curveSmoothness ?? this.curveSmoothness,
@@ -470,6 +488,7 @@ class LineChartBarData with EquatableMixin {
         show,
         color,
         gradient,
+        gradientArea,
         barWidth,
         isCurved,
         curveSmoothness,

lib/src/chart/line_chart/line_chart_painter.dart

@@ -1056,7 +1056,9 @@ class LineChartPainter extends AxisChartPainter<LineChartData> {
       ..setColorOrGradient(
         barData.color,
         barData.gradient,
-        rectAroundTheLine,
+        barData.gradientArea == LineChartGradientArea.wholeChart
+            ? Offset.zero & viewSize
+            : rectAroundTheLine,
       )
       ..maskFilter = null
       ..strokeWidth = barData.barWidth

repo_files/documentations/line_chart.md

@@ -45,6 +45,7 @@ When you change the chart's state, it animates to the new state internally (usin
 |spots| list of [FlSpot](base_chart.md#FlSpot)'s x and y coordinates that the line go through it| []
 |color|color of the line|[Colors.redAccent]|
 |gradient| You can use any [Gradient](https://api.flutter.dev/flutter/dart-ui/Gradient-class.html) here. such as [LinearGradient](https://api.flutter.dev/flutter/painting/LinearGradient-class.html) or [RadialGradient](https://api.flutter.dev/flutter/painting/RadialGradient-class.html)|null|
+|gradientArea| determines the area where the gradient is applied |null|
 |barWidth| gets the stroke width of the line bar|2.0|
 |isCurved| curves the corners of the line on the spot's positions| false|
 |curveSmoothness| smoothness radius of the curve corners (works when isCurved is true) | 0.35|

test/chart/line_chart/line_chart_painter_test.dart

@@ -18,6 +18,7 @@ import '../data_pool.dart';
 import 'line_chart_painter_test.mocks.dart';
 
 @GenerateMocks([Canvas, CanvasWrapper, BuildContext, Utils, LineChartPainter])
+@GenerateNiceMocks([MockSpec<LinearGradient>()])
 void main() {
   group('paint()', () {
     test('test 1', () {
@@ -2172,14 +2173,13 @@ void main() {
         FlSpot(8, 9),
       ];
 
+      final mockLinearGradient = MockLinearGradient();
       final lineChartBarData1 = LineChartBarData(
         spots: barSpots1,
         barWidth: 80,
         isStrokeCapRound: true,
         isStepLineChart: true,
-        gradient: const LinearGradient(
-          colors: [Color(0xF0F0F0F0), Color(0x0100FF00)],
-        ),
+        gradient: mockLinearGradient,
         dashArray: [1, 2, 3],
       );
 
@@ -2199,6 +2199,11 @@ void main() {
       final mockCanvasWrapper = MockCanvasWrapper();
       when(mockCanvasWrapper.size).thenAnswer((realInvocation) => viewSize);
       when(mockCanvasWrapper.canvas).thenReturn(MockCanvas());
+      // just to provide a dummy Shader, don't care about its value
+      provideDummy<Shader>(
+        const LinearGradient(colors: [Color(0xF0F0F0F0), Color(0x0100FF00)])
+            .createShader(Rect.zero),
+      );
 
       final barPath = Path()
         ..moveTo(10, 10)
@@ -2222,6 +2227,29 @@ void main() {
       expect(paint.shader != null, true);
       expect(paint.maskFilter, null);
       expect(paint.strokeWidth, 80);
+
+      final createShaderWithRectAroundTheLine =
+          verify(mockLinearGradient.createShader(captureAny))..called(1);
+      expect(
+        createShaderWithRectAroundTheLine.captured.single,
+        const Rect.fromLTRB(10, 10, 80, 10),
+      );
+
+      lineChartPainter.drawBar(
+        mockCanvasWrapper,
+        barPath,
+        lineChartBarData1.copyWith(
+          gradientArea: LineChartGradientArea.wholeChart,
+        ),
+        holder,
+      );
+
+      final createShaderWithRectWholeChart =
+          verify(mockLinearGradient.createShader(captureAny))..called(1);
+      expect(
+        createShaderWithRectWholeChart.captured.single,
+        Offset.zero & viewSize,
+      );
     });
   });
 

test/chart/line_chart/line_chart_painter_test.mocks.dart

@@ -105,6 +105,18 @@ class _FakePath_9 extends _i1.SmartFake implements _i2.Path {
     : super(parent, parentInvocation);
 }
 
+class _FakeAlignmentGeometry_10 extends _i1.SmartFake
+    implements _i3.AlignmentGeometry {
+  _FakeAlignmentGeometry_10(Object parent, Invocation parentInvocation)
+    : super(parent, parentInvocation);
+}
+
+class _FakeLinearGradient_11 extends _i1.SmartFake
+    implements _i3.LinearGradient {
+  _FakeLinearGradient_11(Object parent, Invocation parentInvocation)
+    : super(parent, parentInvocation);
+}
+
 /// A class which mocks [Canvas].
 ///
 /// See the documentation for Mockito's code generation for more information.
@@ -1448,3 +1460,129 @@ class MockLineChartPainter extends _i1.Mock implements _i10.LineChartPainter {
           )
           as double);
 }
+
+/// A class which mocks [LinearGradient].
+///
+/// See the documentation for Mockito's code generation for more information.
+class MockLinearGradient extends _i1.Mock implements _i3.LinearGradient {
+  @override
+  _i3.AlignmentGeometry get begin =>
+      (super.noSuchMethod(
+            Invocation.getter(#begin),
+            returnValue: _FakeAlignmentGeometry_10(
+              this,
+              Invocation.getter(#begin),
+            ),
+            returnValueForMissingStub: _FakeAlignmentGeometry_10(
+              this,
+              Invocation.getter(#begin),
+            ),
+          )
+          as _i3.AlignmentGeometry);
+
+  @override
+  _i3.AlignmentGeometry get end =>
+      (super.noSuchMethod(
+            Invocation.getter(#end),
+            returnValue: _FakeAlignmentGeometry_10(
+              this,
+              Invocation.getter(#end),
+            ),
+            returnValueForMissingStub: _FakeAlignmentGeometry_10(
+              this,
+              Invocation.getter(#end),
+            ),
+          )
+          as _i3.AlignmentGeometry);
+
+  @override
+  _i2.TileMode get tileMode =>
+      (super.noSuchMethod(
+            Invocation.getter(#tileMode),
+            returnValue: _i2.TileMode.clamp,
+            returnValueForMissingStub: _i2.TileMode.clamp,
+          )
+          as _i2.TileMode);
+
+  @override
+  List<_i2.Color> get colors =>
+      (super.noSuchMethod(
+            Invocation.getter(#colors),
+            returnValue: <_i2.Color>[],
+            returnValueForMissingStub: <_i2.Color>[],
+          )
+          as List<_i2.Color>);
+
+  @override
+  _i2.Shader createShader(_i2.Rect? rect, {_i2.TextDirection? textDirection}) =>
+      (super.noSuchMethod(
+            Invocation.method(
+              #createShader,
+              [rect],
+              {#textDirection: textDirection},
+            ),
+            returnValue: _i9.dummyValue<_i2.Shader>(
+              this,
+              Invocation.method(
+                #createShader,
+                [rect],
+                {#textDirection: textDirection},
+              ),
+            ),
+            returnValueForMissingStub: _i9.dummyValue<_i2.Shader>(
+              this,
+              Invocation.method(
+                #createShader,
+                [rect],
+                {#textDirection: textDirection},
+              ),
+            ),
+          )
+          as _i2.Shader);
+
+  @override
+  _i3.LinearGradient scale(double? factor) =>
+      (super.noSuchMethod(
+            Invocation.method(#scale, [factor]),
+            returnValue: _FakeLinearGradient_11(
+              this,
+              Invocation.method(#scale, [factor]),
+            ),
+            returnValueForMissingStub: _FakeLinearGradient_11(
+              this,
+              Invocation.method(#scale, [factor]),
+            ),
+          )
+          as _i3.LinearGradient);
+
+  @override
+  _i3.Gradient? lerpFrom(_i3.Gradient? a, double? t) =>
+      (super.noSuchMethod(
+            Invocation.method(#lerpFrom, [a, t]),
+            returnValueForMissingStub: null,
+          )
+          as _i3.Gradient?);
+
+  @override
+  _i3.Gradient? lerpTo(_i3.Gradient? b, double? t) =>
+      (super.noSuchMethod(
+            Invocation.method(#lerpTo, [b, t]),
+            returnValueForMissingStub: null,
+          )
+          as _i3.Gradient?);
+
+  @override
+  _i3.LinearGradient withOpacity(double? opacity) =>
+      (super.noSuchMethod(
+            Invocation.method(#withOpacity, [opacity]),
+            returnValue: _FakeLinearGradient_11(
+              this,
+              Invocation.method(#withOpacity, [opacity]),
+            ),
+            returnValueForMissingStub: _FakeLinearGradient_11(
+              this,
+              Invocation.method(#withOpacity, [opacity]),
+            ),
+          )
+          as _i3.LinearGradient);
+}