Chart axes and elements

getChartAxes(c::Chart) -> Vector{ChartAxis}
getChartAxes(c::Chart, role::Symbol) -> Vector{ChartAxis}

Axes of c, in c:plotArea document order. role is :category, :value, :date or :series and filters by axis kind; a combo chart has two value axes, so this returns a vector rather than one axis.

Axes with c:delete val="1" are included. Excel does not draw them, but they remain in the XML and remain formattable — check ax.deleted to skip them.

getChartAxis(c::Chart, axid::Integer) -> ChartAxis

The axis with c:axId equal to axid. This is the identifier chart groups and c:crossAx use, so it is how you get from a series group, or from one axis, to its partner.

getAxisPartner(c::Chart, ax::ChartAxis) -> Union{Nothing,ChartAxis}

The axis that ax crosses (c:crossAx). nothing if unwritten or dangling.

getAxisShapeProps(c::Chart, ax::ChartAxis) -> Union{Nothing,DrawingShapeProps}

Fill and line for the axis itself (c:spPr) — the axis line and its tick marks. nothing means no c:spPr was written, so Excel takes the formatting from the chart style. Gridlines are separate; see getAxisGridlines.

getAxisTextProps(c::Chart, ax::ChartAxis) -> Union{Nothing,DrawingText}

Text body for the axis tick labels (c:txPr). nothing means none was written. The axis title's text is separate; see getAxisTitleText.

getAxisGridlines(c::Chart, ax::ChartAxis; minor=false) -> Union{Nothing,DrawingShapeProps}

Line properties for the axis gridlines (c:majorGridlines, or c:minorGridlines when minor is true).

nothing means no gridlines element, so none are drawn. An element present with no c:spPr means gridlines are drawn with inherited formatting, and comes back as a DrawingShapeProps with every field absent — so isnothing answers "are there gridlines?" and the returned value answers "how are they formatted?".

getAxisTitleText(c::Chart, ax::ChartAxis) -> Union{Nothing,DrawingText}

The axis title's text body (c:title/c:tx/c:rich). nothing means no title element, or a title that references a cell rather than carrying literal text — c:tx/c:strRef — which this does not resolve.

getAxisTitleRef(c::Chart, ax::ChartAxis) -> Union{Nothing,String}

The formula behind an axis title that references a cell (c:title/c:tx/c:strRef/c:f). nothing for a literal or absent title.

getAxisTitleTextProps(c::ChartEx, id::Integer) -> Union{Nothing, DrawingText}

The text body of the axis title, or nothing if the axis has no title.

setAxisTitleText(c, ax::ChartAxis, text) -> Chart

Replace an axis title's text and all its formatting. As setChartTitleText, including that a cell reference is replaced by literal text.

A title created here gets c:overlay val="0", as Excel writes on every title it creates, so it sits beside the plot area rather than over it.

setAxisTitleTextProp(c, ax::ChartAxis, field, value) -> Chart

Set one text property of an axis title. As setChartTitleTextProp.

setAxisTitleTextProp(c::ChartEx, id::Integer, field, value) -> ChartEx

Set one field of an axis title's text formatting, on cx:axis/cx:title/cx:txPr. id is the axis' id attribute, as getChartAxisIds reports it, not a position. Creates the title if the axis has none. Returns c, which remains valid.

getAxisNumberFormatCode(c::Chart, ax::ChartAxis) -> Union{Nothing,String}

The format code from c:numFmt/@formatCode. Ignored by Excel when getAxisNumberFormatLinked is true.

getAxisNumberFormatLinked(c::Chart, ax::ChartAxis) -> Union{Nothing,Bool}

c:numFmt/@sourceLinked. true means Excel takes the number format from the source cells and ignores the axis's own format code. nothing means no c:numFmt element was written.

getAxisMajorTickMark(c::Chart, ax::ChartAxis) -> Union{Nothing,Symbol}

c:majorTickMark — :cross, :in, :out or :none.

getAxisMinorTickMark(c::Chart, ax::ChartAxis) -> Union{Nothing,Symbol}

c:minorTickMark — :cross, :in, :out or :none.

getAxisTickLabelPos(c::Chart, ax::ChartAxis) -> Union{Nothing,Symbol}

c:tickLblPos — :high, :low, :nextTo or :none.

getAxisOrientation(c::Chart, ax::ChartAxis) -> Union{Nothing,Symbol}

c:scaling/c:orientation — :minMax for a normal axis, :maxMin for one plotted in reverse order.

Throws if the axis has no c:scaling: the schema requires it, so its absence means a malformed chart part rather than an inherited value.

getAxisMin(c::Chart, ax::ChartAxis) -> Union{Nothing,Float64}

Fixed lower bound from c:scaling/c:min. nothing means Excel scales the axis automatically, which is the usual case; a value means the user fixed the bound.

getAxisMax(c::Chart, ax::ChartAxis) -> Union{Nothing,Float64}

Fixed upper bound from c:scaling/c:max. nothing means automatic.

getAxisLogBase(c::Chart, ax::ChartAxis) -> Union{Nothing,Float64}

c:scaling/c:logBase. nothing means a linear axis.

getAxisCrosses(c::Chart, ax::ChartAxis) -> Union{Nothing,Symbol}

Where this axis crosses its partner (c:crosses), as a position on the partner: :autoZero, :min or :max. Mutually exclusive with getAxisCrossesAt — at most one of the two is non-nothing.

Excel's "Horizontal axis crosses: At maximum category", set in the category axis's pane, is stored on the value axis.

getAxisCrossesAt(c::Chart, ax::ChartAxis) -> Union{Nothing,Float64}

Where this axis crosses its partner, as a value on the partner's scale (c:crossesAt). Mutually exclusive with getAxisCrosses.

getAxisCrossBetween(c::Chart, ax::ChartAxis) -> Union{Nothing,Symbol}

c:crossBetween — :between if the partner axis crosses between categories, :midCat if it crosses at their midpoints. Value axes only.

getAxisMajorUnit(c::Chart, ax::ChartAxis) -> Union{Nothing,Float64}

Interval between major ticks and gridlines (c:majorUnit). nothing means Excel chooses automatically. Value and date axes only.

getAxisMinorUnit(c::Chart, ax::ChartAxis) -> Union{Nothing,Float64}

Interval between minor ticks (c:minorUnit). Value and date axes only.

getAxisLabelAlign(c::Chart, ax::ChartAxis) -> Union{Nothing,Symbol}

c:lblAlgn — :ctr (centre), :l (left) or :r (right). Category and date axes only.

getAxisLabelOffset(c::Chart, ax::ChartAxis) -> Union{Nothing,Int}

c:lblOffset — distance of the labels from the axis, as a percentage between 0 and 1000. Category and date axes only.

getAxisMultiLevelLabels(c::Chart, ax::ChartAxis) -> Union{Nothing,Bool}

Whether multi-level category labels are shown. This inverts the XML: the element is c:noMultiLvlLbl, so val="1" means labels are not multi-level and this returns false. Category and date axes only.

setAxisTickLabelPos(c, ax, pos) -> Chart

Set where the axis's tick labels are drawn (c:tickLblPos): :nextTo the axis, at the :low or :high end of the crossing axis, or :none. :inherit removes the element.

:low keeps a category axis's labels at the edge of the plot area when the value axis has negative values, rather than beside the zero line.

setAxisScaling(c, ax; orientation, min, max) -> Chart

Set several c:scaling properties in one rebuild. A keyword left unspecified is left alone; :inherit removes it.

• orientation — :minMax, or :maxMin to plot the axis in reverse order.
• min, max — fixed bounds, in the axis's own units. :inherit returns a bound to automatic.

Throws if the resulting bounds would have min ≥ max. Checking once all keywords are applied means a range can be moved in one call past its old bounds, which separate setAxisMin and setAxisMax calls might not allow.

Throws if the axis has no c:scaling; see getAxisOrientation.

setAxisMin(c, ax, value) -> Chart

Fix the axis's lower bound (c:scaling/c:min); :inherit returns it to automatic. See setAxisScaling to set both bounds at once.

setAxisMax(c, ax, value) -> Chart

Fix the axis's upper bound (c:scaling/c:max); :inherit returns it to automatic. See setAxisScaling to set both bounds at once.

setAxisOrientation(c, ax, orientation) -> Chart

:minMax for a normal axis, :maxMin to plot it in reverse order — Excel's "Categories in reverse order" or "Values in reverse order". :inherit removes the element.

Reversing a bar chart's category axis moves the value axis to the other end; setAxisCrosses(c, valax, :max) moves it back.

setAxisCrosses(c, ax, rule) -> Chart

Set where this axis crosses its partner (c:crosses), as a position on the partner: :autoZero, :min or :max. Removes any c:crossesAt, since the schema allows one or the other. :inherit removes c:crosses only.

Excel's "Horizontal axis crosses: At maximum category", set in the category axis's pane, is written on the value axis: setAxisCrosses(c, valax, :max).

setAxisCrossesAt(c, ax, value) -> Chart

Set where this axis crosses its partner as a value on the partner's scale (c:crossesAt). Removes any c:crosses. :inherit removes c:crossesAt only.

setAxisNumberFormatCode(c, ax, code) -> Chart

Set the axis's number format (c:numFmt/@formatCode) and unlink it from the source cells (sourceLinked="0"), without which Excel ignores the code. :inherit removes c:numFmt.

A two-section code such as "0%;0%" shows negative values without a minus sign.

setAxisNumberFormatLinked(c, ax, linked::Bool) -> Chart

Set c:numFmt/@sourceLinked, keeping the current format code, or "General" if none was written.

setAxisMajorTickMark(c, ax, mark) -> Chart

Set the axis's major tick marks (c:majorTickMark): :out, :in, :cross or :none, or Excel's :outside and :inside. :inherit removes the element.

setAxisMinorTickMark(c, ax, mark) -> Chart

As setAxisMajorTickMark, for c:minorTickMark.

setAxisGridlines(c, ax; major, minor) -> Chart

Show (true) or remove (false) the axis's major and minor gridlines. A gridline element's presence is the switch, so false removes it rather than writing an "off" value; a newly shown set takes its line from the chart style. A keyword left unspecified is left alone.

setAxisTextProp(c, ax, field, value) -> Chart

Set one text property of the axis's tick labels (c:txPr on the axis). Takes the same fields and values as setLegendTextProp.

setAxisLine(c, ax; color, width, dash, cap, compound, join, miterLimit) -> Chart
setAxisLine(c, ax, :none)
setAxisLine(c, ax, :inherit)

Set the axis line, as setSeriesLine sets a series outline: several properties in one rebuild, :none for a line that draws nothing, :inherit to remove it so the chart style supplies it.

setAxisMajorUnit(c, ax, value) -> Chart

Set the interval between major ticks and gridlines (c:majorUnit), in the axis's own units; :inherit returns it to automatic. Value and date axes only.

Ticks start at the axis minimum, so a minimum that is a multiple of the unit puts a tick at zero.

setAxisMinorUnit(c, ax, value) -> Chart

As setAxisMajorUnit, for the interval between minor ticks (c:minorUnit).

getSeriesDataPoints(c::Chart, i::Integer) -> Vector{ChartDataPoint}

Per-point overrides on series i, in document order. Usually empty, or short — only points the user formatted individually appear.

getSeriesDataPoint(c::Chart, i::Integer, point::Integer) -> Union{Nothing,ChartDataPoint}

The override for data point point of series i, counting from 1, or nothing if that point has no individual formatting.

getDataPointShapeProps(c::Chart, d::ChartDataPoint) -> Union{Nothing,DrawingShapeProps}

Fill and line overriding the series' own, for one data point (c:dPt/c:spPr). nothing means the point writes no c:spPr, so the series' formatting applies; getSeriesFill resolves that cascade.

getDataPointMarker(c::Chart, d::ChartDataPoint) -> Union{Nothing,ChartMarker}

Marker override for a single data point (c:dPt/c:marker). nothing means the point does not override the series marker — the series-level getSeriesMarker applies.

getMarkerFill(c::Chart, i::Integer, point::Integer) -> Effective{DrawingFill}

Resolve the fill of a data point's marker: c:dPt/c:marker/c:spPr, then c:ser/c:marker/c:spPr.

Both lookups are anchored on c:ser and c:dPt, where c:marker is marker properties. Under a group element the same tag is a boolean show-markers flag, so this must not be generalised to walk up from a group.

setMarker(c, i; point, symbol, size, fill, lineColor, lineWidth) -> Chart

Set several marker properties at once, in one rebuild of the chart part. Sets the marker for series i, or overrides it for one of its data points when point is given, counting from 1.

A keyword left unspecified is left alone; pass :inherit to remove one that is set. Each keyword takes the values its single-property setter does: setMarkerSymbol, setMarkerSize, setMarkerFill, setMarkerLineColor and setMarkerLineWidth.

Nothing is written if every property keyword is nothing.

Example

setMarker(c, 1; symbol = :circle, size = 7, fill = "FF0000", lineColor = :none)

setMarkerSymbol(c, i, symbol; point = nothing) -> Chart

Set the marker shape for series i, or for one of its data points when point is given, counting from 1. One of :circle, :dash, :diamond, :dot, :none, :picture, :plus, :square, :star, :triangle, :x or :auto.

:none draws no marker and :auto lets Excel choose; both are settings. :inherit removes the element so the chart style decides.

setMarkerSize(c, i, size; point = nothing) -> Chart

Set the marker size for series i, or for one of its data points when point is given, counting from 1. In points, rounded to the nearest whole point. DrawingML allows 2 to 72; anything outside that is rejected rather than written. :inherit removes the setting so the chart style decides.

One of the single-property marker setters; setMarker sets several at once in a single rebuild.

setMarkerFill(c, i, color; point = nothing) -> Chart

Set the fill of series i's marker, or of one data point's when point is given, counting from 1. Takes the same values as setSeriesFill: a colour, a SchemeColor, :none for an explicit <a:noFill/>, or :inherit to remove it.

One of the single-property marker setters; see setMarker.

setMarkerLineColor(c, i, color; point = nothing) -> Chart

Set the outline colour of series i's marker, or of one data point's when point is given, counting from 1. Takes the same values as setSeriesFill: a colour, a SchemeColor, :none for an explicit <a:noFill/>, or :inherit to remove it.

As with setSeriesLineColor, :none leaves the outline in place drawing nothing, which is not the same as removing it.

One of the single-property marker setters; see setMarker.

setMarkerLineWidth(c, i, width; point = nothing) -> Chart

Set the outline width of series i's marker, or of one data point's when point is given, counting from 1. In points. :inherit removes the width.

DrawingML caps a line width at 1584 pt; a wider one is rejected rather than written.

One of the single-property marker setters; see setMarker.

getSeriesDataLabels(c::Chart, i::Integer) -> Vector{ChartDataLabel}

Individual label overrides on series i, in document order. Usually empty.

getSeriesDataLabel(c::Chart, i::Integer, point::Integer) -> Union{Nothing,ChartDataLabel}

The label override for data point point of series i, counting from 1, or nothing if that label is not individually formatted.

getDataLabelText(c::Chart, d::ChartDataLabel) -> Union{Nothing,DrawingText}

Literal replacement text for one label (c:dLbl/c:tx/c:rich). nothing means the label shows its value rather than typed-over text. Contrast getDataLabelTextProps, which is the label's c:txPr formatting.

getDataLabelTextProps(c::Chart, d::ChartDataLabel) -> Union{Nothing,DrawingText}

Text body for one label (c:dLbl/c:txPr) — its formatting. nothing means the label writes none, so the series' getSeriesLabelTextProps applies. Contrast getDataLabelText, which is typed-over text.

getDataLabelShapeProps(c::Chart, d::ChartDataLabel) -> Union{Nothing,DrawingShapeProps}

Fill and border of one label's box (c:dLbl/c:spPr). nothing means none was written.

getDataLabelPosition(c::Chart, d::ChartDataLabel) -> Union{Nothing,Symbol}

c:dLblPos — :ctr (centre), :inEnd (inside-end), :inBase (inside-base), :outEnd (outside-end), :l (left), :r (right), :t (above), :b (below), :bestFit. Which values are legal depends on the chart type.

getDataLabelOffset(c::Chart, d::ChartDataLabel) -> Union{Nothing,NamedTuple}

Manual position offset (c:dLbl/c:layout/c:manualLayout) as (x, y), fractions of the plot area, signed. nothing means the label sits where Excel puts it. Distinct from getDataLabelPosition, which is the discrete c:dLblPos enum — Excel writes a layout offset when you drag a label and a position when you pick one from the menu, so a label usually has one or neither.

getLabelTextProp(c::Chart, i::Integer, field::Symbol) -> Effective

Resolve one field of the data-label text formatting for series i, walking c:txPr from the series up through the group, plot area and chart space.

field is a field of DrawingRunProps other than raw. Text inherits field by field — a size from one rung and a weight from another both apply — which is why this resolves a named field rather than a whole DrawingRunProps.

Two fields are composite: :fill and :line resolve to a whole DrawingFill or DrawingLine. They inherit as units — a run's fill is written at some rung or it is not — so there is no cascade below them, and resolving through to .fgcolor or .width is a field access on the result, not a further walk.

A rung whose txPr exists but sets nothing (an empty a:defRPr, which Excel writes at the chart space) does not answer: the walk continues, and a field set at no rung resolves to nothing, meaning Excel takes it from the chart style.

getLabelTextProp(c::ChartEx, i::Integer, field::Symbol; pareto=false) -> Effective

Resolve one field of the data-label text formatting for series i, walking cx:dataLabels/cx:txPr then cx:chartSpace/cx:txPr. With pareto = true, series i's Pareto line instead; an error if it has none. See the Chart method for how fields inherit.

setLabelText(c, i, point, text) -> Chart

Replace one data label's typed-over text and all its formatting, so the label shows text instead of its value.

If the point has no c:dLbl, one is created with the same show* flags as its c:dLbls. Typed text is displayed whatever those flags say, so this shows the label even on a series whose labels are off.

setLabelTextProp(c, i, field, value) -> Chart
setLabelTextProp(c, i, point, field, value) -> Chart

Set one text property of series i's data labels, or of one individual label. field is a field of DrawingRunProps other than raw — the same vocabulary getLabelTextProp resolves. :inherit removes it.

Creating a c:dLbls where none existed writes every show* flag as off, so formatting a series' labels does not make them appear. A c:dLbls that names no flags shows labels with Excel's own defaults — legend key, series name and value — which would turn them on for a series that had none.

The per-point form creates the individual c:dLbl if the point has none, placed in index order and carrying the same show* flags as its c:dLbls, so it displays exactly what its sibling labels display. Formatting one label on a series whose labels are off does not make that label appear.

Two fields take compound values. :fill accepts anything setSeriesFill does — a color, a SchemeColor, :none or :inherit. :line accepts a color, or a NamedTuple of the setSeriesLine keywords: (color = "red", width = 1.5).

A label that has been deleted carries only c:delete and cannot be formatted — undeleting it is a separate operation.

setLabelTextProp(c::ChartEx, i, field, value; pareto=false) -> ChartEx

Set one field of the data-label text formatting for series i, writing it on the series' cx:dataLabels/cx:txPr. field is a field of DrawingRunProps; :fill and :line are composite and take a colour or a named tuple of line properties. Pass :inherit to remove a field so the cascade resolves it. With pareto = true, series i's Pareto line instead; an error if it has none.

Creating a cx:dataLabels to hold formatting writes cx:visibility with all three flags off, since one that names no flags shows labels with Excel's defaults rather than none.

Returns c, which remains valid.

setLabelDeleted(c, i, point, deleted::Bool) -> Chart

Delete or undelete the data label of point point (counting from 1) of series i.

Deleting writes a c:dLbl carrying only c:idx and c:delete, replacing any individual formatting or typed text the label had: the schema makes c:delete exclusive of every display property. Undeleting removes that c:dLbl, so the point shows whatever its series' c:dLbls does. Undeleting a label that is not deleted does nothing.

getSeriesTrendlines(c::Chart, i::Integer) -> Vector{ChartTrendline}

Trendlines on series i, in document order. A series can carry several — a linear fit and a moving average, say — so this returns a vector. Usually empty.

getTrendlineShapeProps(c::Chart, t::ChartTrendline) -> Union{Nothing,DrawingShapeProps}

Line properties of the trendline itself (c:trendline/c:spPr). Trendlines are lines, so the fill is normally absent; the dash pattern lives in line.dash.

getTrendlineLabelText(c::Chart, t::ChartTrendline) -> Union{Nothing,DrawingText}

Literal text of the trendline's on-chart label (c:trendlineLbl/c:tx/c:rich). nothing means the label shows Excel's generated equation or R² rather than typed-over text — or that there is no label at all. Contrast getTrendlineLabelTextProps, which is the label's c:txPr formatting.

getTrendlineLabelTextProps(c::Chart, t::ChartTrendline) -> Union{Nothing,DrawingText}

Formatting of the trendline label (c:trendlineLbl/c:txPr).

getTrendlineLabelShapeProps(c::Chart, t::ChartTrendline) -> Union{Nothing,DrawingShapeProps}

Fill and border of the trendline label's box (c:trendlineLbl/c:spPr).

getSeriesErrorBars(c::Chart, i::Integer) -> Vector{ChartErrorBars}

Error bars on series i, in document order. A series carries at most two, one for each of the x and y directions.

getErrorBarsShapeProps(c::Chart, e::ChartErrorBars) -> Union{Nothing,DrawingShapeProps}

Line properties of the error bars (c:errBars/c:spPr).

getErrorBarsCustomRefs(c::Chart, e::ChartErrorBars) -> NamedTuple

The sheet references behind custom error bars, as (plus, minus), each a ChartRef or nothing.

Only errValType="cust" bars carry these; every other value type takes its magnitude from ChartErrorBars.value instead, and this returns (nothing, nothing). Excel writes both c:plus and c:minus even for one-sided bars, so a nothing here means the element was genuinely absent.

Cached values are always read, whatever read_cached_values is passed to getChartSeries — these ranges are short, so there is nothing to save by skipping them.