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
Fluent builder.

  • Method Details

    • title

      public Chart.Builder title(String title)

    • 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)
      Legend placement; LegendPosition.NONE hides the legend.

    • legendVisible

      public Chart.Builder legendVisible(boolean visible)
      Show or hide the legend without changing its position — distinct from legend(LegendPosition). Hiding emits <c:legend> <c:delete val="1"/> so a rebuilt minimal chart does not sprout a legend the source hid (ECMA-376 §21.2.2.24 legend).

    • categoryAxisVisible

      public Chart.Builder categoryAxisVisible(boolean visible)
      Show or hide the category (X) axis (ECMA-376 §21.2.2.16 catAx).

    • valueAxisVisible

      public Chart.Builder valueAxisVisible(boolean visible)
      Show or hide the value (Y) axis (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)
      Show/hide data labels on the series.

    • 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)
      Render the chart in 3-D.

    • 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.

    • 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.

    • titleFormula

      public Chart.Builder titleFormula(String reference)
      Make the chart title follow a cell rather than a literal string — <c:title><c:tx><c:strRef><c:f>.

      Pass the reference ("Sheet1!$A$1"); pair it with title(String) for the text to cache, which is what renderers that do not evaluate the reference will draw. An empty string clears the link and leaves the literal title.

    • 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.

    • gapWidth

      public Chart.Builder gapWidth(int percent)
      Bar/column gap width as a percentage of bar width (0–500, default 150).

    • overlap

      public Chart.Builder overlap(int percent)
      Bar overlap as a percentage (-100 to 100, default 0).

    • holeSize

      public Chart.Builder holeSize(int percent)
      Doughnut hole size as a percentage (10–90, default 50).

    • anchor

      public Chart.Builder anchor(int fromRow, int fromColumn, int toRow, int toColumn)
      The two-cell anchor rectangle (0-based cells).

    • 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.

    • chartAreaFill

      public Chart.Builder chartAreaFill(Color fill)
      Chart-area fill color (ECMA-376 §21.2.2.198 <c:spPr> on the chart space).

    • chartAreaBorder

      public Chart.Builder chartAreaBorder(Color color)
      Chart-area frame (border) line 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)
      Plot-area fill color.

    • plotAreaBorder

      public Chart.Builder plotAreaBorder(Color color)
      Plot-area frame (border) line 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)
      Add a data series referencing a values range.

    • series

      public Chart.Builder series(String name, String valuesRef, String categoriesRef)
      Add a data series with a categories (labels) range.

    • 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.

    • 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.

    • series

      public Chart.Builder series(String name, String valuesRef, String categoriesRef, Color fill)
      Add a data series with an explicit fill 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.
      Throws:
      IllegalStateException - when no series has been added yet

    • 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.
      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.
      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"/>).
      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).

    • 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.

    • 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

    • 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.
      Throws:
      IllegalStateException - when no series has been added yet

    • 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).
      Throws:
      IllegalStateException - when no series has been added yet

    • 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)
      Category (X) axis title.

    • valueAxisTitle

      public Chart.Builder valueAxisTitle(String title)
      Value (Y) axis title.

    • valueAxisScale

      public Chart.Builder valueAxisScale(double min, double max)
      Fix the value (Y) axis scale to [min, max].

    • 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