SheetXL - v1.0.2
    Preparing search index...

    Interface IChart

    Interface for working with a chart.

    A chart is the content of a movable, which places it — see IChart.getMovable.

    interface IChart {
        isIChart: true;
        isIModel: true;
        acceptFlip?(flip: Flip): Flip;
        acceptRotation?(degrees: number): number;
        addListeners(
            listeners: IChart.IListeners,
            options?: IListener.Options,
        ): Remove;
        addSeries(
            name?: string | ICellRange,
            index?: number,
            options?: ITransaction.OperationOptions,
        ): IChart.ISeries;
        beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
        close(): void;
        delete(options?: ITransaction.OperationOptions): void;
        doBatch<R = any>(
            callback: (commit: ICommit) => R | Promise<R>,
            options?: string | ITransaction.OperationOptions,
        ): R | Promise<R>;
        getAxes(): IAxes;
        getChartArea(): IChart.IChartArea;
        getChartStyle(): number;
        getChartTitle(): string | null;
        getChartType(): string;
        getConnections?(
            width: number,
            height: number,
            options?: ConnectionsOptions,
        ): readonly Connection[] | null;
        getDataLabels(): IChart.IDataLabels;
        getDataTable(): IChart.IDataTable;
        getDefaultAnchorType?(): IAnchored.Type;
        getDescription(): string | null;
        getDisplayBlanksAs(): DisplayBlanksAs;
        getElement(path: string): IElement | null;
        getElementAt(point: Point, layout?: Size | ChartLayout): IElement | null;
        getElementBounds(
            element: string | IElement,
            layout?: Size | ChartLayout,
        ): Bounds | null;
        getElements(): readonly IElement[];
        getGroups(): readonly IChartGroup[];
        getId(): string;
        getLayout(size?: { height: number; width: number }): ChartLayout | null;
        getLegend(): IChart.ILegend;
        getMovable(): IMovable | null;
        getName?(): string | null;
        getPivotSource(): string | null;
        getPlotArea(): IChart.IPlotArea;
        getPlotVisibleOnly(): boolean;
        getReferences(): ICellRanges | null;
        getRoundedCorners(): boolean;
        getSeries(): readonly IChart.ISeries[];
        getSeriesBy(): "rows" | "columns";
        getStyle(): ITextBoxStyle;
        getTitle(): IChart.ITitle;
        getType(): string;
        getTypeDescription(): string;
        getVersionId(): number;
        isClosed(): boolean;
        isDefaultLockAspectRatio?(): boolean;
        isDeleted(): boolean;
        isReadOnly(): boolean;
        setChartType(type: string, options?: ITransaction.OperationOptions): this;
        setData(
            source: string | ICellRanges | ICellRange,
            seriesBy?: SeriesBy,
            options?: ITransaction.OperationOptions,
        ): this;
        setDescription(description: string | null): this;
        setDisplayBlanksAs(
            value: DisplayBlanksAs,
            options?: ITransaction.OperationOptions,
        ): this;
        setElement(
            element: IChart.Element,
            options?: ITransaction.OperationOptions,
        ): this;
        setName?(name: string): this;
        setPlotVisibleOnly(
            plotVisibleOnly: boolean,
            options?: ITransaction.OperationOptions,
        ): this;
        setRoundedCorners(
            rounded: boolean,
            options?: ITransaction.OperationOptions,
        ): this;
        setSeriesBy(
            seriesBy: "rows" | "columns",
            options?: ITransaction.OperationOptions,
        ): this;
        update(
            update: IChart.Update,
            options?: ITransaction.OperationOptions,
        ): this;
    }

    Hierarchy (View Summary)

    Index
    isIChart isIModel
    acceptFlip? acceptRotation? addListeners addSeries beginCommit close delete doBatch getAxes getChartArea getChartStyle getChartTitle getChartType getConnections? getDataLabels getDataTable getDefaultAnchorType? getDescription getDisplayBlanksAs getElement getElementAt getElementBounds getElements getGroups getId getLayout getLegend getMovable getName? getPivotSource getPlotArea getPlotVisibleOnly getReferences getRoundedCorners getSeries getSeriesBy getStyle getTitle getType getTypeDescription getVersionId isClosed isDefaultLockAspectRatio? isDeleted isReadOnly setChartType setData setDescription setDisplayBlanksAs setElement setName? setPlotVisibleOnly setRoundedCorners setSeriesBy update
    isIChart: true

    For runtime type checking.

    isIModel: true

    For runtime type checking.

    • The flip this content takes when asked to mirror as flip states.

      Parameters

      Returns Flip

      Defined by content that can be mirrored, such as a shape or a picture; absent, the content cannot: a frame dragged through its opposite edge is moved there but not mirrored, as Excel does with a chart. Must be pure, as acceptRotation is. A connector may accept each axis on its own.

    • The rotation this content takes when asked to turn by degrees, clockwise.

      Parameters

      • degrees: number

      Returns number

      Defined by content that can be turned, such as a shape or a picture; absent, the content cannot and no rotate handle is offered. Must be pure: it is asked throughout a gesture to draw its preview, and the answer is what the movable stores.

    • Batches all 'transactional' changes until they have all be committed or rolled back.

      Parameters

      • Optionaloptions: string | ITransaction.OperationOptions

        Description of the operation or additional options. Used for tracking undo/redo and history. Default Value User Operation.

      Returns ITransaction

      Any changes that are made to this object will be reflected in the local record but not committed to the transactional store until the batch is popped.

      Useful for operations that are longer running but generally not recommended as it keeps a transaction open. doBatch is the preferred option.

    • Close the record and cleans resources. Can't be undone.

      Returns void

    • Provides a mechanism to perform a set of operations in a batch.

      Type Parameters

      • R = any

      Parameters

      • callback: (commit: ICommit) => R | Promise<R>

        A callback that performs multiple operations all within the same transaction.

      • Optionaloptions: string | ITransaction.OperationOptions

        Description of the operation or additional options. Used for tracking undo/redo and history. Default Value User Operation.

      Returns R | Promise<R>

      Writes are tracked automatically: a batch that performs no state updates (a read-only batch) is elided — the commit id is unchanged, no events fire, and nothing is added to the undo stack or commit log.

    • Returns the chart's axes. A pie has none.

      Returns IAxes

      chart.getAxes().getValueAxis()?.setMinimum(0);
      chart.getAxes().getItems().map(axis => axis.getKind());

    • Returns the chart area: the whole chart's fill, border and font, the element every other element is inside.

      Returns IChart.IChartArea

    • Returns the chart's preset style, 1 to 48: the colors and effects Excel's Chart Styles gallery gives the chart's parts. 2 for a chart that states none, as the file format's default.

      Returns number

    • Returns the chart's title, or null if it has none.

      Returns string | null

      A title that is a reference to a cell reads as that cell's text. A chart with no title of its own answers null even where an application would draw one for it — a single series' name, or a placeholder.

    • Returns the chart's type, by the names of IChart.Type, or 'unknown'.

      Returns string

      'columnClustered', 'barStacked100', 'lineMarkers', 'pie', 'xyscatter', 'waterfall', 'pareto' and so on. A chart whose groups of series are drawn differently is 'combo', and IChart.ISeries.getChartType says how each series is drawn. Within one group series may differ in markers; the chart then answers its first series' type, as Excel does.

    • The points a connector's end may be glued to, in a width by height frame of this content, before the frame is placed.

      Parameters

      Returns readonly Connection[] | null

      Absent, the four edge midpoints — top, left, bottom, right, numbered in that order, each leaving straight out — as Excel offers on a picture, a chart, a slicer or a control. A shape is the exception and answers its geometry's own sites (a triangle's three, a connector's none); a group answers none, since Excel glues to a group's members and never to the group. Must be synchronous: null means the content cannot answer yet and will call options.onReady when it can.

    • Returns the data labels of every series at once: reads answer the first series', and each setter sets every series (Office Scripts' chart.getDataLabels(), VBA's ApplyDataLabels).

      Returns IChart.IDataLabels

    • Returns the alternative text used by assistive technologies, or null if none has been set.

      Returns string | null

    • Returns how a blank cell is plotted: as a gap, as zero, or with a line drawn across it.

      Returns DisplayBlanksAs

    • Returns the element at path (see IChart.IElement.getPath), or null where the chart has none: a path that names nothing, or a part an edit removed.

      Parameters

      • path: string

      Returns IElement | null

      chart.getElement('axes/primary/value/title')?.getElementType(); // 'axisTitle'
      chart.getElement('series/0/points/3');                          // the fourth point of series 0

    • Returns the element drawn at point: a hit test of the chart as laid out.

      Parameters

      • point: Point

        In px from the chart's top-left, unzoomed, as getLayout speaks.

      • Optionallayout: Size | ChartLayout

        The layout to test, as getLayout answered it, or the size to lay the chart out at; by default the chart is laid out at its movable's bounds.

      Returns IElement | null

      The topmost element there, as Excel stacks them: the title and legend over everything, then data labels, trendlines and error bars, a series' points, the lines under them, axis titles, axes and gridlines, the plot area, and the chart area under it all. null outside the chart, or when the chart has no layout.

      A press on a bar answers the bar's point; its series is the point's parent. Excel selects the series on a first press and the point on the next; which to select is the caller's.

      const layout = chart.getLayout({ width: 480, height: 288 });
      chart.getElementAt({ x: 240, y: 12 }, layout)?.getPath(); // 'title'

    • Returns the box element is drawn in, in px from the chart's top-left, or null where the chart as laid out draws nothing for it (a hidden part, a point with no value, the data table).

      Parameters

      Returns Bounds | null

      The chart area's box is the whole chart's, the plot area's its outer box (with its axes' labels), an axis's its line and labels together, a series' its points' boxes together.

    • Returns the elements the chart shows, as Excel's Chart Elements list offers them to choose from: the chart area, the plot area, each series, and the title, legend, axes, axis titles, gridlines, data labels, trendlines, error bars, data table and group lines that are shown. Points, markers and legend entries are left out; a series' IChart.ISeries.getPoints lists its points.

      Returns readonly IElement[]

    • Returns the chart's groups: each the series drawn one way against one pair of axes, with the options they share (VBA's ChartGroups). A chart of one type has one group; a combo one per type and axis pair.

      Returns readonly IChartGroup[]

    • A unique identifier for the record. This will never change.

      Returns string

      This enables the record to be identified across transactions and users in a collaborative environment. The id is store-issued (IStore.create); the store keys all state by it.

    • Returns the chart laid out as Excel lays it out: every rect, axis scale, tick label, bar and point, in px from the chart's top-left, with every color concrete.

      Parameters

      • Optionalsize: { height: number; width: number }

        The chart's size in px, unzoomed. Defaults to the movable's bounds.

      Returns ChartLayout | null

      null when the chart cannot be laid out: it has no size, or it is of a type not yet laid out (waterfall, histogram, pareto, box and whisker, treemap, sunburst, funnel, map).

      Values are those the file cached. Automatic axis bounds and units read back as numbers here, the way Excel's MinimumScale does.

      const layout = chart.getLayout({ width: 480, height: 288 });
      const valueAxis = layout?.axes.find(axis => axis.kind === 'value');
      console.log(valueAxis?.min, valueAxis?.max, valueAxis?.majorUnit);

    • Returns the movable that places the chart on the sheet, or null if it is not placed by one.

      Returns IMovable | null

      The movable holds the chart's position and size; the chart keeps no copy of either. Deleting the chart removes its movable.

    • Returns the name, or null if the content has none.

      Returns string | null

      Not defined for content that is never named.

    • Returns the name of the pivot table the chart draws, or null if it is not a pivot chart.

      Returns string | null

      A pivot chart's series are the pivot table's: they change with its layout, and the ranges its series name are wherever the table last put them.

    • Returns whether hidden rows and columns are left out of the chart.

      Returns boolean

    • Returns the cells the content names - a chart's series, a control's linked cell, a slicer's column - or null when it names none.

      Returns ICellRanges | null

      Not where the movable sits: that is IMovable.getRange. The references are formulas the calculation engine holds, so they follow the cells they name through inserts, deletes, cuts, sheet renames and undo, and ContentEvents.onReferencesChange is announced when they have. A reference to deleted cells is left out. Without a running engine the references read as they were set.

    • Returns whether the chart area's corners are rounded.

      Returns boolean

    • Returns the series the chart plots, in the order they are listed.

      Returns readonly IChart.ISeries[]

      What a series plots is stated as formulas, which follow the cells they name: inserting a row above the data moves them, and deleting the data leaves #REF!.

    • Returns whether each series is a row or a column of the chart's cells, as its first series reads them.

      Returns "rows" | "columns"

    • Returns what the chart area is drawn with: its fill, its border and the chart's font (Office Scripts' getFormat(), VBA's ChartArea.Format).

      Returns ITextBoxStyle

      The font is what every text takes unless it states its own. Setting it sets every text in the chart, the title at 1.2 times the size, as Excel's ChartArea.Font does.

    • Returns the chart's title. A chart always has one to set, shown or not.

      Returns IChart.ITitle

    • Returns an immutable type string.

      Returns string

    • Returns a label for the kind of content, such as Chart or Picture.

      Returns string

    • Every committed update gives the record a new, strictly increasing version id.

      Returns number

      Used with getId to uniquely identify a version of the record.

      The id is an identity, not a per-record count: ids are drawn from a single store-wide sequence bumped once per commit, so all records written in the same commit share an id and a given record's ids increase but are not sequential.

      Records are immutable so a restore/revert doesn't change them — it repoints, and the version id reported is the one for the snapshot the store is currently at. Version ids are never reused: a write after an undo receives an id higher than any previously issued, so a stale reader can always detect the change.

    • Returns true if no more operations are allowed.

      Returns boolean

    • Whether a movable of this content keeps its aspect ratio when resized from a corner, when it states no lock of its own.

      Returns boolean

      Absent, it does not. A picture does.

    • If the model unable to be modified.

      Returns boolean

    • If the model unable to be modified.

      Returns boolean

    • Draws every series as type, in one group on the primary axes, as Excel's Change Chart Type does: the series keep their colors, and what each type cannot draw with is restated (a bar's fill becomes a line's color, a pie takes a slice per point).

      Parameters

      Returns this

      A combo becomes one group; the secondary axes go. Office Scripts' setChartType, VBA's Chart.ChartType. To change one series, see IChart.ISeries.setChartType.

      ExpectedError for a stock type, which Excel makes only from its own series.

    • Replaces every series with the series Excel makes of source, as Insert Chart does.

      Parameters

      • source: string | ICellRanges | ICellRange

        The cells: a range, or an address. A bare address is on the chart's sheet; several areas are separated by commas.

      • OptionalseriesBy: SeriesBy

        Whether each series is a row or a column of the cells. 'auto' lets the cells decide, as Insert Chart does.

      • Optionaloptions: ITransaction.OperationOptions

      Returns this

      The same as Office Scripts' setData and VBA's SetSourceData. Series that take the place of existing ones keep how those are drawn; any more are drawn as a new chart of the type draws them.

      ExpectedError when source holds no cells.

    • Set the alternative text used by assistive technologies.

      Parameters

      • description: string | null

      Returns this

    • Adds, places or removes a chart element by the names of Excel's Add Chart Element menu (VBA's SetElement): 'legendRight', 'dataLabelOutsideEnd', 'primaryValueAxisTitleRotated', 'primaryValueGridLinesMinorMajor', 'trendlineAddLinear', 'errorBarStandardDeviation'…

      Parameters

      Returns this

      Each name is one of the setters below, applied as Excel applies it: a data label element to every series, a trendline or error bar element to every series that takes one.

      ExpectedError for an element the chart has no place for (a secondary axis's on a chart without one, a 3-D wall), or one Excel refuses on its type.

    • Set the name.

      Parameters

      • name: string

        The name of the content.

      Returns this

    • Reads the chart's cells the other way: each series a row of them, or a column. The same cells, as IChart.setData reads them with that direction.

      Parameters

      Returns this

      ExpectedError when the series do not read one block of cells.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods