LumaxForge
ZH EN

Pie Chart (Pie)

easy-chart-lit · Manual

Back to Product Chapters

Pie Chart (Pie)

This chapter explains how Pie charts work in EasyChart: how data fields are interpreted, how layout/aggregation/legend/interactions take effect, and which behaviors have hidden prerequisites, mapped to Inspector fields.

1. Use cases

  • Showing proportions/composition
  • Emphasizing the share of each category in the whole

Not suitable for:

  • Too many categories (usually > 8–12 becomes hard to read)
  • Precise comparison of tiny differences (a bar chart is usually better)

2. Minimum viable setup (checklist)

  1. coordinateSystem: Pie does not rely on Cartesian/Polar coordinate systems (keep your Profile setting)
  2. Add 1 Serie:
    • type = Pie
    • settings = PieSettings
    • seriesData has at least 1 point
  3. Ensure each point has value > 0

Note: Pie currently ignores points with value <= 0.

3. Important limitations (runtime behavior)

  • Only the first visible Pie serie is drawn: the renderer iterates Data.Series, finds the first visible serie with type=Pie, draws it, then breaks.
  • Slice hidden state comes from ChartInteractionState.HiddenPieSliceIds, which is added/removed when clicking legend items.

4. SeriesData field interpretation (runtime behavior)

Pie mainly uses:

  • value: numeric value (weight) of the slice
  • name: slice name (recommended)
  • useColor + color: per-slice custom color (optional)
  • id: stable slice identifier (for hidden/interaction state; keep it stable)

4.1 Recommended pattern: explicit name + value

  • SeriesData.name = "Apple"
  • SeriesData.value = 12

4.2 Name fallback when name is empty

When SeriesData.name is empty, Pie may try to use labels, but with an important prerequisite:

  • If ChartData.CoordinateSystem == None (typically pure Pie / no coordinate system), runtime skips label fallback and uses only SeriesData.name.

When coordinate system is not None, the fallback order is:

  • Prefer Category axis labels that match Data.Cartesian.xAxisId
  • Otherwise, use labels from any Category axis
  • Final fallback: Slice {index}

Therefore: if you do not want to depend on axis configuration, fill SeriesData.name directly.

4.3 Color source

  • If useColor=true on the point: use SeriesData.color
  • Otherwise: use the built-in palette in order

5. Common settings (PieSettings)

Pie settings is PieSettings, mainly including:

  • layout: layout (angle/radius/gaps/center offset, etc.)
  • hover: hover interaction (explode)
  • aggregation: aggregation (TopN + Others)
  • legend: Pie-specific legend settings (replaces global legend only for “pure Pie chart” cases)

4.1 layout (PieLayoutSettings)

Common fields:

  • startAngleDeg: start angle (default -90 makes the first slice start at the top)
  • clockwise: clockwise/counter-clockwise
  • angleRangeDeg: angle range (default 360; use 180 for half-pie, etc.)
  • outerRadius: outer radius
    • <= 0: auto
    • 0~1: normalized by control size
    • > 1: pixels
  • innerRadius: inner radius (Pie usually 0; >0 creates a hole, but RingChart is recommended for ring/progress style)
  • innerRadiusColor: inner fill color
  • sliceGapPx: gap between slices (pixels)
  • sliceGapType: gap mode (Radial/Translate/Uniform)
  • cornerRadius: corner radius (pixels, limited by slice thickness)
  • plot.padding: padding (avoid clipping slices/outside labels)
  • plot.centerOffset: center offset

4.2 hover (PieHoverSettings)

  • hover.enabled: enable hover interaction
  • hover.explodeType:
    • Translate: translate the whole slice
    • Pull: pull out / stretch
    • Color: brighten
    • Stroke: stroke emphasis
  • hover.explodeDistance: translate/pull distance (pixels)

4.3 aggregation (PieAggregationSettings)

When there are many categories, you can merge small items into Others:

  • aggregation.enabled = true
  • keepTopN: keep top N, merge the rest
  • sortByValue: sort by value before taking TopN
  • othersName: name for Others
  • useOthersColor + othersColor: Others color

Note: aggregation only takes effect when keepTopN > 0 and slice count exceeds N.

6. Legend (PieLegendSettings) and “hide slice” interaction

When the chart is a “pure Pie chart” (only Pie/RingChart/Pie3D and no other types):

  • Legend prefers PieSettings.legend (or the legend on RingChartSettings/Pie3DSettings), instead of ChartData.legend.
  • Clicking a legend item toggles HiddenPieSliceIds:
    • normal slices: SeriesData.id (if empty, uses index string)
    • aggregated Others: always __ec_pie_others__

PieLegendSettings.source affects where legend items come from:

  • Slice: one entry per slice (default)
  • RingSlice: provides label source for RingChart/RingSlice scenarios (prefers PolarAxes.angleAxis.labels)
  • Series: one entry per serie (not slice-level)

7. Labels (SerieLabelSettings)

Pie labels are controlled by Serie.labelSettings:

  • show: whether to show
  • fontSize / color / decimalPlaces: font and value format
  • showName: whether to include slice name
  • position: Outside/Inside/Center
  • offset: offset

8. Common pitfalls (by symptoms)

  • Some slices are not visible

    • Check whether the point value is <= 0

  • Slice name is not what I expect

    • Recommended: fill SeriesData.name directly
    • If you rely on labels: ensure you have a Category axis with labels, and the order matches data point indices

  • Slice colors change each time / hard to control

    • For slices that need fixed colors: set useColor=true + color on the point

  • Hidden/interaction state is unstable

    • Ensure each point SeriesData.id is stable (do not regenerate ids on each refresh)

9. Next

  • Ring chart (RingChart): 03_07-RingChart.md