SheetXL - v1.0.2
    Preparing search index...

    Interface IShape

    A drawn shape: a text box, a callout, a rectangle, a connector.

    A shape is the content of an IMovable — movable.getContent<IShape>() for a movable whose content type is 'shape'. The movable carries the position; the shape carries what is drawn there and what is written on it. A group of shapes is an IGroup, whose members are movables of their own.

    Reading, and adjust values: a shape is JSON (IShape.JSON) that a file reads into and writes from; the editing API beyond setAdjustments is still to come.

    interface IShape {
        isIModel: true;
        isIShape: true;
        acceptFlip?(flip: Flip): Flip;
        acceptRotation?(degrees: number): number;
        addListeners(listeners: IListeners, options?: IListener.Options): Remove;
        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>;
        getAdjustments(): Readonly<Record<string, number>>;
        getConnections(
            width: number,
            height: number,
            options?: ConnectionsOptions,
        ): readonly Connection[] | null;
        getConnectionSiteCount(): Promise<number>;
        getConnectorFormat(): IConnectorFormat | null;
        getDefaultAnchorType?(): IAnchored.Type;
        getDescription(): string | null;
        getGeometry(
            width?: number,
            height?: number,
            options?: GeometryOptions,
        ): Promise<IGeometry | null>;
        getId(): string;
        getMovable(): IMovable | null;
        getName(): string | null;
        getReferences(): ICellRanges | null;
        getResource(resourceId: number): IResource | null;
        getShapeType(): string;
        getStyle(): IShapeStyle;
        getTextFrame(): ITextFrame.IText | null;
        getType(): string;
        getTypeDescription(): string;
        getVersionId(): number;
        isClosed(): boolean;
        isConnector(): boolean;
        isDefaultLockAspectRatio?(): boolean;
        isDeleted(): boolean;
        isReadOnly(): boolean;
        setAdjustments(
            adjustments: Record<string, number> | null,
            options?: ITransaction.OperationOptions,
        ): this;
        setDescription(description: string | null): this;
        setName?(name: string): this;
        setShapeType(
            shapeType: string,
            options?: ITransaction.OperationOptions,
        ): this;
        toJSON(
            toResourceId?: (resource: IResource) => number | null,
        ): IShape.JSON | null;
    }

    Hierarchy (View Summary)

    Index
    isIModel isIShape
    acceptFlip? acceptRotation? addListeners beginCommit close delete doBatch getAdjustments getConnections getConnectionSiteCount getConnectorFormat getDefaultAnchorType? getDescription getGeometry getId getMovable getName getReferences getResource getShapeType getStyle getTextFrame getType getTypeDescription getVersionId isClosed isConnector isDefaultLockAspectRatio? isDeleted isReadOnly setAdjustments setDescription setName? setShapeType toJSON
    isIModel: true

    For runtime type checking.

    isIShape: 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 adjust values set on this shape, by name.

      Returns Readonly<Record<string, number>>

      A preset's handles move its adjust values — how rounded a roundRect is, where a callout points. Only values that differ from the preset's defaults are stored.

      The values are the geometry definition's own numbers (a ratio in 100,000ths, an angle in 60,000ths of a degree), opaque to a caller: a handle drag produces them through IGeometry.adjustmentsFromHandle, and a file reads and writes them as they are.

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

    • How many connection sites the shape's geometry has: the places a connector's end can be glued, numbered from 0.

      Returns Promise<number>

      Asynchronous as getGeometry is, which answers it. A shape with no geometry has none.

    • A connector's ends: what each is glued to, and gluing it.

      Returns IConnectorFormat | null

      null for a shape that is not a connector.

      const line = connector.getContent<IShape>().getConnectorFormat()!;
      line.startConnect(box, 3); // the box's right site
      line.getStartConnectedMovable() === box; // true, and the line follows the box from now on

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

      Returns string | null

    • Evaluates the shape's geometry at a size.

      Parameters

      • Optionalwidth: number

        Width in pixels.

      • Optionalheight: number

        Height in pixels.

      • Optionaloptions: GeometryOptions

        What to evaluate in place of the shape's own preset or adjust values, as a gesture previews them; the shape is not changed.

      Returns Promise<IGeometry | null>

      null for a shape whose preset is unknown, or a shape with no size. A custom geometry evaluates like a preset, from its own definition.

      What evaluates a shape loads on first use, and only what that shape needs, so this is asynchronous; a workbook with no shapes loads none of it. Everything on the geometry it returns is synchronous, including evaluating it again at another size or with other adjust values. Paths, handles and sites are in sheet pixels, in the shape's own frame (its top-left is 0,0), which is how the movable layer draws them.

      An open path takes the line ends the shape's line declares (its own over its theme style's): its stroke is trimmed under them, and they are visited as IGeometry.PathLayer.Marker paths.

      the movable's bounds.

      the movable's bounds.

    • 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 movable that places the content on the sheet, or null if it is not placed by one.

      Returns IMovable | null

    • Returns the name of the shape.

      Returns string | null

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

    • The image a resource id in this shape's JSON names: an image fill's resId, as toJSON with no scope names it. null when the shape holds no such resource.

      Parameters

      • resourceId: number

      Returns IResource | null

    • Returns the kind of shape this is: its preset geometry.

      Returns string

      A DrawingML preset id (IGeometry.Preset) — rect, borderCallout2, curvedConnector3 — or 'custom' for a shape drawn from its own path. A file may name a preset this SDK does not know; it is returned as the file states it.

      The preset says what a shape is for where its name does not: a callout annotates something, a connector links two shapes, and a rectangle with no text is usually a box drawn around the cells under it.

    • What the shape draws with: its fill and its line, resolved from what it states over its theme style. The same object answers for the life of the shape.

      Returns IShapeStyle

      shape.getStyle().setFill('#ffd966');
      shape.getStyle().getStroke().setWidth(2.25);

    • Returns the text written on the shape.

      Returns ITextFrame.IText | null

      null when the shape has no text body at all, as a connector does not. A shape that can hold text but has none answers with a frame whose text is ''.

      Text on a shape is a note from the workbook's author to its reader, so it is worth reading before the cells it sits beside.

      for (const movable of sheet.getMovables().getItems({ type: 'shape' })) {
        const text = movable.getContent<IShape>().getTextFrame()?.getText();
        if (text) console.log(movable.getRange().toString(), text);
      }

    • 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 the shape is a connector: a line whose ends can be glued to other movables' connection sites.

      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

    • Sets the adjust values, replacing any already set.

      Parameters

      Returns this

    • Set the alternative text used by assistive technologies.

      Parameters

      • description: string | null

      Returns this

    • Set the name.

      Parameters

      • name: string

        The name of the content.

      Returns this

    • Changes the kind of shape this is, as Excel's Change Shape does: its text, fill, outline, size and placement stay; its adjust values go back to the new preset's defaults.

      A line or connector takes only a line or connector preset, and any other shape only another kind of preset; custom is not a preset.

      Parameters

      Returns this

      ExpectedError for a preset the shape cannot take.

      shape.setShapeType(IGeometry.Preset.RoundRect);

    • Parameters

      • OptionaltoResourceId: (resource: IResource) => number | null

      Returns IShape.JSON | null

    Settings
    Member Visibility

    On This Page
    Properties
    Methods