Package limn.components.chart

Class DonutChart

java.lang.Object
limn.scene.Widget<DonutChart>
limn.components.chart.Chart<DonutChart>
limn.components.chart.DonutChart
public final class DonutChart extends Chart<DonutChart>
A ring of slices, or a pie, with setInnerRadius(float) at 0.

The chart draws its first visible series as the ring: one slice per value, named by the chart's labels and colored by palette slot, because in a donut it is the slices that are the categories. A second series is left undrawn rather than drawn as a second ring; two rings on one chart is a chart nobody can read.

The hole is a real widget slot. setCenter(Widget) puts a widget in the middle (a total, an icon, a button), laid out in the largest square that fits inside the ring, and it takes input like any other widget: a button in the hole is clickable, and the chart's own hover stops at the ring.

Negative values are ignored: they have no share of a whole. Hiding a slice from the legend animates it closed and gives its angle back to the others, because the shares are recomputed from what is still shown. 


 DonutChart chart = new DonutChart();
 chart.setLabels("Direct", "Search", "Social", "Mail");
 chart.addSeries(ChartSeries.of("Traffic", 42, 31, 18, 9));
 chart.setCenter(new Label("100%").setRole(Label.Role.TITLE));

  • Constructor Details

    • DonutChart

      public DonutChart()

  • Method Details

    • of

      public static DonutChart of(List<String> labels, double... values)
      A donut over labels showing values.

    • innerRadius

      public float innerRadius()
      The hole's diameter as a fraction of the ring's.

    • setInnerRadius

      public DonutChart setInnerRadius(float fraction)
      Sets the hole as a fraction of the outer radius, in [0, 0.95]. 0 draws a pie; the default 0.62 leaves a hole big enough for a headline number.

    • startAngle

      public float startAngle()
      Where the first slice starts, in degrees clockwise from three o'clock.

    • setStartAngle

      public DonutChart setStartAngle(float degrees)
      Sets the first slice's starting angle in degrees; -90 (the default) is noon.

    • sliceGap

      public float sliceGap()
      Points of surface between two slices.

    • setSliceGap

      public DonutChart setSliceGap(float points)
      Sets the gap between slices in logical points (0 makes them touch).

    • setSliceColors

      public DonutChart setSliceColors(Color @Nullable ... colors)
      Pins the slice colors, in slice order; a shorter array leaves the rest to the palette, and null hands all of them back to it.

    • sliceColor

      public Color sliceColor(int index)
      The color of slice index: its own, or its palette slot.

    • center

      public @Nullable Widget<?> center()
      The widget in the hole, or null.

    • setCenter

      public DonutChart setCenter(@Nullable Widget<?> widget)
      Puts a widget in the hole. It is laid out centred in the largest square that fits inside the ring and is a normal child in every other way: it takes input, it can be a button, and it is measured against that square rather than against the chart. null empties the hole.

    • isSliceVisible

      public boolean isSliceVisible(int index)
      Whether slice index is currently drawn.

    • setSliceVisible

      public DonutChart setSliceVisible(int index, boolean visible)
      Hides or shows one slice; the rest of the ring closes over it, or opens for it.

    • onLayout

      protected void onLayout()
      Description copied from class: Chart
      Recomputes the regions whenever the box is laid out, so that the legend's boxes are current for the tree published between this pass and the paint. A subclass that lays out a child of its own calls this first.
      Overrides:
      onLayout in class Chart<DonutChart>

    • paintContent

      protected void paintContent(Canvas canvas, float x, float y, float w, float h)
      Description copied from class: Chart
      Paints the marks inside the region left after the title and the legend, in the chart's own coordinates. Grid, axes and everything data-shaped belong here.
      Specified by:
      paintContent in class Chart<DonutChart>

    • pickAt

      protected @Nullable ChartPoint pickAt(float localX, float localY)
      Description copied from class: Chart
      The datum under a point in the chart's local coordinates, or null when the pointer is not over the marks. Called for hover and for clicks, so it decides both.
      Specified by:
      pickAt in class Chart<DonutChart>

    • hoverRegion

      protected @Nullable Rect hoverRegion(ChartPoint point)
      The ring, grown by the distance a slice pops out of it.

      The whole ring rather than the hovered sector: a sector's bounding box is an arc problem with four cases for which quadrants it spans, and the ring is a square that is already much smaller than this widget, which also carries a title and a legend.

      Overrides:
      hoverRegion in class Chart<DonutChart>
      Parameters:
      point - the hovered datum, never null
      Returns:
      the region in widget coordinates, or null for "all of it"

    • onHoverChanged

      protected void onHoverChanged(@Nullable ChartPoint picked)
      Description copied from class: Chart
      Called when the datum under the pointer changes, null when there is none: the hook for a chart that animates something on hover. The application-facing callback is Chart.onPointHover(Consumer); this is for subclasses.
      Overrides:
      onHoverChanged in class Chart<DonutChart>

    • onAccessibility

      protected void onAccessibility(Accessibility a)
      One chart node, named by the title and described by the ring's series name, or named by the series when there is no title, with one toggleable series node per legend entry.

      What is published is what is drawn. The ring is the first visible series and any other is undrawn on purpose, so there is no node per series; the things the legend names and a click operates are the slices, one per category, and those are the children — only while the legend is drawn, because without it no slice has a box or an operation of its own, and the arcs are not nodes in this cut. Each child's box is the legend box a click is tested against and never the arc, which moves on every frame of an animation and on the hover pop. Its toggle state is the hidden-slice bit and never the eased weight, for the same reason. Every string is handed over by reference, so a damaged frame that changes nothing a reader hears allocates nothing.

      Overrides:
      onAccessibility in class Widget<DonutChart>
      Parameters:
      a - the node being described; write into it, and never keep it

    • onSyntheticAction

      protected boolean onSyntheticAction(long key, Accessible.Action action, Accessible.Argument arg)
      A toggle on a slice node reaches the same path a click on its legend entry reaches, so a reader's toggle and a pointer's are one and the same to the chart; refused when the legend is not interactive, not drawn, or the key names no category.
      Overrides:
      onSyntheticAction in class Widget<DonutChart>
      Parameters:
      key - the key this widget gave that child when it declared it
      action - what was asked
      arg - the argument, or Accessible.Argument.NONE
      Returns:
      whether this widget did it

    • tooltipRows

      protected List<ChartPoint> tooltipRows(ChartPoint picked)
      Description copied from class: Chart
      The rows a tooltip shows for picked. The default is Chart.TooltipMode.INDEX-aware: every visible series at the same index, or just the picked datum in Chart.TooltipMode.POINT.
      Overrides:
      tooltipRows in class Chart<DonutChart>

    • tooltipTitle

      protected String tooltipTitle(ChartPoint picked)
      The series names the ring as a whole ("Traffic"); the row names the slice.
      Overrides:
      tooltipTitle in class Chart<DonutChart>

    • tooltipRowName

      protected String tooltipRowName(ChartPoint row)
      Description copied from class: Chart
      The name a tooltip row carries where reading starts, the series name by default.
      Overrides:
      tooltipRowName in class Chart<DonutChart>

    • tooltipRowValue

      protected String tooltipRowValue(ChartPoint row)
      Description copied from class: Chart
      The value a tooltip row carries where reading ends.
      Overrides:
      tooltipRowValue in class Chart<DonutChart>

    • tooltipRowColor

      protected Color tooltipRowColor(ChartPoint row)
      Description copied from class: Chart
      The swatch color for a tooltip row.
      Overrides:
      tooltipRowColor in class Chart<DonutChart>

    • legendEntries

      protected List<Chart.LegendEntry> legendEntries()
      Description copied from class: Chart
      One entry per series, in palette order. Overridden by charts whose legend is not that.
      Overrides:
      legendEntries in class Chart<DonutChart>

    • toggleLegendEntry

      protected void toggleLegendEntry(int index)
      Description copied from class: Chart
      Hides or shows what legend entry index stands for.
      Overrides:
      toggleLegendEntry in class Chart<DonutChart>