gauges

Note: This project serves as a training exercise for myself in order to better understand the inner workings of Flutter and learn how to write custom Widgets, Elements and RenderObjects from scratch. As a result, the API might change heavily and I may not know about best practices or optimal solutions for many problems. So if you have any suggestions of improvement, please feel free to open an issue.

Getting started

To use this plugin, add [flutter_gauges] as a dependency in your pubspec.yaml file.

Usage

Radial gauge

The basic widget for radial gauges is the RadialGauge. Multiple axes can be added. E. g. this is a gauge with three axes:

This is the basic structure of a RadialGauge. See the following sections for more info on each of them.

RadialGauge(
  axes: [
    RadialGaugeAxis(
        segments: [
            RadialGaugeSegment(),
            RadialGaugeSegment(),
            // ...
        ],
        pointers: [
            RadialNeedlePointer(),
            RadialNeedlePointer(),
            // ...
        ],
        ticks: [
            RadialTicks(
                children: [
                    RadialTick(),
                    RadialTick(),
                ],
            ),
            RadialTick(),
            // ...
    ),
    RadialGaugeAxis(
    ),
  ],
)

Axes

An axes has a few important properties:

• min: The minimum value of this axis
• max: The maximum value of this axis
• minAngle: The angle in degrees min is mapped to
• maxAngle: The angle in degrees max is mapped to
• radius: The radius of the axes as a fraction of the RadialGauge's size
• width: The width of the axes as a fraction of the RadialGauge's size
• offset: The offset of the axes in respect to the middle of the RadialGauge
• color: The color of the axes (gradients are also available, see examples)

For more, take a look at the examples.

RadialGauge(
  axes: [
    RadialGaugeAxis(
      minValue: -100,
      maxValue: 100,
      minAngle: -150,
      maxAngle: 150,
      radius: 0.6,
      width: 0.2,
    ),
  ],
)

Segments

Each axes can consist of multiple segments (it is, in fact, a segment itself). Each of the segments has a properties similiar to the RadialGaugeAxis. The segments are listed in the segments property of an axes:

RadialGauge(
  axes: [
    RadialGaugeAxis(
      color: Colors.transparent,
      // ...
      segments: [
        RadialGaugeSegment(
          minValue: 0, 
          maxValue: 20, 
          minAngle: -150, 
          maxAngle: -130,
          color: Colors.red,
        ),
        RadialGaugeSegment(
          minValue: 20, 
          maxValue: 40, 
          minAngle: -120, 
          maxAngle: -90,
          color: Colors.orange,
        ),
          // ...
      ],
    ),
  ],
)

Ticks

Each axes can have multiple ticks of type RadialTick. They are listed in the ticks property. There are multiple possibilities to create ticks.

• Interval: Set the interval to the desired value. The ticks are displayed on every integer multiple of interval.
• Ticks in between: Set ticksInBetween to the desired number of ticks in between the parent ticks or the axes limits.
• Custom values: Set values to the desired values you want the ticks to appear at.
• Custom builder: Set valuesBuilder and/or anglesBuilder to a custom function calculating the values and/or angles at which the ticks should be displayed.

Every RadialTick can have RadialTicks as children, which is especially useful when setting the ticksInBetween on a children tick.

RadialGaugeAxis(
  // ...
  color: Colors.transparent,
  ticks: [
    RadialTicks(
        interval: 20,
        alignment: RadialTickAxisAlignment.inside,
        color: Colors.blue,
        length: 0.2,
        children: [
          RadialTicks(
              ticksInBetween: 5,
              length: 0.1,
              color: Colors.grey[500]),
        ])
  ],
)

Pointer

Each axis can have multiple pointers. Currently, there is only one type of pointer available, the RadialNeedlePointer with the following properties:

• value: The value the pointer is pointing to
• ticknessStart: The thickness of the pointer at the start of the pointer (in the middle of the axis)
• ticknessEnd: The thickness of the pointer at the end of the pointer
• length: The length of the pointer in fractions of the axis.
• knobRadiusAboslute: The radius of the pointer's knob in absolute pixels.
• color/gradient: The color/gradient filling the pointer.

The following code results in the knob shown above. For more, take a look at the examples.

RadialGaugeAxis(
    pointers: [
        RadialNeedlePointer(
            value: _pointerValue,
            thicknessStart: 20,
            thicknessEnd: 0,
            length: 0.6,
            knobRadiusAbsolute: 10,
            gradient: LinearGradient(...),
        )
    ],
)

Linear gauge

Not available yet

Centered Text

Centered text is actually a centered child widget. This was quickly done, but it is functional. See the child property usage in the RadialGauge below. Also, there is an example in the example application.

int _value = 33;
String _valueText = 'Social';
RadialGauge(
          child: Center(
              child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text(
                33.toString(),
                textAlign: TextAlign.center,
                style: TextStyle(color: Colors.purple, fontSize: 40.0),
              ),
              if (_valueText != null)
                Text(_valueText!,
                    style: TextStyle(color: Colors.purple, fontSize: 20.0)),
            ],
          )),
          axes: [
            RadialGaugeAxis(
              rotation: 180, // starts at the bottom
              minValue: 0,
              maxValue: ((_value + 1) / 100) * 360,
              minAngle: 0,
              maxAngle: ((_value + 1) / 100) * 360,
              radius: 0.6,
              color: Colors.transparent,
              ticks: [
                RadialTicks(
                  interval: 5,
                  alignment: RadialTickAxisAlignment.inside,
                  color: Colors.purple,
                  length: 0.1,
                ),
              ],
            ),
            RadialGaugeAxis(
              rotation: 180,
              minValue: (((_value + 1) / 100) * 360) + 2,
              maxValue: 358,
              minAngle: (((_value + 1) / 100) * 360) + 2,
              maxAngle: 358,
              radius: 0.6,
              color: Colors.transparent,
              ticks: [
                RadialTicks(
                  interval: 5,
                  alignment: RadialTickAxisAlignment.inside,
                  color: Colors.grey,
                  length: 0.1,
                ),
              ],
            )
          ],
        )

Maintainers

Julian Aßmann - Tommy L. Cox