LumaxForge
ZH EN

Ring Chart (RingChart)

This chapter explains what RingChart really means (it is not a donut pie), and aligns its SeriesData interpretation, RingChartSettings configuration, and Pro/base differences with runtime behavior.

1. What is RingChart? (very important)

In the current EasyChart implementation:

  • SerieType.RingChart renders multiple progress rings (one ring per data point)
  • each ring is a full 360° background ring + one progress arc
  • it is not a pie chart that splits the circle into multiple slices

If you want a donut pie chart that shows composition:

  • it is closer to SerieType.Pie + layout.innerRadius > 0
  • but you should choose based on intent:

    • - composition/proportion: use Pie - multi-metric progress/completion: use RingChart

2. Important note (Pro feature)

  • The renderer for SerieType.RingChart is registered by EasyChartProBootstrap.
  • Without Pro installed/enabled, this serie usually won't render.

3. Minimum viable setup (checklist)

  1. Add 1 Serie

    2. - type = RingChart - settings = RingChartSettings - seriesData has at least 1 point

  2. Each point has value > 0
Note: RingChart ignores points with value <= 0.

4. SeriesData field interpretation (runtime behavior)

RingChart mainly uses:

  • value: the raw progress value
  • name: ring name
  • useColor + color: ring color (per-point override)
  • id: stable identifier (for legend/hidden state; keep it stable)

4.1 Percent mode (default): value supports both 0~1 and 0~100

When RingChartSettings.valueMapping.mode = Percent (default):

  • value <= 0: the ring is filtered out
  • 0~1: treated as ratio (0.72 = 72%)
  • > 1: treated as percent (72 = 72%, runtime divides by 100)

Recommendation: standardize one convention within your team (all 0~1 or all 0~100) to avoid mistakes.

4.2 Range mode: map value to 0..1

When RingChartSettings.valueMapping.mode = Range:

  • It first determines the range min/max:

    • - autoRange=true: compute from values across all rings - autoRange=false: use minValue/maxValue

  • Then it maps to (value-min)/(max-min) and clamps to 0..1

4.3 Name fallback when name is empty

When SeriesData.name is empty, RingChart tries to fall back to labels:

  • If ChartData.CoordinateSystem == None: it won't use labels, and falls back to Ring {i}
  • Otherwise it prefers: Data.PolarAxes.angleAxis.labels[i]
  • Otherwise: labels from Cartesian/any Category axis labels[i]
  • Final fallback: Ring {i}

If you do not want to depend on PolarAxes configuration, fill SeriesData.name directly.

5. Inspector fields (RingChartSettings)

  • series[i].type = RingChart
  • series[i].settings: actual type is RingChartSettings

    • - layout: angles/radius/inner-outer ring/padding/center offset - valueMapping: Percent/Range mapping rules - hover: hover emphasis (Translate/Pull/Color/Stroke) - legend: RingChart legend settings (effective for pure Pie charts) - showBackground/backgroundAlpha/backgroundColor: background ring - cornerRadius: rounded cap - ringGapPx: gap between rings

5.1 layout (RingChartLayoutSettings)

Common fields:

  • startAngleDeg: start angle
  • clockwise: clockwise/counter-clockwise
  • angleRangeDeg: default 360; use for half-ring progress, etc.
  • outerRadius: outer radius (<=0 auto; 0~1 normalized; >1 pixels)
  • innerRadius: inner radius (0~1 normalized or pixels)
  • plot.padding: padding (avoid clipping hover/labels)
  • plot.centerOffset: center offset

5.2 hover (PieHoverSettings)

  • hover.enabled: enable
  • hover.explodeType:

    • - Translate: translate the whole ring - Pull: pull/stretch - Color: brighten - Stroke: stroke emphasis

  • hover.explodeDistance: translate/pull distance (pixels)

5.3 Background ring and spacing

  • showBackground: draw background ring
  • backgroundAlpha: background ring alpha (multiplied into final color alpha)
  • backgroundColor: background ring color (when alpha=0, it falls back to ring color)
  • ringGapPx: gap between rings
  • cornerRadius: rounded cap (limited by ring thickness)

6. Legend and hide interaction (shared HiddenPieSliceIds with Pie)

  • RingChart shares ChartInteractionState.HiddenPieSliceIds with Pie.
  • Hidden key for each ring: prefer SeriesData.id, otherwise use the index string.
  • Legend label source is affected by PieLegendSettings.source:

    • - RingSlice prefers polarAxes.angleAxis.labels.

7. Labels (SerieLabelSettings)

RingChart labels also use Serie.labelSettings:

  • show: whether to show
  • showName: whether to show name
  • decimalPlaces: decimals (note: this displays the raw value, not a percent text multiplied by 100)
  • position:

    • - Outside: outside label + leader line - Center: centered on the ring

6. Common pitfalls (by symptoms)

  • I thought it was a donut pie, but it looks wrong

    • - This is a multi-ring progress chart: each point is one progress ring

  • Progress is wrong (e.g. I set 75 but it is almost full)

    • - value>1 is treated as percent and divided by 100 - For 75%: use 0.75 or 75

  • Some rings are not visible

    • - Check whether value <= 0 is being filtered

  • Interaction/hidden state is unstable

    • - Ensure SeriesData.id is stable

8. Further reading

  • Pie (composition/proportion): 03_06-PieChart.md
  • Series data structure: 00_02-WorkflowAndLibrary.md