Charts

XLSX.Charts

Reading, formatting and creating Excel charts, in both chart schemas: the c: schema (Chart) and the cx: chartEx schema (ChartEx).

using XLSX.Charts brings the chart functions into scope. The handle and value types are public but not exported; refer to them as XLSX.Charts.ChartSeries and so on.

Conventions shared by the functions:

• i is a series' position, counting from 1 in getChartSeries order, and point a data point's position in the series, also from 1.
• ax is a ChartAxis from getChartAxes or getChartAxis, and g a ChartGroup from getChartGroups. On a ChartEx, an axis is named by its id from getChartAxisIds.
• Setters return the chart. Most take :inherit to remove a setting so it is inherited from the chart style; each docstring says where it does.
• Color values are listed at setSeriesFill, line keywords at setSeriesLine, and text-property fields at setChartTitleTextProp.

getCharts(xf::XLSXFile) -> Vector{AbstractChart}
getCharts(ws::Worksheet) -> Vector{AbstractChart}

Return every chart in the file, or every chart anchored to ws.

Each chart is a handle that reads its part on every call, so it stays valid across edits. Reading options belong to the accessors: series metadata without cached values is getChartSeries(c; read_cached_values=false).

A chart may reference an external workbook, in which case its source formula takes the form [1]Sheet1!$A$1:$A$10, where [1] indexes the workbook's external references. Pass get_external_refs=true to XLSX.Charts.getChartSeries or XLSX.Charts.getChartData to substitute the workbook path, as XLSX.getFormula does.

Examples

julia> f = XLSX.readxlsx("sales.xlsx");

julia> c = XLSX.Charts.getCharts(f["Summary"])[1];

julia> XLSX.Charts.getChartTitle(c)
"Revenue by region"

julia> XLSX.Charts.getChartSeries(c)[1].values.ref
"Summary!$B$2:$B$5"

# A DataFrame per chart, skipping chartEx charts, which carry no cached data
julia> dfs = Dict(c.name => DataFrame(XLSX.Charts.getChartData(c))
                  for c in XLSX.Charts.getCharts(f) if c isa XLSX.Charts.Chart)

See also XLSX.Charts.getChart, XLSX.Charts.getChartData, XLSX.Charts.getChartType.

getChart(ws::Worksheet, name) -> AbstractChart
getChart(xf::XLSXFile, name) -> AbstractChart

Return a single chart. name may be the part name ("chart1" or "chart1.xml"), the full package path, or the chart's relationship id within its drawing part ("rId1").

Returns a XLSX.Charts.ChartEx where the named part uses the chartEx schema. The returned handle reads the current part on every call, so it stays valid across edits. Options that affect reading, such as read_cached_values and get_external_refs, are taken by the accessors: see XLSX.Charts.getChartSeries and XLSX.Charts.getChartData.

See also XLSX.Charts.getCharts.

getChartSchema(c::AbstractChart) -> Symbol

:c for charts in the original schema, :cx for newer chartEx charts.

getChartType(c::AbstractChart) -> Symbol

The kind of chart, as a single symbol, whatever the schema.

For c: charts this is the plot-group tag - :barChart, :scatterChart - or :combo where the chart has more than one group. The full list is in getChartTypes(c), and each series carries its own group in s.charttype.

For cx: charts it is the normalised layout: :waterfall, :funnel, :treemap, :sunburst, :boxWhisker, :regionMap, :histogram, :pareto, or :clusteredColumn. Histogram and Pareto are not distinct layouts in the file - a histogram is a clustered column series carrying cx:binning, and a Pareto adds a second paretoLine series - so both are derived here.

getChartTitle(c::Chart) -> Union{Nothing,String}
getChartTitle(c::ChartEx) -> Union{Nothing,String}

The chart's title as plain text, whether typed into the chart or bound to a cell. A cell-bound title comes from the string Excel cached with the reference, so it is the text as of the last save rather than the cell's current value.

nothing where the chart has no title, where the title element carries no text of its own, or where Excel generates the title from the single series' name and so writes no text at all. Paragraphs are joined with newlines, as are the line breaks within one.

Returns text only. getChartTitleText gives a c: title's rich text with its formatting, getChartTitleRef the formula behind a cell-bound one, getChartTitleRange the same for a cx: chart, and getChartTitleTextProps the c:txPr or cx:txPr that formats it.

getChartData(c::Chart) -> DataTable
getChartData(ws::Worksheet, name) -> DataTable
getChartData(xf::XLSXFile, name) -> DataTable

Return the cached data of a chart as a DataTable, ready for DataFrame(...) or any other Tables.jl sink.

Categories become the leading column(s). Where every series shares one category reference a single categories column is emitted; otherwise each series contributes its own <series>_x column, which is the usual layout for scatter and bubble charts. Multi-level categories give one column per level, and bubble charts add a <series>_size column. Series of unequal length are padded with missing.

Series with no name in the file - Excel shows these as "Series1", "Series2" in the legend - are labelled by position. No category column is produced when the chart has no c:cat at all: Excel is plotting against an implicit index in that case, and nothing is cached for it.

Examples

julia> using DataFrames

julia> DataFrame(XLSX.Charts.getChartData(f["Summary"], "chart1"))
4×3 DataFrame
 Row │ categories  2024      2025
     │ String      Float64   Float64

See also XLSX.Charts.getCharts, XLSX.gettable.

getChartData(c::ChartEx)

chartEx charts do not carry a readable value cache. Throws XLSX.XLSXError.

getChartRanges(c::Chart) -> Vector{ChartRanges}
getChartRanges(c::ChartEx) -> Vector{ChartRange}
getChartRanges(ws::Worksheet, name) -> Vector
getChartRanges(xf::XLSXFile, name) -> Vector
getChartRanges(ws::Worksheet) -> Vector{@NamedTuple{chart::String, ranges::Vector}}
getChartRanges(xf::XLSXFile) -> Vector{@NamedTuple{chart::String, ranges::Vector}}

The worksheet ranges of the source data a chart plots from.

Given a XLSX.Charts.Chart, or a chart name in any of the forms XLSX.Charts.getChart accepts, return one entry per series in document order, parallel to getChartSeries(c). Each entry carries the series idx and name alongside its categories, values and bubble_sizes ranges.

Given no name, return the ranges of every chart on the worksheet or in the workbook, each paired with its chart name, following XLSX.Charts.getCharts.

categories holds c:cat or c:xVal and values holds c:val or c:yVal, so the two mean the same thing whatever the chart type, as in XLSX.Charts.ChartSeries. bubble_sizes is nothing for every chart type but bubble.

A range is nothing wherever the series has no addressable source: a literal series (c:numLit/c:strLit), a reference to an external workbook, a defined name.

Examples

julia> f = XLSX.readxlsx("sales.xlsx");

julia> r = XLSX.Charts.getChartRanges(f["Summary"], "chart1");

julia> r[1].name, r[1].values
("2024", Summary!B2:B5)

julia> XLSX.getdata(f, r[1].values)      # read the live source cells, not the cache
4-element Vector{Any}:
 1250.0
 1310.0
 ⋮

julia> [(x.chart, length(x.ranges)) for x in XLSX.Charts.getChartRanges(f)]
2-element Vector{Tuple{String, Int64}}:
 ("chart1", 3)
 ("chart2", 1)

See also XLSX.Charts.getChart, XLSX.Charts.getCharts, XLSX.Charts.getChartData.

getChartTypes(c::Chart) -> Vector{Symbol}

The tag of each chart-type group in c:plotArea, in document order: :barChart, :lineChart and so on. One entry per group, duplicates kept — a primary and a secondary bar group both appear — and groups holding no series are included. Contrast getChartType, which names the chart as a whole.

getChartGroups(c::Chart) -> Vector{ChartGroup}

The chart-type groups in c:plotArea, in document order. A combo chart has several; a plain chart has one. Use getGroupAxes to find which axes a group's series are plotted against.

getChartLegend(c::Chart) -> Union{Nothing,XML.Node}

The c:legend element, or nothing if the chart has no legend. Returned as a node because the legend carries no identity of its own — pass it to getLegendShapeProps and friends, or read it directly.

getLegendPos(c::Chart) -> Union{Nothing,Symbol}
getLegendPos(c::ChartEx) -> Union{Nothing,Symbol}

:b (bottom), :t (top), :l (left), :r (right) or :tr (top-right) from c:legendPos, or from cx:legend's pos and align. nothing means no legend, or a legend with no explicit position. Set with setLegendPos.

setLegendPos(c::Chart, pos; overlay=nothing) -> Chart
setLegendPos(c::ChartEx, pos; overlay=nothing) -> ChartEx

Set where the legend is drawn: :b (bottom), :t (top), :l (left), :r (right) or :tr (top-right) — Excel's five legend positions. :bottom, :top, :left, :right and :topRight are accepted too. :inherit removes the position, which Excel reads as :r.

overlay also sets setLegendOverlay: true draws the legend over the plot area, false beside it, shrinking the plot area to make room. nothing leaves it as it is.

Creates the legend if the chart has none. On a Chart, any manual layout on the legend (c:legend/c:layout, written when a legend is dragged in Excel) is removed so that the position takes effect, as picking a position in Excel does.

getLegendOverlay(c::Chart) -> Union{Nothing,Bool}
getLegendOverlay(c::ChartEx) -> Union{Nothing,Bool}

c:overlay, or cx:legend's overlay attribute — true where the legend is drawn on top of the plot area rather than beside it. nothing means the chart has no legend, or the element was not written, in which case Excel treats it as false.

setLegendOverlay(c::Chart, overlay) -> Chart
setLegendOverlay(c::ChartEx, overlay) -> ChartEx

true draws the legend over the plot area; false draws it beside the plot area, which shrinks to make room — Excel's "Show the legend without overlapping the chart". :inherit removes the setting, which Excel reads as false. Creates the legend if the chart has none.

getLegendShapeProps(c::Chart) -> Union{Nothing,DrawingShapeProps}

Fill and border of the legend box (c:legend/c:spPr). nothing means the chart has no legend, or none was written.

getLegendTextProps(c::Chart) -> Union{Nothing,DrawingText}
getLegendTextProps(c::ChartEx) -> Union{Nothing,DrawingText}

Text body for the legend entries (c:legend/c:txPr). nothing means the chart has no legend, or none was written.

setLegendTextProp(c, field, value) -> Chart

Set one text property of the legend (c:legend/c:txPr). A legend takes its text from the series names, so there is no c:tx to replace — only its formatting is settable.

field is one of :lang, :size, :bold, :italic, :under, :strike, :caps, :baseline, :kern, :spacing, :fill, :line, :latin, :ea, :cs, or Excel's names :color (= :fill), :font (= :latin), :strikethrough (= :strike), :underline (= :under). value depends on the field — see the table at setChartTitleTextProp — and :inherit removes the field so it is inherited.

setLegendTextProp(c::ChartEx, field, value) -> ChartEx

Set one field of the legend's text formatting, on cx:legend/cx:txPr. Creates the legend if the chart has none. Returns c, which remains valid.

field is one of :lang, :size, :bold, :italic, :under, :strike, :caps, :baseline, :kern, :spacing, :fill, :line, :latin, :ea, :cs, or Excel's names :color (= :fill), :font (= :latin), :strikethrough (= :strike), :underline (= :under). value depends on the field — see the table at setChartTitleTextProp — and :inherit removes the field so it is inherited.

getLegendEntryDeleted(c::Chart, i::Integer) -> Union{Nothing,Bool}

Whether series i's legend entry is hidden (c:legendEntry/c:delete). nothing means the chart has no legend, series i has no c:legendEntry, or the entry carries text formatting instead, which the schema allows in place of c:delete; in all three cases the entry is shown.

A legend entry is keyed by its series' c:idx, which this finds from the position.

setLegendEntryDeleted(c, positions, deleted) -> Chart

Hide (true) or show (false) the legend entries of the series at positions — a single position or any collection of them — in one rebuild of the chart part. :inherit removes their c:legendEntry elements, so the entries show with the legend's own formatting.

Replacing an entry discards any text formatting it carried: the schema allows an entry either c:delete or c:txPr, not both.

Throws if the chart has no legend, rather than adding one.

Hiding entries is how to show a legend in an order other than series order: add series with zero values in the wanted order, format them to match, and hide the entries of the series that draw the data.

getChartTitleText(c::Chart) -> Union{Nothing,DrawingText}

Literal title text (c:title/c:tx/c:rich). nothing if there is no title element, or the title references a cell rather than carrying literal text — see getChartTitleRef — or c:autoTitleDeleted is 0 and Excel generates the title from the series name, in which case no text exists in the file at all.

getChartTitleRef(c::Chart) -> Union{Nothing,String}
getChartTitleRef(c::ChartEx) -> Union{Nothing,String}

The formula behind a title that references a cell, as written (c:title/c:tx/c:strRef/c:f, or cx:txData/cx:f). nothing for a literal or absent title. Excel writes a cx: formula as a hidden _xlchart.* defined name; getChartTitleRange resolves it.

getChartTitleShapeProps(c::Chart) -> Union{Nothing,DrawingShapeProps}

Fill and border of the title box (c:title/c:spPr). nothing means there is no title element, or none was written.

getChartTitleTextProps(c::Chart) -> Union{Nothing,DrawingText}
getChartTitleTextProps(c::ChartEx) -> Union{Nothing,DrawingText}

Text body for the title (c:title/c:txPr) — its formatting, which applies whether the title is typed, bound to a cell or generated by Excel. Contrast getChartTitleText, which is the literal text in c:tx/c:rich.

getAutoTitleDeleted(c::Chart) -> Union{Nothing,Bool}

c:autoTitleDeleted — true where the user removed the title Excel would otherwise generate from the single series' name. nothing means the element was not written, which Excel treats as false.

setChartTitleText(c, text) -> Chart
setChartTitleText(c, ref::Union{CellRef,SheetCellRef}) -> Chart

Replace the chart title's text and all its formatting. text may be a DrawingText, a string, which becomes a one-run title inheriting its formatting from the chart style, or a RichTextString, whose runs keep their own formatting and inherit the rest. A newline starts a new paragraph. A styled string from StyledStrings.jl (styled"…", Julia 1.11 and later) is converted to a RichTextString as it is when written to a cell.

This replaces rather than merges, like writing a RichTextString to a cell — use setChartTitleTextProp to change one property and leave the rest.

Given a CellRef or SheetCellRef, the title is bound to that cell (c:tx/c:strRef) and shows its text, with the cell's current value cached as Excel does. A bare CellRef means the chart's own sheet; a chart on a chartsheet needs a SheetCellRef. A string is always typed text, never read as a reference — "Q1" is a valid title.

A bound title can't carry rich text: this is a limit of Excel's file format, in which c:tx holds either a reference or typed runs, never both. Its one style is c:title/c:txPr. Binding a typed title moves its formatting there — the first paragraph's, overlaid by its first run's — and, where the cell holds a RichTextString, the formatting all of its runs share is laid over that. Formatting that varies between the cell's runs is not shown.

Typing text over a bound title replaces the reference. c:autoTitleDeleted is not touched, so a chart with the title switched off stays that way.

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.

setChartTitleText(c::ChartEx, text) -> ChartEx
setChartTitleText(c::ChartEx, ref::Union{CellRef,SheetCellRef}) -> ChartEx

Set the chart title to text, typed rather than bound to a cell. Creates the title if the chart has none, and drops any cx:f binding it had. A newline starts a new paragraph.

Excel stores a typed title both as cx:tx/cx:txData/cx:v and as runs in the title's cx:txPr, and renders the latter, so both are updated. Run formatting is preserved; use setChartTitleTextProp to change it. A RichTextString, or a styled string from StyledStrings.jl (Julia 1.11 and later), lays each run's own formatting over it.

Given a CellRef or SheetCellRef, the title is bound to that cell (cx:txData with cx:f and the cell's text cached in cx:v). A bare CellRef means the chart's own sheet; a chart on a chartsheet needs a SheetCellRef. A string is always typed text, never read as a reference.

A bound title can't carry rich text, a limit of Excel's file format. Binding keeps the title's formatting in cx:txPr — its first run's, folded into the paragraph default — and, where the cell holds a RichTextString, lays over it the formatting all of its runs share.

Returns c, which remains valid.

setChartTitleTextProp(c, field, value) -> Chart

Set one text property of the chart title, such as its size or color, leaving the others as they are.

Fields

These are the fields and values of every text-property setter: setLabelTextProp, setGroupLabelTextProp, setChartSpaceTextProp, setAxisTitleTextProp, setAxisTextProp and setLegendTextProp. Each field is a field of DrawingRunProps, and getters such as getLabelTextProp report it under that name; the Excel names in brackets are accepted as well.

Every field also takes :inherit, which removes it so it is inherited from the next level up — for a title, the chart space, then the chart style. The :under, :strike and :caps words may be Strings as well as Symbols; any other word is rejected, since Excel will not open a file containing one.

A title carries formatting in c:title/c:txPr and, when it holds literal text, in c:title/c:tx/c:rich as well — Excel renders the rich one, so both are written. Contrast setChartTitleText, which replaces the text and all its formatting.

Example

setChartTitleTextProp(c, :size, 16)
setChartTitleTextProp(c, :color, "accent2")
setChartTitleTextProp(c, :font, "Georgia")

setChartTitleTextProp(c::ChartEx, field, value) -> ChartEx

Set one field of the chart title's text formatting, on cx:title/cx:txPr. Creates the title if the chart has none. Returns c, which remains valid.

field is one of :lang, :size, :bold, :italic, :under, :strike, :caps, :baseline, :kern, :spacing, :fill, :line, :latin, :ea, :cs, or Excel's names :color (= :fill), :font (= :latin), :strikethrough (= :strike), :underline (= :under). value depends on the field — see the table at setChartTitleTextProp — and :inherit removes the field so it is inherited.

getPlotAreaShapeProps(c::Chart) -> Union{Nothing,DrawingShapeProps}

Fill and border of the plot area (c:plotArea/c:spPr) — the region the data is drawn in, inside the axes. nothing means none was written.

getChartSpaceShapeProps(c::Chart) -> Union{Nothing,DrawingShapeProps}

Fill and border of the chart as a whole (c:chartSpace/c:spPr) — the outer frame, not the plot area. nothing means none was written.

getChartSpaceTextProps(c::Chart) -> Union{Nothing,DrawingText}

Text body at the chart space (c:chartSpace/c:txPr), the default every other text element inherits from and the last rung of the text cascade; see getLabelTextProp. nothing means none was written.

setChartSpaceTextProp(c, field, value) -> Chart

Set one text property on c:chartSpace/c:txPr — the bottom rung of the text cascade, which every text body in the chart inherits from unless it overrides. This is the way to set one font or size for the whole chart.

field is one of :lang, :size, :bold, :italic, :under, :strike, :caps, :baseline, :kern, :spacing, :fill, :line, :latin, :ea, :cs, or Excel's names :color (= :fill), :font (= :latin), :strikethrough (= :strike), :underline (= :under). value depends on the field — see the table at setChartTitleTextProp — and :inherit removes the field so it is inherited.

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

Set the border of the plot area (c:plotArea/c:spPr/a:ln), as setSeriesLine sets a series outline: several properties in one rebuild, :none for a border that draws nothing, :inherit to remove it so the chart style supplies it.

Keywords are color, width, dash, cap, compound, join and miterLimit, each taking the values listed at setSeriesLine. A keyword left unspecified is left alone.

getChartSeries(c::Chart; read_cached_values=true, get_external_refs=false) -> Vector{ChartSeries}

The series of c, in document order across all chart groups. Each is a value identified by its idx; see ChartSeries."

read_cached_values=false reads metadata only: names, references and point counts, without the cached values. get_external_refs=true replaces an external workbook index such as [1] in each reference with the workbook's path.

getSeriesGroup(c::Chart, i::Integer) -> ChartGroup

The chart-type group containing series i.

getSeriesAxes(c::Chart, i::Integer) -> Vector{ChartAxis}

The axes series i is plotted against. This is how you tell a primary-axis series from a secondary-axis one: they sit in different groups naming different axis ids.

getSeriesShapeProps(c::Chart, i::Integer) -> Union{Nothing,DrawingShapeProps}

Fill, line and effects for the graphic of series i (c:ser/c:spPr), where i is a position in getChartSeries(c), not the c:idx value. nothing means no spPr was written, which in DrawingML means inherit from the chart style — not "no formatting". Contrast an explicit <a:noFill/>, which hasFill reports as deliberately off.

getSeriesFill(c::Chart, i::Integer; point=nothing) -> Effective{DrawingFill}

Resolve the fill of the graphic of series i, or of one data point of it.

This is always c:spPr. On a line or scatter series what Excel's format pane calls the point's fill lives on its marker instead — use getMarkerFill for that.

getSeriesFill(c::ChartEx, i::Integer; point=nothing, pareto=false) -> Effective{DrawingFill}

Resolve the fill of series i, or of one data point of it, walking cx:dataPt/cx:spPr then cx:series/cx:spPr. With pareto = true, series i's Pareto line instead; an error if it has none.

getSeriesLine(c::Chart, i::Integer; point=nothing) -> Effective{DrawingLine}

Resolve the outline of the graphic of series i, or of one data point of it.

getSeriesLine(c::ChartEx, i::Integer; point=nothing, pareto=false) -> Effective{DrawingLine}

Resolve the outline of series i, or of one data point of it, walking cx:dataPt/cx:spPr then cx:series/cx:spPr. With pareto = true, series i's Pareto line instead; an error if it has none.

getSeriesMarker(c::Chart, i::Integer) -> Union{Nothing,ChartMarker}

Marker for series i of a line, scatter or radar chart (c:ser/c:marker). nothing means no c:marker element; a marker whose symbol is :none is a marker explicitly turned off, which is a different thing.

getSeriesLabelTextProps(c::Chart, i::Integer) -> Union{Nothing,DrawingText}

Text body for the data labels of series i (c:ser/c:dLbls/c:txPr). Per-point overrides in c:dLbls/c:dLbl are not consulted; this is the series-level default.

setSeriesFill(c, i, color) -> Chart

Set the fill of series i's graphic — its bars, area or pie slices.

Color values

Every chart setter that takes a color — fills, lines, markers, the text :fill field and addSeries' color keyword — accepts the same values:

• a color name from Colors.jl, as a String or Symbol: "red", :steelblue;
• a hex string, "RRGGBB" or "AARRGGBB", with or without a leading #: "FF0000", "#FF0000", "80FF0000" (50% transparent red);
• a Colors.Colorant, such as colorant"red" or RGB(1, 0, 0);
• a theme color, named as a String or Symbol: :bg1, :tx1, :bg2, :tx2, :accent1, :accent2, :accent3, :accent4, :accent5, :accent6, :hlink, :folHlink, :lt1, :dk1, :lt2, :dk2. It follows the workbook's theme, as Excel's palette colors do;
• a SchemeColor, for a theme color with a tint or shade applied: SchemeColor(:accent1; lumMod = 75);
• :none, for an explicit <a:noFill/> — deliberately invisible;
• :inherit, to remove the fill so the chart style applies.

:none and :inherit are different states. An absent fill inherits; noFill does not.

Returns c. A Chart reads its part on every call, so c and any other handle to the same chart see the change. Values read from it earlier, such as a ChartSeries or a ChartDataPoint, describe the part as it was then.

setSeriesFill(c::ChartEx, i, color; point=nothing, pareto=false) -> ChartEx

Set the fill of series i, or of data point point of it, counting from 1. color is a color name ("red" or :red), a hex string ("FF0000", "#FF0000" or "80FF0000" with alpha), a Colors.Colorant, a theme color named as a String or Symbol ("accent2", :tx1), a SchemeColor, or :none or :inherit — see setSeriesFill. With pareto = true, series i's Pareto line instead; an error if it has none.

Setting a point's fill creates its cx:dataPt if Excel never formatted that point. :inherit never creates anything.

Returns c, which remains valid.

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

Set several line properties of series i's outline at once, in one rebuild of the chart part. A keyword left unspecified is left alone; pass :inherit to remove one that is set.

Keywords

These are the line keywords of every multi-property line setter — setAxisLine, setPlotAreaLine and the text :line field take the same. Each matches a single-property setter, whose docstring has more.

Every keyword also takes :inherit. The symbol-valued keywords accept the same words as Strings.

miterLimit needs a miter join. Passing join = :miter and miterLimit in one call works, since the join is applied first.

The symbol form acts on the whole outline: :none writes an a:ln whose fill is <a:noFill/>, and :inherit removes the a:ln so the chart style supplies it.

setSeriesLine(c::ChartEx, i; point=nothing, pareto=false, color, width, dash, cap, compound, join, miterLimit) -> ChartEx
setSeriesLine(c::ChartEx, i, :none; point=nothing, pareto=false)
setSeriesLine(c::ChartEx, i, :inherit; point=nothing, pareto=false)

Set several outline properties of series i, or of data point point of it, in one rebuild of the chart part. Keywords are color, width, dash, cap, compound, join and miterLimit, each taking the values listed at setSeriesLine. A keyword left unspecified is left alone; pass :inherit to remove one that is set. With pareto = true, series i's Pareto line instead; an error if it has none.

The symbol form acts on the whole outline: :none writes an a:ln whose fill is <a:noFill/>, and :inherit removes the a:ln so the chart style supplies it.

Returns c, which remains valid.

setSeriesLineColor(c, i, color) -> Chart

Set the color of series i's outline — the line itself, on a line or scatter chart. color is a color name ("red" or :red), a hex string ("FF0000", "#FF0000" or "80FF0000" with alpha), a Colors.Colorant, a theme color named as a String or Symbol ("accent2", :tx1), a SchemeColor, or :none or :inherit — see setSeriesFill.

Note :none here leaves the a:ln in place with no fill — the line exists and draws nothing, which is what Excel writes and is distinct from setSeriesLine(c, i, :inherit), which removes the outline entirely.

setSeriesLineColor(c::ChartEx, i, color; point=nothing, pareto=false) -> ChartEx

Set the color of series i's outline, or of data point point of it. color is a color name ("red" or :red), a hex string ("FF0000", "#FF0000" or "80FF0000" with alpha), a Colors.Colorant, a theme color named as a String or Symbol ("accent2", :tx1), a SchemeColor, or :none or :inherit — see setSeriesFill. :none writes an outline with <a:noFill/>; :inherit removes the color and leaves the rest of the a:ln. With pareto = true, series i's Pareto line instead; an error if it has none.

setSeriesLineWidth(c, i, points) -> Chart

Set the width of series i's outline, in points — the unit Excel's width box uses — as a Real from 0 to 1584. :inherit removes the width so the chart style supplies it.

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

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

setSeriesLineWidth(c::ChartEx, i, points; point=nothing, pareto=false) -> ChartEx

Set the width of series i's outline, or of data point point's, in points — a Real from 0 to 1584 — or :inherit to remove it. With pareto = true, series i's Pareto line instead.

setSeriesLineDash(c, i, dash) -> Chart

Set the dash pattern of series i's outline to one of the DrawingML presets, :solid, :dot, :dash, :lgDash, :dashDot, :lgDashDot, :lgDashDotDot, :sysDash, :sysDot, :sysDashDot, :sysDashDotDot, or Excel's names for them, :longDash (= :lgDash), :longDashDot (= :lgDashDot), :longDashDotDot (= :lgDashDotDot), :roundDot (= :sysDot), :squareDot (= :sysDash). A String works as well as a Symbol. :inherit removes the pattern.

Excel's "Round Dot" is :sysDot and "Square Dot" is :sysDash; :dot and :dash are different patterns, which Excel's dropdown does not offer.

One of the single-property line setters; see setSeriesLine.

setSeriesLineDash(c::ChartEx, i, dash; point=nothing, pareto=false) -> ChartEx

Set the dash pattern of series i's outline, or of data point point's: :solid, :dot, :dash, :lgDash, :dashDot, :lgDashDot, :lgDashDotDot, :sysDash, :sysDot, :sysDashDot, :sysDashDotDot, or Excel's names :longDash (= :lgDash), :longDashDot (= :lgDashDot), :longDashDotDot (= :lgDashDotDot), :roundDot (= :sysDot), :squareDot (= :sysDash); or :inherit to remove it. With pareto = true, series i's Pareto line instead.

setSeriesLineCap(c, i, cap) -> Chart

Set how series i's outline ends: :rnd, :sq, :flat, or Excel's names :round (= :rnd), :square (= :sq). A String works as well as a Symbol. :inherit removes the setting.

One of the single-property line setters; see setSeriesLine.

setSeriesLineCap(c::ChartEx, i, cap; point=nothing, pareto=false) -> ChartEx

Set how series i's outline ends, or data point point's: :rnd, :sq, :flat, or Excel's names :round (= :rnd), :square (= :sq); or :inherit to remove it. With pareto = true, series i's Pareto line instead.

setSeriesLineCompound(c, i, cmpd) -> Chart

Set the compound line type of series i's outline — how many parallel strokes it draws: :sng, :dbl, :thickThin, :thinThick, :tri, or Excel's names :double (= :dbl), :simple (= :sng), :triple (= :tri). A String works as well as a Symbol. :inherit removes the setting.

One of the single-property line setters; see setSeriesLine.

setSeriesLineCompound(c::ChartEx, i, cmpd; point=nothing, pareto=false) -> ChartEx

Set the compound line type of series i's outline, or data point point's: :sng, :dbl, :thickThin, :thinThick, :tri, or Excel's names :double (= :dbl), :simple (= :sng), :triple (= :tri); or :inherit to remove it. With pareto = true, series i's Pareto line instead.

setSeriesLineJoin(c, i, join) -> Chart

Set how the segments of series i's outline meet: :round, :bevel or :miter (or the same as a String). :inherit removes the join. Excel uses the same three words, so there are no aliases.

A miter join takes a limit as well, set separately with setSeriesLineMiterLimit; changing the join afterwards discards it.

One of the single-property line setters; see setSeriesLine.

setSeriesLineJoin(c::ChartEx, i, join; point=nothing, pareto=false) -> ChartEx

Set how the segments of series i's outline meet, or data point point's: :round, :bevel, :miter; or :inherit to remove it. Changing the join discards any miter limit. With pareto = true, series i's Pareto line instead.

setSeriesLineMiterLimit(c, i, limit) -> Chart

Set the miter limit of series i's outline, as a Real multiple of the line width: how far a sharp corner may extend before the join is cut off. Excel's default is 8. :inherit removes the limit.

The limit belongs to the a:miter element, so the series' outline must already have a miter join (setSeriesLineJoin); otherwise this throws.

One of the single-property line setters; see setSeriesLine.

setSeriesLineMiterLimit(c::ChartEx, i, limit; point=nothing, pareto=false) -> ChartEx

Set the miter limit of series i's outline, or data point point's, as a Real multiple of the line width; or :inherit to remove it. The outline must already have a miter join (setSeriesLineJoin). With pareto = true, series i's Pareto line instead.

hasFill(x) -> Bool

Whether x sets a visible fill. x is a DrawingShapeProps, a DrawingFill, or the Effective a resolver returns.

false covers two different cases: nothing was written, so the fill is inherited; or <a:noFill/> was, so it is deliberately transparent. Read sp.fill, or e.value, to tell those apart — nothing for the first, a fill with kind === :none for the second.

false never means Excel draws nothing: a property written at no rung comes from the chart style, which this layer does not read.

hasLine(x) -> Bool

Whether x sets a visible outline. x is a DrawingShapeProps, a DrawingLine, or the Effective a resolver returns.

false when a:ln is absent, so the outline is inherited, and also when it contains <a:noFill/>, which is how Excel writes "no border". As with hasFill, read the line itself to tell those apart.

false never means Excel draws nothing: a property written at no rung comes from the chart style, which this layer does not read.

getGroupAxes(c::Chart, g::ChartGroup) -> Vector{ChartAxis}

The axes named by g's c:axId children, in that order. Empty for pie and doughnut groups, which have no axes. An id that names no axis in the plot area is skipped rather than raising — malformed files exist.

getGroupLabelTextProps(c::Chart, g::ChartGroup) -> Union{Nothing,DrawingText}

Group-level data label text (c:barChart/c:dLbls/c:txPr). This is the inheritance parent for the series-level c:dLbls; Excel commonly writes a group c:dLbls carrying only the show* flags and no txPr, in which case this is nothing.

getGroupDropLines(c::Chart, g::ChartGroup) -> Union{Nothing,DrawingShapeProps}

Line properties of the group's drop lines (c:dropLines), which run from each data point down to the category axis. nothing means the group has no drop lines. Line, area and stock charts.

getGroupHiLowLines(c::Chart, g::ChartGroup) -> Union{Nothing,DrawingShapeProps}

Line properties of the group's high-low lines (c:hiLowLines), which span between the highest and lowest series at each category. Line and stock charts.

getGroupSeriesLines(c::Chart, g::ChartGroup) -> Union{Nothing,DrawingShapeProps}

Line properties of the group's series lines (c:serLines), which connect segments across categories on a stacked bar or an of-pie chart.

getGroupUpDownBars(c::Chart, g::ChartGroup) -> Union{Nothing,ChartUpDownBars}

The group's up-down bars (c:upDownBars), which span between the first and last series at each category. nothing means the group has none. Line and stock charts.

The result carries the gap width and is the handle the two formatting getters take: getUpBarShapeProps and getDownBarShapeProps.

getUpBarShapeProps(c::Chart, b::ChartUpDownBars) -> Union{Nothing,DrawingShapeProps}

Fill and border of the up bars (c:upBars/c:spPr). nothing means c:upBars was written with no formatting, or not written at all — Excel writes an empty <c:upBars/> for default white bars. The two cases differ only in the XML; both draw Excel's default bars.

getDownBarShapeProps(c::Chart, b::ChartUpDownBars) -> Union{Nothing,DrawingShapeProps}

Fill and border of the down bars (c:downBars/c:spPr), as getUpBarShapeProps is for the up bars.

setGroupLabelTextProp(c, g::ChartGroup, field, value) -> Chart

Set one text property of a chart group's data labels — the rung every series in the group inherits from. g is a group from getChartGroups.

field is one of :lang, :size, :bold, :italic, :under, :strike, :caps, :baseline, :kern, :spacing, :fill, :line, :latin, :ea, :cs, or Excel's names :color (= :fill), :font (= :latin), :strikethrough (= :strike), :underline (= :under). value depends on the field — see the table at setChartTitleTextProp — and :inherit removes the field so it is inherited.

getGroupGapWidth(c::Chart, g::ChartGroup) -> Union{Nothing,Int}

c:gapWidth — the space between bars or clusters, as a percentage of a bar's width (0–500). nothing means not written; Excel then uses 150. Bar and bar-of-pie groups only.

setGroupGapWidth(c, g, percent) -> Chart

Set the group's gap width, an Integer percentage of a bar's width from 0 to 500, as Excel's "Gap Width" box; or :inherit to remove it. g is a group from getChartGroups; bar and bar-of-pie groups only.

getGroupOverlap(c::Chart, g::ChartGroup) -> Union{Nothing,Int}

c:overlap — how far bars in a cluster overlap, as a percentage from -100 (separated by a bar's width) to 100 (fully overlapping, as stacked charts need). nothing means not written. 2-D bar groups only.

setGroupOverlap(c, g, percent) -> Chart

Set the group's overlap, an Integer percentage from -100 to 100, as Excel's "Series Overlap" box; or :inherit to remove it. g is a group from getChartGroups; 2-D bar groups only. Stacked groups need 100 for each series to sit on the one before it.

addChart(ws::Worksheet, kind::Symbol; anchor, title=nothing) -> Chart

Add an empty chart of kind to ws, covering the cells in anchor (a range such as "F2:M18"). Add data with addSeries.

kind is one of :column, :bar, :stackedColumn, :stackedBar, :line, :lineMarkers, :area, :pie, :doughnut, :scatter, :bubble or :radar. :bar and :stackedBar are horizontal; :column and :stackedColumn vertical. The chart starts as Excel's own default for that kind, formatted by the workbook's theme.

title is nothing for Excel's automatic title, a string for typed text, or false for no title. A RichTextString keeps each run's formatting, on top of the formatting Excel gives a new title, as does a styled string from StyledStrings.jl (Julia 1.11 and later). A CellRef or SheetCellRef binds the title to that cell, as setChartTitleText does; a string is always typed text, never read as a cell reference.

addChart(xf::XLSXFile, kind::Symbol; sheetname="", title=nothing) -> Chart

Add an empty chart of kind on a new chartsheet, placed after the existing sheets. sheetname defaults to Chart1, Chart2, … as Excel names them. See the worksheet method for kind and title. A title bound to a cell must name its sheet — a SheetCellRef, not a CellRef — since a chartsheet has no cells.

addChartEx(ws::Worksheet, kind::Symbol, values; anchor, categories=nothing,
           name=nothing, name_ref=nothing, title=nothing) -> ChartEx
addChartEx(xf::XLSXFile, kind::Symbol, values; sheetname="", …) -> ChartEx

Add a chartEx chart of kind — :waterfall, :funnel, :treemap, :sunburst, :histogram, :pareto or :boxWhisker — plotting values, to a worksheet or as a new chartsheet.

Unlike addChart, this takes the first series' data: a chartEx part must contain data, so an empty one cannot exist. A box & whisker chart takes further series with addSeries; every other layout takes one.

categories are the category labels; treemap and sunburst require them, as one column per hierarchy level ("A2:B8"), and a histogram takes none. References, name, name_ref and title are as for addChart and addSeries. The chart's appearance comes from Excel's style for the layout.

addSeries(c::Chart, values; categories=nothing, name=nothing, name_ref=nothing,
          bubble_sizes=nothing, markers=nothing, smooth=nothing, line=nothing,
          color=nothing) -> Chart

Add a series to c, plotting values. Each reference is a range string ("B2:B5"), a defined name, or a reference object; an unqualified range means the chart's own sheet, and a chart on a chartsheet must name one ("Data!B2:B5").

categories are the category labels, or the X values on a scatter or bubble chart; a bubble chart requires them, and bubble_sizes too. name is literal text for the series name, and name_ref a cell to take it from; pass one or neither.

To plot a table column, pass gettablerange(t, column) for either values or categories

markers (line, lineMarkers, radar and scatter) is a marker Symbol such as :circle, :square or :triangle — any that setMarkerSymbol takes — or true for :circle, or false for none. Markers on a :line chart make it :lineMarkers. smooth (line, lineMarkers and scatter) is a Bool: true curves the line. line (scatter) is a Bool: true joins the points.

color overrides the series' automatic color. It is a color name ("red" or :red), a hex string ("FF0000", "#FF0000" or "80FF0000" with alpha), a Colors.Colorant, a theme color named as a String or Symbol ("accent2", :tx1) or a SchemeColor — the color values of setSeriesFill other than :none and :inherit. It does not apply to pie and doughnut charts, whose points are colored individually.

The cells' current values are cached in the chart, as Excel does, so the series reads back without opening the file in Excel. Series take the theme's accent colors in turn; on a pie or doughnut chart each point does instead.

addSeries(c::ChartEx, values; categories=nothing, name=nothing, name_ref=nothing) -> ChartEx

Add a series to a box & whisker chart, plotting values. Every other chartEx layout holds one series, given to addChartEx.

References, categories, name and name_ref are as for the Chart method: a range string ("B2:B9"), a defined name or a reference object, with an unqualified range meaning the chart's own sheet and a chart on a chartsheet needing a qualified one ("Data!B2:B9"). name is literal text for the series name, name_ref a cell to take it from.

Format the new series afterwards with setSeriesFill and setSeriesLine.