Package io.keikai.axyra.sheets.content

Class Chart

java.lang.Object
io.keikai.axyra.sheets.content.Chart
public final class Chart extends Object
A chart (immutable). Specify the chart type, an optional title, a two-cell anchor rectangle, and one or more data series (each a range reference like "Sheet1!$B$2:$B$10"). Add with Sheet.addChart(...).

Types: column, bar, line, pie, area, scatter, doughnut, radar, bubble, surface, stock, combo, waterfall, histogram, funnel, treemap, sunburst, boxWhisker, pareto, map. Appearance the builder can set: legend placement and visibility, axis visibility/titles/scale, per-series and per-point fill colors, data labels, the Excel auto-title, and — on a combo chart — each series' plot type (Chart.Builder.seriesType(java.lang.String)) and value axis (Chart.Builder.secondaryAxis(boolean)). The color and style parts (colors1.xml, style1.xml) of a classic chart are not modeled. For an extended chart (waterfall, funnel, histogram, treemap, sunburst, box and whisker, pareto, map), pass them through Chart.Builder.extendedApparatus(java.lang.String, java.lang.String, java.lang.String).

Read the charts of a sheet with Sheet.charts() (snapshots), or edit one in place with Sheet.chart(int), which returns a ChartView.

  • Method Details

    • column

      public static Chart.Builder column()
      A vertical clustered column chart.

    • bar

      public static Chart.Builder bar()
      A horizontal bar chart: categories up the side, values along the bottom.

    • line

      public static Chart.Builder line()
      A line chart.

    • pie

      public static Chart.Builder pie()
      A pie chart; Excel draws only the first series.

    • area

      public static Chart.Builder area()
      An area chart.

    • scatter

      public static Chart.Builder scatter()
      An XY scatter chart; each series' categoriesRef holds its X values.

    • doughnut

      public static Chart.Builder doughnut()
      A doughnut chart; set the hole with Chart.Builder.holeSize(int).

    • radar

      public static Chart.Builder radar()
      A radar chart.

    • bubble

      public static Chart.Builder bubble()
      A bubble chart; add series with Chart.Builder.bubbleSeries(java.lang.String, java.lang.String, java.lang.String, java.lang.String) so each bubble has a size.

    • combo

      public static Chart.Builder combo()
      A combination chart: one plot holding column, line, area, horizontal bar and scatter series together (ECMA-376 Part 1 §21.2.2.145, one <c:plotArea> with several plot groups). Give each series its type with Chart.Builder.seriesType(java.lang.String) — a series given none is a column series — and move a series onto the secondary axes with Chart.Builder.secondaryAxis(boolean). The series on one axis share an axis kind (column/line/area, bar, scatter); see Chart.Builder.seriesType(java.lang.String).

    • surface

      public static Chart.Builder surface()
      A surface chart. The default form is the top-down (contour) view; call threeD(true) for the 3-D surface.

    • stock

      public static Chart.Builder stock()
      A stock chart (high-low-close). Add three series in high, low, close order — or four (open-high-low-close) — as Excel requires 3-4 series for this type.

    • waterfall

      public static Chart.Builder waterfall()
      A waterfall (bridge) chart: running total with positive/negative steps.

    • histogram

      public static Chart.Builder histogram()
      A histogram chart: values bucketed into frequency bins.

    • funnel

      public static Chart.Builder funnel()
      A funnel chart: values as progressively narrowing stages.

    • treemap

      public static Chart.Builder treemap()
      A treemap chart: hierarchical proportions as nested rectangles.

    • sunburst

      public static Chart.Builder sunburst()
      A sunburst chart: hierarchical proportions as concentric rings.

    • boxWhisker

      public static Chart.Builder boxWhisker()
      A box & whisker chart: distribution quartiles with outlier whiskers.

    • pareto

      public static Chart.Builder pareto()
      A pareto chart: sorted histogram with a cumulative-percentage line.

    • map

      public static Chart.Builder map()
      A filled-region map chart: geographic regions colored by value. The category range holds region names; region geometry is resolved by the spreadsheet application when the file is opened.

    • of

      public static Chart.Builder of(String type)
      A chart of any supported type token: column, bar, line, pie, area, scatter, doughnut, radar, bubble, surface, stock, combo, waterfall, histogram, funnel, treemap, sunburst, boxWhisker, pareto, map. An unknown token is not rejected: the chart is created as a column chart.

    • toBuilder

      public Chart.Builder toBuilder()
      A builder pre-loaded with this chart spec, for read–modify–write round trips. Its series are kept, so series(...) appends to them; call Chart.Builder.clearSeries() first to replace them.

    • toJson

      public String toJson()
      The chart spec as the JSON object sent to the engine. Used by the SDK; not needed by callers.

    • fromJson

      public static Chart fromJson(String json)
      Builds a chart spec from the engine's chart JSON, the form behind Sheet.charts(). Used by the SDK.

    • type

      public String type()
      The chart type token (see of(String)); an empty string when the spec has none.

    • title

      public String title()
      The literal title, or null when the chart has none or uses an auto title (titleAuto()).

    • titleAuto

      public boolean titleAuto()
      Whether this chart carries an Excel "auto" title (derived from the series name).

    • titleFormula

      public String titleFormula()
      The cell reference the title follows (<c:strRef><c:f>), or null for a literal or absent title.

    • style

      public int style()
      The chart's built-in style number (<c:style val>), or -1 when the chart carries none — which is what a chart built here does.

    • barShape

      public String barShape()
      The solid a 3-D bar or column is drawn as; "box" when the chart declares no shape, that being the attribute's default.

    • seriesBubbleSizes

      public String seriesBubbleSizes(int seriesIndex)
      The bubble-size (Z) reference of series seriesIndex, or null when it has none or the index is out of range.
      Parameters:
      seriesIndex - 0-based series index

    • seriesType

      public String seriesType(int seriesIndex)
      The plot type of series seriesIndex in a combo chart: "column", "line", "area", "bar" or "scatter", or the group type of an imported combo ("radar", "bubble", "stock").
      Parameters:
      seriesIndex - 0-based series index
      Returns:
      the type, or null when the series has none, on a chart that is not a combo, or for an index out of range. A combo series without a type is drawn as a column.

    • seriesSecondaryAxis

      public boolean seriesSecondaryAxis(int seriesIndex)
      Whether series seriesIndex is plotted against the secondary value axis of a combo chart; false for an index out of range.
      Parameters:
      seriesIndex - 0-based series index

    • seriesCount

      public int seriesCount()
      The number of series in this spec.

    • legendPosition

      public LegendPosition legendPosition()
      Legend placement; LegendPosition.RIGHT when the spec does not set one.

    • showDataLabels

      public boolean showDataLabels()
      Whether the chart-wide data-label switch is on.

    • is3d

      public boolean is3d()
      Whether the chart is drawn in 3-D.

    • categoryAxisTitle

      public String categoryAxisTitle()
      The category (X) axis title, or null when none is set.

    • valueAxisTitle

      public String valueAxisTitle()
      The value (Y) axis title, or null when none is set.

    • valueAxisGridlines

      public boolean valueAxisGridlines()
      Whether the value (Y) axis draws major gridlines (<c:majorGridlines>, ECMA-376 Part 1 §21.2.2). Defaults to true.

    • pivotSource

      public String pivotSource()
      The PivotChart binding this chart is driven by, in Excel's [WorkbookName]SheetName!PivotName form (ECMA-376 §21.2.2.153), or null for a regular chart. Set by Sheet.addPivotChart(int, java.lang.String, int, int, int, int) and preserved from imported files.