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
   • 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 01 and 0100

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 01 or all 0100) 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