Package io.keikai.axyra.sheets.content

Class Chart.Builder

java.lang.Object
io.keikai.axyra.sheets.content.Chart.Builder
Enclosing class:
Chart
public static final class Chart.Builder extends Object
A fluent builder for a Chart. Start it with a type method such as Chart.column(), set the anchor and the series, then call build() and pass the result to Sheet.addChart. Series options (pointFill(int, io.keikai.axyra.sheets.style.Color), dataLabels(io.keikai.axyra.sheets.content.DataLabels), trendline(io.keikai.axyra.sheets.content.Trendline), seriesType(java.lang.String), ...) apply to the series added last. Tokens and numbers are checked only when the chart is added. 

 Chart chart = Chart.column()
         .title("Revenue")
         .anchor(1, 4, 16, 12)   // E2 to the top-left of M17
         .series("Revenue", "Sheet1!$B$2:$B$9", "Sheet1!$A$2:$A$9")
         .build();
 int index = sheet.addChart(chart);

  • Method Details

    • title

      public Chart.Builder title(String title)
      Sets a literal chart title and turns off autoTitle.

    • autoTitle

      public Chart.Builder autoTitle(boolean on)
      Mark the chart as carrying an Excel "auto" title: no explicit text is emitted, so the app derives the displayed title from the single series name. Use this instead of title(String) to reproduce a source chart whose title was auto (otherwise a rebuild shows a generic "Chart Title"). ECMA-376 §21.2.2.9 (autoTitleDeleted).

    • legend

      public Chart.Builder legend(LegendPosition position)
      Sets the legend placement. LegendPosition.NONE hides the legend by saving it marked deleted; legendVisible(boolean) hides it by omitting it. Without this call the legend is on the right.
      Throws:
      NullPointerException - if position is null

    • legendVisible

      public Chart.Builder legendVisible(boolean visible)
      Shows or hides the legend without changing its position. Hiding omits the <c:legend> element from the saved chart, so every renderer hides it. This differs from legend(LegendPosition.NONE), which writes <c:legend><c:delete val="1"/></c:legend>.

    • categoryAxisVisible

      public Chart.Builder categoryAxisVisible(boolean visible)
      Shows or hides the category (X) axis; shown by default (ECMA-376 §21.2.2.16 catAx).

    • valueAxisVisible

      public Chart.Builder valueAxisVisible(boolean visible)
      Shows or hides the value (Y) axis; shown by default (ECMA-376 §21.2.2.226 valAx).

    • valueAxisGridlines

      public Chart.Builder valueAxisGridlines(boolean on)
      Show or hide the value (Y) axis' major gridlines — the lines across the plot at each major tick (<c:majorGridlines>, ECMA-376 Part 1 §21.2.2). On by default. On a horizontal bar chart the value axis runs along the bottom, so its gridlines are vertical.

    • showDataLabels

      public Chart.Builder showDataLabels(boolean show)
      Turns value labels on every series on or off. For per-series label content, use dataLabels(DataLabels).

    • type

      public Chart.Builder type(String type)
      Change the chart family this spec describes, keeping everything else it already carries — the counterpart of Chart.type() on the read–modify–write path, where the family comes from the file and the caller wants a different one.
      Parameters:
      type - a family token accepted by Chart.of(java.lang.String)

    • threeD

      public Chart.Builder threeD(boolean on)
      Draws the chart in 3-D. Only bar, column, line, pie, area and surface charts have a 3-D form; other types ignore the flag when saved. Set the angles with view3D(int, int, int).

    • barShape

      public Chart.Builder barShape(String shape)
      The solid a 3-D bar or column is drawn as — <c:shape>, ECMA-376 Part 1 §21.2.2.177: "box" (the default), "cone", "coneToMax", "cylinder", "pyramid" or "pyramidToMax".

      Only a bar or column chart with threeD(boolean) set emits it; on any other family the shape has nowhere to go and is ignored, which is also how Excel treats it. An unknown token is read as "box".

    • style

      public Chart.Builder style(int style)
      The chart's built-in style number (<c:style val>).

      Excel stores the number and expands the appearance from its own gallery, so this writes exactly what a file carries and no more: a chart saved with a style number opens in Excel wearing that style, and renders here with whatever explicit formatting it was given. Excel's gallery numbers run from 1 to 48. A negative value makes Sheet.addChart throw AxyraException.

    • titleFormula

      public Chart.Builder titleFormula(String reference)
      Makes the chart title follow a cell instead of a literal string (<c:title><c:tx><c:strRef><c:f>).

      Pass a sheet-qualified reference such as "Sheet1!$A$1". Pair it with title(String) for the cached text that renderers draw. An empty string clears the link only through Sheet.replaceChart. On Sheet.addChart, leave this unset instead, because an empty reference is written as is.

    • grouping

      public Chart.Builder grouping(String grouping)
      Bar/column/area/line grouping: "clustered" / "stacked" / "percentStacked" / "standard" (default "clustered"). Stacked charts stack each category's series into one bar; without this a rebuilt stacked chart renders as clustered. An unknown token is not rejected and is read as "clustered".

    • gapWidth

      public Chart.Builder gapWidth(int percent)
      Sets the gap between bar or column clusters, as a percentage of one bar's width (0–500). When not set, the engine uses the value Excel writes for a new chart: 219 for a clustered 2-D column chart, 182 for a clustered 2-D bar chart, and 150 for stacked, 3-D and other charts. A negative value makes Sheet.addChart throw AxyraException.

    • overlap

      public Chart.Builder overlap(int percent)
      Sets how much bars in one cluster overlap, as a percentage from -100 (a full bar-width gap) to 100 (full overlap). When not set, the engine uses Excel's value for a new chart: -27 for a clustered 2-D column chart, 0 for every other chart.

    • holeSize

      public Chart.Builder holeSize(int percent)
      Sets the doughnut hole size as a percentage of the outer radius; 50 when not set. Has no effect on other chart types. A negative value makes Sheet.addChart throw AxyraException.

    • anchor

      public Chart.Builder anchor(int fromRow, int fromColumn, int toRow, int toColumn)
      Sets the two-cell anchor (0-based). The chart's top-left corner is at the top-left of cell (fromRow, fromColumn). Its bottom-right corner is at the top-left of cell (toRow, toColumn), so that cell is not covered unless anchorOffsets(int, int, int, int) moves the corner into it. A negative index makes Sheet.addChart throw AxyraException.

    • anchorOffsets

      public Chart.Builder anchorOffsets(int fromColOff, int fromRowOff, int toColOff, int toRowOff)
      The sub-cell EMU offsets of the two-cell anchor's from/to corners (914400 EMU = 1 inch). Excel pins a chart to a fractional position inside the from/to cells; without these the chart snaps to the cell boundary and resizes. Reproduces the exact placement of a source chart.

      Note the order: column offset before row offset for each corner, unlike FormControl.Builder.anchorOffsets(long, long, long, long). Offsets are non-negative EMU; a negative value makes Sheet.addChart throw AxyraException.

    • chartAreaFill

      public Chart.Builder chartAreaFill(Color fill)
      Chart-area fill color (ECMA-376 §21.2.2.198 <c:spPr> on the chart space). Only RGB colors are accepted; the alpha byte is ignored and null leaves the setting unchanged.
      Throws:
      IllegalStateException - if the color is a theme, indexed or automatic color

    • chartAreaBorder

      public Chart.Builder chartAreaBorder(Color color)
      Sets the chart-area border color. Only RGB colors are accepted; the alpha byte is ignored and null leaves the setting unchanged.
      Throws:
      IllegalStateException - if the color is a theme, indexed or automatic color

    • chartAreaNoBorder

      public Chart.Builder chartAreaNoBorder()
      Suppress the chart-area frame (<a:ln><a:noFill/></a:ln>). Use to reproduce a source chart with no outer border box, which a rebuilt chart would otherwise draw by default.

    • chartAreaNoFill

      public Chart.Builder chartAreaNoFill()
      Make the chart-area background explicitly TRANSPARENT (<a:noFill/>, ECMA-376 §20.1.8.44) so the sheet shows through — distinct from leaving the fill unset, which renders as the application-default opaque white. Takes precedence over chartAreaFill(Color).

    • plotAreaFill

      public Chart.Builder plotAreaFill(Color fill)
      Sets the plot-area fill color. Only RGB colors are accepted; the alpha byte is ignored and null leaves the setting unchanged.
      Throws:
      IllegalStateException - if the color is a theme, indexed or automatic color

    • plotAreaBorder

      public Chart.Builder plotAreaBorder(Color color)
      Sets the plot-area border color. Only RGB colors are accepted; the alpha byte is ignored and null leaves the setting unchanged.
      Throws:
      IllegalStateException - if the color is a theme, indexed or automatic color

    • plotAreaNoBorder

      public Chart.Builder plotAreaNoBorder()
      Suppress the plot-area frame (<a:ln><a:noFill/></a:ln>).

    • plotAreaNoFill

      public Chart.Builder plotAreaNoFill()
      Make the plot-area background explicitly transparent (mirrors chartAreaNoFill()).

    • series

      public Chart.Builder series(String name, String valuesRef)
      Adds a data series with no categories range.
      Parameters:
      name - the series name: literal text or a reference such as "Sheet1!$B$1"; null for none
      valuesRef - the values range, such as "Sheet1!$B$2:$B$9"

    • series

      public Chart.Builder series(String name, String valuesRef, String categoriesRef)
      Adds a data series with a categories (labels) range. On a scatter chart categoriesRef holds the X values.
      Parameters:
      name - the series name: literal text or a reference such as "Sheet1!$B$1"; null for none
      valuesRef - the values range, such as "Sheet1!$B$2:$B$9"
      categoriesRef - the categories range, or null for none

    • clearSeries

      public Chart.Builder clearSeries()
      Drop every series this builder currently holds.

      Written for the read–modify–write round trip: Chart.toBuilder() pre-loads the chart's existing series so series(...) appends to them, which is right when adding one and wrong when replacing the whole set. Clearing first makes the series list say exactly what the caller means, and nothing else about the chart is touched.

    • bubbleSeries

      public Chart.Builder bubbleSeries(String name, String valuesRef, String categoriesRef, String sizesRef)
      Add a bubble series: a values (Y) range, a categories (X) range and the sizes (Z) range that gives each bubble its area — <c:bubbleSize>, ECMA-376 Part 1 §21.2.2.19.

      Without the sizes every bubble is drawn identically, which is the one dimension a bubble chart exists to show. Only a bubble chart emits them. A null sizesRef adds the series without sizes.

    • bubbleSizes

      public Chart.Builder bubbleSizes(String sizesRef)
      Attaches a bubble-size (Z) range to the series most recently added — the counterpart of pointFill(int, io.keikai.axyra.sheets.style.Color) for a series that was added with one of the plain series(...) overloads. Does nothing when sizesRef is null or no series has been added.

    • series

      public Chart.Builder series(String name, String valuesRef, String categoriesRef, Color fill)
      Adds a data series with a solid fill color. Only RGB colors are accepted; the alpha byte is ignored and null leaves the theme color.
      Throws:
      IllegalStateException - if the color is a theme, indexed or automatic color

    • pointFill

      public Chart.Builder pointFill(int pointIndex, Color fill)
      Override the fill color of one data point (pie slice / bar) on the most recently added series (ECMA-376 §21.2.2.52 dPt). Reproduces per-slice colors when rebuilding a chart from its read model. pointIndex is 0-based. Only RGB colors are accepted; the alpha byte is ignored and null leaves the setting unchanged.
      Throws:
      IllegalStateException - when no series has been added yet, or fill is a theme, indexed or automatic color

    • pointExplosion

      public Chart.Builder pointExplosion(int pointIndex, int percent)
      Explode the pie/doughnut slice at pointIndex outward by percent of the radius (ECMA-376 §21.2.2.62 dPt/explosion) on the most recently added series. pointIndex is 0-based. percent must be non-negative; 0 means no explosion. A negative value makes Sheet.addChart throw AxyraException.
      Throws:
      IllegalStateException - when no series has been added yet

    • pointLabel

      public Chart.Builder pointLabel(int pointIndex, String text)
      Give one point of the most recently added series a label of its own (ECMA-376 §21.2.2.47 dLbl) — a caption in place of the value the rest of the series shows. Lines are separated by \n. pointIndex is 0-based.
      Throws:
      IllegalStateException - when no series has been added yet

    • pointLabelHidden

      public Chart.Builder pointLabelHidden(int pointIndex, boolean hidden)
      Hide the label of one point while the rest of the series keeps its own (<c:dLbl><c:delete val="1"/>). pointIndex is 0-based. Hiding drops any caption set with pointLabel(int, java.lang.String).
      Throws:
      IllegalStateException - when no series has been added yet

    • view3D

      public Chart.Builder view3D(int rotX, int rotY, int depthPercent)
      Render the chart in 3-D with the given view angles (ECMA-376 §21.2.2.228 view3D): rotX is the elevation and rotY the rotation, both in degrees; depthPercent is the depth as a percentage of the plot height (100 = default). The base type (bar/column/line/pie/area) becomes its *3DChart form on save. Implies threeD(true). rotY and depthPercent must be non-negative; a negative value makes Sheet.addChart throw AxyraException. A depthPercent of 0 keeps the default depth.

    • plotAreaLayout

      public Chart.Builder plotAreaLayout(double x, double y, double w, double h)
      Position the inner plot area at an explicit rectangle in chart-relative fractions (ECMA-376 §21.2.2.88 manualLayout): x/y are the top-left corner and w/h the size, all in [0, 1]. Without this the plot area is laid out automatically.

    • legendLayout

      public Chart.Builder legendLayout(double x, double y, double w, double h)
      Position the legend at an explicit rectangle in chart-relative fractions (x/y top-left, w/h size, all in [0, 1]) — a manual legend layout. Without this the legend is placed automatically at its position.

    • titleLayout

      public Chart.Builder titleLayout(double x, double y, double w, double h)
      Position the chart title at an explicit rectangle in chart-relative fractions — a manual title layout. Without this the title is placed automatically. x/y are the top-left corner and w/h the size, all in [0, 1].

    • trendline

      public Chart.Builder trendline(Trendline trendline)
      Add a trendline to the most recently added series. Trendlines persist to the saved workbook per ECMA-376 §21.2.2.211.
      Throws:
      IllegalStateException - when no series has been added yet
      NullPointerException - if trendline is null

    • errorBars

      public Chart.Builder errorBars(ErrorBars errorBars)
      Attach error bars to the most recently added series. Error bars persist to the saved workbook per ECMA-376 §21.2.2.55. Replaces any error bars set on that series before.
      Throws:
      IllegalStateException - when no series has been added yet
      NullPointerException - if errorBars is null

    • dataLabels

      public Chart.Builder dataLabels(DataLabels labels)
      Attach data labels to the most recently added series. Data labels are re-emitted as <c:dLbls> on save (ECMA-376 §21.2.2.49) and read back via ChartView.seriesDataLabels(int). A null labels removes the labels set before. The label's DataLabels.textColor() accepts only RGB colors; its alpha byte is ignored.
      Throws:
      IllegalStateException - when no series has been added yet, or the text color is a theme, indexed or automatic color

    • seriesType

      public Chart.Builder seriesType(String type)
      The plot type of the most recently added series in a combo chart — the plot group it is drawn in (ECMA-376 Part 1 §21.2.2.145: a <c:barChart>, <c:lineChart>, <c:areaChart> or <c:scatterChart> under the one <c:plotArea>). A combo series given no type is a column series.

      Only a combo chart has more than one plot group; build() rejects a series type on any other chart.

      Each type is drawn against a kind of axis pair: "column", "line" and "area" against categories along the bottom and values up the side; "bar" (horizontal bars) against categories up the side and values along the bottom; "scatter" against a value axis on both edges. The series on one axis — the primary, or the secondary (secondaryAxis(boolean)) — must share one kind, so a combo mixes kinds only by putting one kind on each axis: columns with a scatter series on the secondary axis, bars with a line on the secondary axis. build() rejects any other mix.

      On the secondary axis a scatter series' Y values run up the right and its X values along the top; a bar series' values run along the top. A scatter series' X values are the categoriesRef of series(String, String, String), as on a scatter chart.

      Parameters:
      type - "column", "line", "area", "bar" or "scatter"
      Throws:
      IllegalStateException - when no series has been added yet
      IllegalArgumentException - when type is none of those

    • secondaryAxis

      public Chart.Builder secondaryAxis(boolean on)
      Plot the most recently added series against a secondary value axis (on) — drawn on the right of the plot with its own scale, the way a ratio or a percentage is shown next to amounts — or against the primary one. On save the series goes in a plot group of its own type bound to the secondary axis pair (ECMA-376 Part 1 §21.2.2.226 valAx): values on the right for a column, line or area series, values along the top for a bar series, Y on the right and X along the top for a scatter series.

      Only a combo chart has a secondary axis; build() rejects one on any other chart, and a combo with every series on the secondary axis.

      Throws:
      IllegalStateException - when no series has been added yet

    • extendedApparatus

      public Chart.Builder extendedApparatus(String chartExBase64, String colorsBase64, String styleBase64)
      Carry the byte-exact apparatus of a modern extended (cx:) chart — the chartEx part plus its chartColorStyle / chartStyle parts, each base64-encoded — so a re-authored waterfall/funnel/… re-emits the complete part set Excel requires to open the file. The structured builder fields (series/axes/…) cannot reconstruct an extended chart, and Excel refuses to open a chartEx that lacks its colors/style relationships, so this is the faithful round-trip path. Obtain the arguments from ChartView.extendedChartExData() and its siblings. Passing a null chartExBase64 is a no-op.

      Reference: ISO/IEC 29500 Transitional; MS extension namespace .../office/drawing/2014/chartex.

    • categoryAxisTitle

      public Chart.Builder categoryAxisTitle(String title)
      Sets the category (X) axis title; null sets none.

    • valueAxisTitle

      public Chart.Builder valueAxisTitle(String title)
      Sets the value (Y) axis title; null sets none.

    • valueAxisScale

      public Chart.Builder valueAxisScale(double min, double max)
      Fixes the value (Y) axis to the range [min, max]. Without this call the axis scales automatically.

    • build

      public Chart build()
      The immutable chart.
      Throws:
      IllegalStateException - when a series carries a series type or the secondary axis on a chart that is not a combo, when every series of a combo is on the secondary axis, or when series of two axis kinds (column/line/area, bar, scatter) share one axis