Graphics
Operations on a sheet’s graphics, reached as sheet.graphics; only chart graphics, for now. A
graphic is one object on the sheet, as Excel’s Selection Pane lists them: a chart frame,
picture, shape or group. Its id is unique on the sheet. It sits in a drawing, the container
anchored to the sheet (sheet.drawings). A chart graphic shows a chart: the record
workbook.charts[graphic.chartId]. Methods take and return JSF, and copy both ways. Apiary
doesn’t build charts: a client passes in a JSF chart.
Methods
Section titled “Methods”addChart()
Section titled “addChart()”addChart( chart, anchor, options?): GraphicChart;Add a chart to the sheet, in a new drawing of its own. Stores a copy of chart in
workbook.charts under a new key. The graphic’s id is one more than the highest on the
sheet; its name, unless given, is “Chart N” with N one less than the id, as Excel names them.
A chart that has no axis for one of its scales is left out when the workbook is saved as XLSX.
Parameters
Section titled “Parameters”Chart
anchor
Section titled “anchor”GraphicAnchor
options?
Section titled “options?”| {
name?: string;
}
| null
Returns
Section titled “Returns”GraphicChart
a copy of the new graphic
Throws
Section titled “Throws”if the anchor is outside the grid, the name is not a non-empty string, or the chart fails the checks of validateChart; nothing is changed then
delete()
Section titled “delete()”delete(id): boolean;Delete graphic id: take it out of its group, and each group and the drawing that leaves
empty; ungroup a group left with one graphic, keeping that graphic where it was, and fit the
groups that are left around their content, as Excel does. The chart record it showed is
removed from workbook.charts once no graphic on any sheet shows it.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”boolean
false if the sheet has no chart graphic id
getChart()
Section titled “getChart()”getChart(id): ChartGraphicInfo | null;The chart graphic id, where it sits, and the chart it shows; null if the sheet has no chart
graphic id, or the chart record it names is missing.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”ChartGraphicInfo | null
setChart()
Section titled “setChart()”setChart(id, chart): void;Replace the chart that graphic id shows with a copy of chart. A chart record shown by
several graphics changes for all of them.
Parameters
Section titled “Parameters”string
Chart
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if the sheet has no chart graphic id, or the chart fails the checks of
validateChart; nothing is changed then
setName()
Section titled “setName()”setName(id, name): void;Rename graphic id. Names need not be unique, as in Excel.
Parameters
Section titled “Parameters”string
string
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if the sheet has no chart graphic id, or the name is not a non-empty string
setPosition()
Section titled “setPosition()”setPosition(id, anchor): void;Move graphic id: replace its drawing’s anchor with a copy of anchor.
Parameters
Section titled “Parameters”string
anchor
Section titled “anchor”GraphicAnchor
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if the sheet has no chart graphic id, the graphic is in a group (its position
belongs to the group’s drawing), or the anchor is outside the grid