Class ChartView

java.lang.Object
io.keikai.axyra.sheets.ChartView

public final class ChartView extends Object
A live view of an existing chart, obtained via Sheet.chart(int) for a chart on a worksheet's drawing layer, or via Workbook.chartSheetChart(int) for the full-page chart hosted by a chart-sheet tab: getters mirror the Chart builder fields, setters apply immediately to the engine. Any mutation marks the host dirty — the sheet's drawing layer, or the chart sheet's byte-preserved import — so a byte-preserved imported chart is regenerated from the model on the next save (the edit becomes visible).

Trendline / error-bar edits are honored by the model and the renderer (Sheet.renderChartToPng(int, int, int)) and persist to the saved workbook (ECMA-376 §21.2.2.211 trendline, §21.2.2.55 errBars). The anchor accessors are meaningless for a chart-sheet-hosted chart (it always fills the page).

  • Method Summary

    Modifier and Type
    Method
    Description
    addTrendline(int seriesIndex, Trendline trendline)
    Add a trendline to a series.
    int[]
    {fromRow, fromColumn, toRow, toColumn} two-cell anchor.
    int[]
    {fromColOff, fromRowOff, toColOff, toRowOff} — the sub-cell EMU offsets of the two-cell anchor's corners (914400 EMU = 1 inch).
    The solid a 3-D bar or column draws its bars as (<c:shape>, ECMA-376 Part 1 §21.2.2.177): "box", "cone", "coneToMax", "cylinder", "pyramid" or "pyramidToMax".
     
    boolean
    Whether the category (X) axis is drawn.
    The chart-area fill color, or null (default).
    The chart-area frame (border) line color, or null (default).
    boolean
    Whether the chart-area background is explicitly TRANSPARENT (<a:noFill/>, ECMA-376 §20.1.8.44) — the sheet shows through.
    boolean
    Whether the chart-area frame is explicitly suppressed (no border box).
    clearTrendlines(int seriesIndex)
    Remove every trendline from a series.
    errorBars(int seriesIndex)
    The error bars of a series, or null.
    Base64 of the source xl/charts/chartEx*.xml part for an extended chart, or null for a classic chart.
    Base64 of the extended chart's chartColorStyle part, or null.
    Base64 of the extended chart's chartStyle part, or null.
    int
    Bar/column gap width percent (Excel default 150).
    Bar/column/area/line grouping: "clustered" / "stacked" / "percentStacked" / "standard" (Excel default "clustered").
    int
    Doughnut hole size percent.
    int
    This chart's index on its sheet.
    boolean
     
    boolean
    Whether this is a modern extended chart — the ISO/IEC 29500 Transitional cx: chart-extension schema (waterfall, funnel, histogram, treemap, sunburst, box & whisker, region map).
    boolean
    Whether this chart is a pie-of-pie or bar-of-pie (<c:ofPieChart>).
    double[]
    The manual legend layout as [x, y, w, h] chart-relative fractions, or null when the legend is placed automatically.
     
    boolean
    Whether the legend is shown at all (independent of its position).
    int[]
    The zero-based point indices a cust split puts in the second plot (<c:custSplit>); empty for every other rule.
    boolean
    Whether an of-pie chart draws its second plot as a stacked bar (<c:ofPieType val="bar"/>) rather than as a second pie.
    The second plot's size as a percentage of the first (<c:secondPieSize>), or null when absent.
    The count or threshold the split rule compares against (<c:splitPos>), or null when absent.
    The of-pie split rule as the format's own token — auto, cust, percent, pos or val — or null when the chart carries no <c:splitType>.
    int
    Bar overlap percent (-100..100).
    The plot-area fill color, or null (default).
    double[]
    The manual plot-area layout (ECMA-376 §21.2.2.88 manualLayout) as [x, y, w, h] in chart-relative fractions, or null when the plot area is laid out automatically.
    The plot-area frame (border) line color, or null (default).
    boolean
    Whether the plot-area background is explicitly transparent (mirrors chartAreaNoFill()).
    boolean
    Whether the plot-area frame is explicitly suppressed.
    void
    Re-read the chart state from the engine.
    seriesBubbleSizes(int seriesIndex)
    The series' bubble-size (Z) range reference (<c:bubbleSize>), or null on anything but a bubble chart that declares one.
    seriesCategories(int seriesIndex)
    The series categories range reference, or null.
    int
     
    seriesDataLabels(int seriesIndex)
    The series-level data labels (<c:dLbls>), or null when the series carries none.
    seriesFill(int seriesIndex)
    The explicit per-series fill color, or null when the series uses the theme default.
    seriesHiddenPointLabels(int seriesIndex)
    The point indices whose label the chart hides while the rest of the series keeps its own (<c:dLbl><c:delete val="1"/>).
    boolean[]
    seriesInSecondPlot(int seriesIndex)
    Which of a series' points a pie-of-pie / bar-of-pie draws in its second plot, one flag per cached value.
    seriesName(int seriesIndex)
    The series name reference/text, or null.
    seriesPointExplosions(int seriesIndex)
    The explicit per-slice explosion overrides of a series (pie/doughnut), keyed by 0-based point index (ECMA-376 §21.2.2.62 dPt/explosion, percent of radius).
    seriesPointFills(int seriesIndex)
    The explicit per-data-point (per-slice / per-bar) fill overrides of a series, keyed by 0-based point index (ECMA-376 §21.2.2.52 dPt).
    seriesPointLabels(int seriesIndex)
    The captions of the series' per-point labels (<c:dLbl>), keyed by the point index each names.
    boolean
    seriesSecondaryAxis(int seriesIndex)
    Whether this series is plotted against the secondary value axis of a combination chart; false on an ordinary chart.
    seriesType(int seriesIndex)
    The plot group this series is drawn in on a combination chart — one <c:plotArea> holding several <c:*Chart> groups, the bar-plus-line shape Excel calls a combo (ECMA-376 Part 1 §21.2.2.145): "column", "line", "area", "bar", "scatter", or the type of the group an imported combo put it in ("radar", "bubble", "stock").
    double[]
    seriesValueCache(int seriesIndex)
    The series' cached point values (<c:numCache>), in point order.
    seriesValues(int seriesIndex)
    The series values range reference (e.g.
    setAnchor(int fromRow, int fromColumn, int toRow, int toColumn)
    Move / resize the chart's two-cell anchor.
    setAutoTitle(boolean auto)
    Mark (or clear) the title as an Excel "auto" title.
    Set (or clear with null) the category-axis title.
    setCategoryAxisVisible(boolean visible)
    Show or hide the category (X) axis.
    setErrorBars(int seriesIndex, ErrorBars errorBars)
    Set (or remove with null) the error bars of a series.
    setGapWidth(int percent)
     
    setHoleSize(int percent)
     
     
    setLegendVisible(boolean visible)
    Show or hide the legend without changing its position.
    setOverlap(int percent)
     
    setSeries(int seriesIndex, String name, String valuesRef, String categoriesRef)
    Replace the name / values / categories references of one series.
    setSeriesDataLabels(int seriesIndex, DataLabels labels)
    Set (or remove with null) the data labels of a series.
    setSeriesFill(int seriesIndex, Color fill)
    Set (or clear with null) the explicit fill color of one series.
    setSeriesSecondaryAxis(int seriesIndex, boolean on)
    Plot one series of a combo chart against the secondary value axis (on) or the primary one — the counterpart of Chart.Builder.secondaryAxis(boolean).
    setSeriesType(int seriesIndex, String type)
    Move one series of a combo chart into the plot group of another type — the counterpart of Chart.Builder.seriesType(String).
    setShowDataLabels(boolean show)
    Show value labels on every series, or (with false) remove every data label from the chart, series and point labels included — Excel's Data Labels > None.
    setThreeD(boolean threeD)
     
    Set (or clear with null) the chart title.
    Show or hide the value (Y) axis' major gridlines.
    setValueAxisScale(double min, double max)
     
    Set (or clear with null) the value-axis title.
    setValueAxisVisible(boolean visible)
    Show or hide the value (Y) axis.
    boolean
    Whether the chart shows data labels: set through the builder or setShowDataLabels(boolean), or value labels on every series — the form the setting takes in a file, so it reads back after reopening.
    int
    The chart's built-in style number (<c:style val>), or -1 when it carries none.
    The chart title, or null.
    boolean
    Whether the chart title is an Excel "auto" title — a <c:title> present with no explicit text, so the app derives it from the single series name.
    The cell reference the title follows (<c:strRef><c:f>), or null for a literal or absent title.
    double[]
    The manual title layout as [x, y, w, h] chart-relative fractions, or null when the title is placed automatically.
    trendlines(int seriesIndex)
    The trendlines of a series (empty when none).
    The chart type token (column/bar/line/pie/…).
    boolean
    Whether the value (Y) axis draws major gridlines (<c:majorGridlines>).
    The explicit value-axis maximum, or null (auto).
    The explicit value-axis minimum, or null (auto).
     
    boolean
    Whether the value (Y) axis is drawn.
    int[]
    The chart's 3-D view angles (ECMA-376 §21.2.2.228 view3D) as [rotX, rotY, depthPercent], or null when the chart is not 3-D.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Method Details

    • reload

      public void reload()
      Re-read the chart state from the engine.
    • index

      public int index()
      This chart's index on its sheet.
    • type

      public String type()
      The chart type token (column/bar/line/pie/…).
    • title

      public String title()
      The chart title, or null.
    • legendPosition

      public LegendPosition legendPosition()
    • showDataLabels

      public boolean showDataLabels()
      Whether the chart shows data labels: set through the builder or setShowDataLabels(boolean), or value labels on every series — the form the setting takes in a file, so it reads back after reopening.
    • is3d

      public boolean is3d()
    • barShape

      public String barShape()
      The solid a 3-D bar or column draws its bars as (<c:shape>, ECMA-376 Part 1 §21.2.2.177): "box", "cone", "coneToMax", "cylinder", "pyramid" or "pyramidToMax". "box" when the chart declares none, that being the attribute's default.
    • style

      public int style()
      The chart's built-in style number (<c:style val>), or -1 when it carries none.
    • titleFormula

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

      public String grouping()
      Bar/column/area/line grouping: "clustered" / "stacked" / "percentStacked" / "standard" (Excel default "clustered"). A stacked series set renders as one solid bar per category, so this must be reproduced to rebuild a stacked chart.
    • gapWidth

      public int gapWidth()
      Bar/column gap width percent (Excel default 150).
    • overlap

      public int overlap()
      Bar overlap percent (-100..100).
    • holeSize

      public int holeSize()
      Doughnut hole size percent.
    • categoryAxisTitle

      public String categoryAxisTitle()
    • valueAxisTitle

      public String valueAxisTitle()
    • valueAxisMin

      public Double valueAxisMin()
      The explicit value-axis minimum, or null (auto).
    • valueAxisMax

      public Double valueAxisMax()
      The explicit value-axis maximum, or null (auto).
    • anchor

      public int[] anchor()
      {fromRow, fromColumn, toRow, toColumn} two-cell anchor.
    • anchorOffsets

      public int[] anchorOffsets()
      {fromColOff, fromRowOff, toColOff, toRowOff} — the sub-cell EMU offsets of the two-cell anchor's corners (914400 EMU = 1 inch). Reproduce them on a rebuild via Chart.Builder.anchorOffsets(int, int, int, int) so the chart keeps its exact fractional placement / size.
    • chartAreaFill

      public Color chartAreaFill()
      The chart-area fill color, or null (default). ECMA-376 §21.2.2.198 spPr.
    • chartAreaLineColor

      public Color chartAreaLineColor()
      The chart-area frame (border) line color, or null (default).
    • chartAreaNoLine

      public boolean chartAreaNoLine()
      Whether the chart-area frame is explicitly suppressed (no border box).
    • chartAreaNoFill

      public boolean chartAreaNoFill()
      Whether the chart-area background is explicitly TRANSPARENT (<a:noFill/>, ECMA-376 §20.1.8.44) — the sheet shows through. Distinct from chartAreaFill() returning null, which means "unset" and renders as the application-default opaque white.
    • plotAreaFill

      public Color plotAreaFill()
      The plot-area fill color, or null (default).
    • plotAreaLineColor

      public Color plotAreaLineColor()
      The plot-area frame (border) line color, or null (default).
    • plotAreaNoLine

      public boolean plotAreaNoLine()
      Whether the plot-area frame is explicitly suppressed.
    • plotAreaNoFill

      public boolean plotAreaNoFill()
      Whether the plot-area background is explicitly transparent (mirrors chartAreaNoFill()).
    • seriesCount

      public int seriesCount()
    • seriesName

      public String seriesName(int seriesIndex)
      The series name reference/text, or null.
    • seriesValues

      public String seriesValues(int seriesIndex)
      The series values range reference (e.g. Sheet1!$B$2:$B$9).
    • seriesCategories

      public String seriesCategories(int seriesIndex)
      The series categories range reference, or null.
    • seriesBubbleSizes

      public String seriesBubbleSizes(int seriesIndex)
      The series' bubble-size (Z) range reference (<c:bubbleSize>), or null on anything but a bubble chart that declares one.
    • seriesType

      public String seriesType(int seriesIndex)
      The plot group this series is drawn in on a combination chart — one <c:plotArea> holding several <c:*Chart> groups, the bar-plus-line shape Excel calls a combo (ECMA-376 Part 1 §21.2.2.145): "column", "line", "area", "bar", "scatter", or the type of the group an imported combo put it in ("radar", "bubble", "stock").

      null on an ordinary chart, where type() describes every series. Change it with setSeriesType(int, String).

    • seriesSecondaryAxis

      public boolean seriesSecondaryAxis(int seriesIndex)
      Whether this series is plotted against the secondary value axis of a combination chart; false on an ordinary chart. Change it with setSeriesSecondaryAxis(int, boolean).
    • seriesFill

      public Color seriesFill(int seriesIndex)
      The explicit per-series fill color, or null when the series uses the theme default. The write counterpart is Chart.Builder.series(String, String, String, Color) — this reader closes that read/write asymmetry (ECMA-376 §21.2.2.211 spPr).
    • seriesPointFills

      public Map<Integer,Color> seriesPointFills(int seriesIndex)
      The explicit per-data-point (per-slice / per-bar) fill overrides of a series, keyed by 0-based point index (ECMA-376 §21.2.2.52 dPt). Empty when the series carries no <c:dPt> color overrides.
    • seriesPointLabels

      public Map<Integer,String> seriesPointLabels(int seriesIndex)
      The captions of the series' per-point labels (<c:dLbl>), keyed by the point index each names.

      A series' <c:dLbls> block sets what every point's label shows; a <c:dLbl> inside it overrides that for one point, most often with a caption of its own. Empty when every point uses the series-level label. Lines within a caption are separated by \n.

    • seriesHiddenPointLabels

      public Set<Integer> seriesHiddenPointLabels(int seriesIndex)
      The point indices whose label the chart hides while the rest of the series keeps its own (<c:dLbl><c:delete val="1"/>).
    • seriesValueCache

      public double[] seriesValueCache(int seriesIndex)
      The series' cached point values (<c:numCache>), in point order.

      These are the numbers the chart was drawn from, as the file recorded them. Empty when the series carries no cache and its range could not be resolved against the cells.

    • seriesInSecondPlot

      public boolean[] seriesInSecondPlot(int seriesIndex)
      Which of a series' points a pie-of-pie / bar-of-pie draws in its second plot, one flag per cached value.

      Derived by the engine from the chart's split settings and the series' values, so every caller gets the same answer to a question the file only states indirectly. Empty for a chart with no of-pie split — which is not the same as all-false, and is why this returns a length rather than a per-index lookup.

    • isOfPie

      public boolean isOfPie()
      Whether this chart is a pie-of-pie or bar-of-pie (<c:ofPieChart>).
    • ofPieSecondPlotIsBar

      public boolean ofPieSecondPlotIsBar()
      Whether an of-pie chart draws its second plot as a stacked bar (<c:ofPieType val="bar"/>) rather than as a second pie. false for a chart that is not an of-pie at all — test with isOfPie() first.
    • ofPieSplitType

      public String ofPieSplitType()
      The of-pie split rule as the format's own token — auto, cust, percent, pos or val — or null when the chart carries no <c:splitType>.

      An absent rule is kept distinct from an explicit auto: the first leaves the choice to the application, the second records that the author chose to leave it there.

    • ofPieSplitPosition

      public Double ofPieSplitPosition()
      The count or threshold the split rule compares against (<c:splitPos>), or null when absent.
    • ofPieCustomSplit

      public int[] ofPieCustomSplit()
      The zero-based point indices a cust split puts in the second plot (<c:custSplit>); empty for every other rule.
    • ofPieSecondPlotSize

      public Integer ofPieSecondPlotSize()
      The second plot's size as a percentage of the first (<c:secondPieSize>), or null when absent.
    • view3D

      public int[] view3D()
      The chart's 3-D view angles (ECMA-376 §21.2.2.228 view3D) as [rotX, rotY, depthPercent], or null when the chart is not 3-D. The read-back counterpart of Chart.Builder.view3D(int, int, int).
    • plotAreaLayout

      public double[] plotAreaLayout()
      The manual plot-area layout (ECMA-376 §21.2.2.88 manualLayout) as [x, y, w, h] in chart-relative fractions, or null when the plot area is laid out automatically. Read-back of Chart.Builder.plotAreaLayout(double, double, double, double).
    • legendLayout

      public double[] legendLayout()
      The manual legend layout as [x, y, w, h] chart-relative fractions, or null when the legend is placed automatically. Read-back of Chart.Builder.legendLayout(double, double, double, double).
    • titleLayout

      public double[] titleLayout()
      The manual title layout as [x, y, w, h] chart-relative fractions, or null when the title is placed automatically. Read-back of Chart.Builder.titleLayout(double, double, double, double).
    • seriesPointExplosions

      public Map<Integer,Integer> seriesPointExplosions(int seriesIndex)
      The explicit per-slice explosion overrides of a series (pie/doughnut), keyed by 0-based point index (ECMA-376 §21.2.2.62 dPt/explosion, percent of radius). Empty when no slice is exploded.
    • titleAuto

      public boolean titleAuto()
      Whether the chart title is an Excel "auto" title — a <c:title> present with no explicit text, so the app derives it from the single series name. When true, title() is null and callers must not re-issue a literal title (that is what turns an auto title into a generic "Chart Title" placeholder on rebuild).
    • legendVisible

      public boolean legendVisible()
      Whether the legend is shown at all (independent of its position).
    • categoryAxisVisible

      public boolean categoryAxisVisible()
      Whether the category (X) axis is drawn. Defaults to true.
    • valueAxisVisible

      public boolean valueAxisVisible()
      Whether the value (Y) axis is drawn. Defaults to true.
    • valueAxisGridlines

      public boolean valueAxisGridlines()
      Whether the value (Y) axis draws major gridlines (<c:majorGridlines>). Defaults to true; an imported chart reports what its file says.
    • trendlines

      public List<Trendline> trendlines(int seriesIndex)
      The trendlines of a series (empty when none).
    • seriesDataLabels

      public DataLabels seriesDataLabels(int seriesIndex)
      The series-level data labels (<c:dLbls>), or null when the series carries none. Reproduce them on a rebuild via Chart.Builder.dataLabels(DataLabels) (ECMA-376 §21.2.2.49).
    • errorBars

      public ErrorBars errorBars(int seriesIndex)
      The error bars of a series, or null.
    • isExtendedChart

      public boolean isExtendedChart()
      Whether this is a modern extended chart — the ISO/IEC 29500 Transitional cx: chart-extension schema (waterfall, funnel, histogram, treemap, sunburst, box & whisker, region map). Such a chart carries a byte-exact apparatus (its chartEx part plus the chartColorStyle / chartStyle parts) which Excel requires intact to open the file; re-issue it verbatim through Chart.Builder.extendedApparatus(java.lang.String, java.lang.String, java.lang.String) when rebuilding, since the structured builder fields cannot reconstruct it.
    • extendedChartExData

      public String extendedChartExData()
      Base64 of the source xl/charts/chartEx*.xml part for an extended chart, or null for a classic chart. Pass to Chart.Builder.extendedApparatus(java.lang.String, java.lang.String, java.lang.String).
    • extendedColorsData

      public String extendedColorsData()
      Base64 of the extended chart's chartColorStyle part, or null.
    • extendedStyleData

      public String extendedStyleData()
      Base64 of the extended chart's chartStyle part, or null.
    • setTitle

      public ChartView setTitle(String title)
      Set (or clear with null) the chart title.
    • setLegend

      public ChartView setLegend(LegendPosition position)
    • setLegendVisible

      public ChartView setLegendVisible(boolean visible)
      Show or hide the legend without changing its position.
    • setCategoryAxisVisible

      public ChartView setCategoryAxisVisible(boolean visible)
      Show or hide the category (X) axis.
    • setValueAxisVisible

      public ChartView setValueAxisVisible(boolean visible)
      Show or hide the value (Y) axis.
    • setValueAxisGridlines

      public ChartView setValueAxisGridlines(boolean on)
      Show or hide the value (Y) axis' major gridlines.
    • setAutoTitle

      public ChartView setAutoTitle(boolean auto)
      Mark (or clear) the title as an Excel "auto" title. When true the explicit title text is cleared and the app derives it from the series name.
    • setSeriesFill

      public ChartView setSeriesFill(int seriesIndex, Color fill)
      Set (or clear with null) the explicit fill color of one series.
    • setSeriesType

      public ChartView setSeriesType(int seriesIndex, String type)
      Move one series of a combo chart into the plot group of another type — the counterpart of Chart.Builder.seriesType(String).

      The series on one axis must share an axis kind, as on the builder: a "bar" or "scatter" series goes on an axis no other kind is on — move it to the secondary axis first.

      Parameters:
      type - "column", "line", "area", "bar" or "scatter"
      Throws:
      IllegalArgumentException - when type is none of those
      IllegalStateException - when the chart is not a combo, or when a series of another axis kind is on the same axis
    • setSeriesSecondaryAxis

      public ChartView setSeriesSecondaryAxis(int seriesIndex, boolean on)
      Plot one series of a combo chart against the secondary value axis (on) or the primary one — the counterpart of Chart.Builder.secondaryAxis(boolean).
      Throws:
      IllegalStateException - when the chart is not a combo, when the move would leave no series on the primary axis, or when a series of another axis kind (column/line/area, bar, scatter) is on the axis the series moves to
    • setShowDataLabels

      public ChartView setShowDataLabels(boolean show)
      Show value labels on every series, or (with false) remove every data label from the chart, series and point labels included — Excel's Data Labels > None.
    • setThreeD

      public ChartView setThreeD(boolean threeD)
    • setGapWidth

      public ChartView setGapWidth(int percent)
    • setOverlap

      public ChartView setOverlap(int percent)
    • setHoleSize

      public ChartView setHoleSize(int percent)
    • setCategoryAxisTitle

      public ChartView setCategoryAxisTitle(String title)
      Set (or clear with null) the category-axis title.
    • setValueAxisTitle

      public ChartView setValueAxisTitle(String title)
      Set (or clear with null) the value-axis title.
    • setValueAxisScale

      public ChartView setValueAxisScale(double min, double max)
    • setAnchor

      public ChartView setAnchor(int fromRow, int fromColumn, int toRow, int toColumn)
      Move / resize the chart's two-cell anchor.
    • setSeries

      public ChartView setSeries(int seriesIndex, String name, String valuesRef, String categoriesRef)
      Replace the name / values / categories references of one series.
    • addTrendline

      public ChartView addTrendline(int seriesIndex, Trendline trendline)
      Add a trendline to a series.
    • clearTrendlines

      public ChartView clearTrendlines(int seriesIndex)
      Remove every trendline from a series.
    • setErrorBars

      public ChartView setErrorBars(int seriesIndex, ErrorBars errorBars)
      Set (or remove with null) the error bars of a series.
    • setSeriesDataLabels

      public ChartView setSeriesDataLabels(int seriesIndex, DataLabels labels)
      Set (or remove with null) the data labels of a series.