Class ChartView
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 TypeMethodDescriptionaddTrendline(int seriesIndex, Trendline trendline) Add a trendline to a series.int[]anchor(){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).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".booleanWhether the category (X) axis is drawn.The chart-area fill color, ornull(default).The chart-area frame (border) line color, ornull(default).booleanWhether the chart-area background is explicitly TRANSPARENT (<a:noFill/>, ECMA-376 §20.1.8.44) — the sheet shows through.booleanWhether 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, ornull.Base64 of the sourcexl/charts/chartEx*.xmlpart for an extended chart, ornullfor a classic chart.Base64 of the extended chart'schartColorStylepart, ornull.Base64 of the extended chart'schartStylepart, ornull.intgapWidth()Bar/column gap width percent (Excel default 150).grouping()Bar/column/area/line grouping:"clustered"/"stacked"/"percentStacked"/"standard"(Excel default"clustered").intholeSize()Doughnut hole size percent.intindex()This chart's index on its sheet.booleanis3d()booleanWhether this is a modern extended chart — the ISO/IEC 29500 Transitionalcx:chart-extension schema (waterfall, funnel, histogram, treemap, sunburst, box & whisker, region map).booleanisOfPie()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, ornullwhen the legend is placed automatically.booleanWhether the legend is shown at all (independent of its position).int[]The zero-based point indices acustsplit puts in the second plot (<c:custSplit>); empty for every other rule.booleanWhether 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>), ornullwhen absent.The count or threshold the split rule compares against (<c:splitPos>), ornullwhen absent.The of-pie split rule as the format's own token —auto,cust,percent,posorval— ornullwhen the chart carries no<c:splitType>.intoverlap()Bar overlap percent (-100..100).The plot-area fill color, ornull(default).double[]The manual plot-area layout (ECMA-376 §21.2.2.88manualLayout) as[x, y, w, h]in chart-relative fractions, ornullwhen the plot area is laid out automatically.The plot-area frame (border) line color, ornull(default).booleanWhether the plot-area background is explicitly transparent (mirrorschartAreaNoFill()).booleanWhether the plot-area frame is explicitly suppressed.voidreload()Re-read the chart state from the engine.seriesBubbleSizes(int seriesIndex) The series' bubble-size (Z) range reference (<c:bubbleSize>), ornullon anything but a bubble chart that declares one.seriesCategories(int seriesIndex) The series categories range reference, ornull.intseriesDataLabels(int seriesIndex) The series-level data labels (<c:dLbls>), ornullwhen the series carries none.seriesFill(int seriesIndex) The explicit per-series fill color, ornullwhen 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, ornull.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.62dPt/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.booleanseriesSecondaryAxis(int seriesIndex) Whether this series is plotted against the secondary value axis of a combination chart;falseon 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.setCategoryAxisTitle(String title) Set (or clear withnull) the category-axis title.setCategoryAxisVisible(boolean visible) Show or hide the category (X) axis.setErrorBars(int seriesIndex, ErrorBars errorBars) Set (or remove withnull) the error bars of a series.setGapWidth(int percent) setHoleSize(int percent) setLegend(LegendPosition position) setLegendVisible(boolean visible) Show or hide the legend without changing its position.setOverlap(int percent) Replace the name / values / categories references of one series.setSeriesDataLabels(int seriesIndex, DataLabels labels) Set (or remove withnull) the data labels of a series.setSeriesFill(int seriesIndex, Color fill) Set (or clear withnull) 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 ofChart.Builder.secondaryAxis(boolean).setSeriesType(int seriesIndex, String type) Move one series of a combo chart into the plot group of another type — the counterpart ofChart.Builder.seriesType(String).setShowDataLabels(boolean show) Show value labels on every series, or (withfalse) remove every data label from the chart, series and point labels included — Excel's Data Labels > None.setThreeD(boolean threeD) Set (or clear withnull) the chart title.setValueAxisGridlines(boolean on) Show or hide the value (Y) axis' major gridlines.setValueAxisScale(double min, double max) setValueAxisTitle(String title) Set (or clear withnull) the value-axis title.setValueAxisVisible(boolean visible) Show or hide the value (Y) axis.booleanWhether the chart shows data labels: set through the builder orsetShowDataLabels(boolean), or value labels on every series — the form the setting takes in a file, so it reads back after reopening.intstyle()The chart's built-in style number (<c:style val>), or-1when it carries none.title()The chart title, ornull.booleanWhether 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>), ornullfor a literal or absent title.double[]The manual title layout as[x, y, w, h]chart-relative fractions, ornullwhen the title is placed automatically.trendlines(int seriesIndex) The trendlines of a series (empty when none).type()The chart type token (column/bar/line/pie/…).booleanWhether the value (Y) axis draws major gridlines (<c:majorGridlines>).The explicit value-axis maximum, ornull(auto).The explicit value-axis minimum, ornull(auto).booleanWhether the value (Y) axis is drawn.int[]view3D()The chart's 3-D view angles (ECMA-376 §21.2.2.228view3D) as[rotX, rotY, depthPercent], ornullwhen the chart is not 3-D.
-
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
The chart type token (column/bar/line/pie/…). -
title
The chart title, ornull. -
legendPosition
-
showDataLabels
public boolean showDataLabels()Whether the chart shows data labels: set through the builder orsetShowDataLabels(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
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-1when it carries none. -
titleFormula
The cell reference the title follows (<c:strRef><c:f>), ornullfor a literal or absent title. -
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
-
valueAxisTitle
-
valueAxisMin
The explicit value-axis minimum, ornull(auto). -
valueAxisMax
The explicit value-axis maximum, ornull(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 viaChart.Builder.anchorOffsets(int, int, int, int)so the chart keeps its exact fractional placement / size. -
chartAreaFill
The chart-area fill color, ornull(default). ECMA-376 §21.2.2.198 spPr. -
chartAreaLineColor
The chart-area frame (border) line color, ornull(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 fromchartAreaFill()returningnull, which means "unset" and renders as the application-default opaque white. -
plotAreaFill
The plot-area fill color, ornull(default). -
plotAreaLineColor
The plot-area frame (border) line color, ornull(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 (mirrorschartAreaNoFill()). -
seriesCount
public int seriesCount() -
seriesName
The series name reference/text, ornull. -
seriesValues
The series values range reference (e.g.Sheet1!$B$2:$B$9). -
seriesCategories
The series categories range reference, ornull. -
seriesBubbleSizes
The series' bubble-size (Z) range reference (<c:bubbleSize>), ornullon anything but a bubble chart that declares one. -
seriesType
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").nullon an ordinary chart, wheretype()describes every series. Change it withsetSeriesType(int, String). -
seriesSecondaryAxis
public boolean seriesSecondaryAxis(int seriesIndex) Whether this series is plotted against the secondary value axis of a combination chart;falseon an ordinary chart. Change it withsetSeriesSecondaryAxis(int, boolean). -
seriesFill
The explicit per-series fill color, ornullwhen the series uses the theme default. The write counterpart isChart.Builder.series(String, String, String, Color)— this reader closes that read/write asymmetry (ECMA-376 §21.2.2.211 spPr). -
seriesPointFills
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
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
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.falsefor a chart that is not an of-pie at all — test withisOfPie()first. -
ofPieSplitType
The of-pie split rule as the format's own token —auto,cust,percent,posorval— ornullwhen 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
The count or threshold the split rule compares against (<c:splitPos>), ornullwhen absent. -
ofPieCustomSplit
public int[] ofPieCustomSplit()The zero-based point indices acustsplit puts in the second plot (<c:custSplit>); empty for every other rule. -
ofPieSecondPlotSize
The second plot's size as a percentage of the first (<c:secondPieSize>), ornullwhen absent. -
view3D
public int[] view3D()The chart's 3-D view angles (ECMA-376 §21.2.2.228view3D) as[rotX, rotY, depthPercent], ornullwhen the chart is not 3-D. The read-back counterpart ofChart.Builder.view3D(int, int, int). -
plotAreaLayout
public double[] plotAreaLayout()The manual plot-area layout (ECMA-376 §21.2.2.88manualLayout) as[x, y, w, h]in chart-relative fractions, ornullwhen the plot area is laid out automatically. Read-back ofChart.Builder.plotAreaLayout(double, double, double, double). -
legendLayout
public double[] legendLayout()The manual legend layout as[x, y, w, h]chart-relative fractions, ornullwhen the legend is placed automatically. Read-back ofChart.Builder.legendLayout(double, double, double, double). -
titleLayout
public double[] titleLayout()The manual title layout as[x, y, w, h]chart-relative fractions, ornullwhen the title is placed automatically. Read-back ofChart.Builder.titleLayout(double, double, double, double). -
seriesPointExplosions
The explicit per-slice explosion overrides of a series (pie/doughnut), keyed by 0-based point index (ECMA-376 §21.2.2.62dPt/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()isnulland 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 totrue. -
valueAxisVisible
public boolean valueAxisVisible()Whether the value (Y) axis is drawn. Defaults totrue. -
valueAxisGridlines
public boolean valueAxisGridlines()Whether the value (Y) axis draws major gridlines (<c:majorGridlines>). Defaults totrue; an imported chart reports what its file says. -
trendlines
The trendlines of a series (empty when none). -
seriesDataLabels
The series-level data labels (<c:dLbls>), ornullwhen the series carries none. Reproduce them on a rebuild viaChart.Builder.dataLabels(DataLabels)(ECMA-376 §21.2.2.49). -
errorBars
The error bars of a series, ornull. -
isExtendedChart
public boolean isExtendedChart()Whether this is a modern extended chart — the ISO/IEC 29500 Transitionalcx:chart-extension schema (waterfall, funnel, histogram, treemap, sunburst, box & whisker, region map). Such a chart carries a byte-exact apparatus (itschartExpart plus thechartColorStyle/chartStyleparts) which Excel requires intact to open the file; re-issue it verbatim throughChart.Builder.extendedApparatus(java.lang.String, java.lang.String, java.lang.String)when rebuilding, since the structured builder fields cannot reconstruct it. -
extendedChartExData
Base64 of the sourcexl/charts/chartEx*.xmlpart for an extended chart, ornullfor a classic chart. Pass toChart.Builder.extendedApparatus(java.lang.String, java.lang.String, java.lang.String). -
extendedColorsData
Base64 of the extended chart'schartColorStylepart, ornull. -
extendedStyleData
Base64 of the extended chart'schartStylepart, ornull. -
setTitle
Set (or clear withnull) the chart title. -
setLegend
-
setLegendVisible
Show or hide the legend without changing its position. -
setCategoryAxisVisible
Show or hide the category (X) axis. -
setValueAxisVisible
Show or hide the value (Y) axis. -
setValueAxisGridlines
Show or hide the value (Y) axis' major gridlines. -
setAutoTitle
Mark (or clear) the title as an Excel "auto" title. Whentruethe explicit title text is cleared and the app derives it from the series name. -
setSeriesFill
Set (or clear withnull) the explicit fill color of one series. -
setSeriesType
Move one series of a combo chart into the plot group of another type — the counterpart ofChart.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- whentypeis none of thoseIllegalStateException- when the chart is not a combo, or when a series of another axis kind is on the same axis
-
setSeriesSecondaryAxis
Plot one series of a combo chart against the secondary value axis (on) or the primary one — the counterpart ofChart.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
Show value labels on every series, or (withfalse) remove every data label from the chart, series and point labels included — Excel's Data Labels > None. -
setThreeD
-
setGapWidth
-
setOverlap
-
setHoleSize
-
setCategoryAxisTitle
Set (or clear withnull) the category-axis title. -
setValueAxisTitle
Set (or clear withnull) the value-axis title. -
setValueAxisScale
-
setAnchor
Move / resize the chart's two-cell anchor. -
setSeries
Replace the name / values / categories references of one series. -
addTrendline
Add a trendline to a series. -
clearTrendlines
Remove every trendline from a series. -
setErrorBars
Set (or remove withnull) the error bars of a series. -
setSeriesDataLabels
Set (or remove withnull) the data labels of a series.
-