Skip to content
Apiary

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.

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.

Chart

GraphicAnchor

| { name?: string; } | null

GraphicChart

a copy of the new graphic

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(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.

string

boolean

false if the sheet has no chart graphic id


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.

string

ChartGraphicInfo | null


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.

string

Chart

void

if the sheet has no chart graphic id, or the chart fails the checks of validateChart; nothing is changed then


setName(id, name): void;

Rename graphic id. Names need not be unique, as in Excel.

string

string

void

if the sheet has no chart graphic id, or the name is not a non-empty string


setPosition(id, anchor): void;

Move graphic id: replace its drawing’s anchor with a copy of anchor.

string

GraphicAnchor

void

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