SheetXL - v1.0.2
    Preparing search index...

    Interface IPicture

    Interface for working with Pictures (both Images and SVG).

    interface IPicture {
        isIModel: true;
        isIPicture: 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>;
        getConnections?(
            width: number,
            height: number,
            options?: ConnectionsOptions,
        ): readonly Connection[] | null;
        getCrop(): RectInsets;
        getDefaultAnchorType?(): IAnchored.Type;
        getDescription(): string | null;
        getDetails(): Promise<Details>;
        getGeometry(width?: number, height?: number): Promise<IGeometry | null>;
        getHyperlink(): IHyperlink | null;
        getId(): string;
        getMovable(): IMovable | null;
        getName?(): string | null;
        getReferences(): ICellRanges | null;
        getResource(): IResource;
        getShapeType(): string;
        getStyle(): IShapeStyle;
        getType(): string;
        getTypeDescription(): string;
        getVersionId(): number;
        isClosed(): boolean;
        isDefaultLockAspectRatio?(): boolean;
        isDeleted(): boolean;
        isReadOnly(): boolean;
        setCrop(
            crop: RectInsets | null,
            options?: ITransaction.OperationOptions,
        ): this;
        setDescription(description: string | null): this;
        setHyperlink(
            hyperlink: IHyperlink.Update,
            options?: ITransaction.OperationOptions,
        ): this;
        setName?(name: string): this;
        setResource(
            picture: string | IResource | IResourceCollection.AddOptions,
            options?: ITransaction.OperationOptions,
        ): this;
        setShapeType(
            shapeType: string,
            options?: ITransaction.OperationOptions,
        ): this;
        toHtml(): string | Promise<string> | null;
        toImage(): Promise<Blob>;
        toJSON(
            toResourceId?: (resource: IResource) => number | null,
        ): IPicture.JSON;
    }

    Hierarchy (View Summary)

    Index
    isIModel isIPicture
    acceptFlip? acceptRotation? addListeners beginCommit close delete doBatch getConnections? getCrop getDefaultAnchorType? getDescription getDetails getGeometry getHyperlink getId getMovable getName? getReferences getResource getShapeType getStyle getType getTypeDescription getVersionId isClosed isDefaultLockAspectRatio? isDeleted isReadOnly setCrop setDescription setHyperlink setName? setResource setShapeType toHtml toImage toJSON
    isIModel: true

    For runtime type checking.

    isIPicture: 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.

    • 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 part of the image shown, as percentages of the image's size inset from each edge.

      Returns RectInsets

      An edge not cropped is absent, so an uncropped picture answers {}. A negative inset shows empty space beyond that edge of the image, which is how a picture fits inside a frame of another shape.

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

      Returns string | null

    • Returns a local object URL for placing in an image tag.

      Returns Promise<Details>

    • Returns the shape's outline at a size, for drawing the picture cropped to its shape.

      Parameters

      • Optionalwidth: number

        The frame's width in pixels. Defaults to the movable's.

      • Optionalheight: number

        The frame's height in pixels. Defaults to the movable's.

      Returns Promise<IGeometry | null>

      null for a preset this SDK does not know, or for a picture with no movable and no size.

    • Returns the hyperlink a click on the picture follows, or null for none.

      Returns IHyperlink | null

    • 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, or null if the content has none.

      Returns string | null

      Not defined for content that is never named.

    • 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 the resource associated with this picture.

      Returns IResource

    • Returns the shape the picture is cropped to: its preset geometry.

      Returns string

      A DrawingML preset id (IGeometry.Preset): rect for a picture that is not cropped to a shape, which is most of them. A file may name a preset this SDK does not know; it is returned as the file states it.

    • What the picture's frame draws with: the fill behind the image and the border around it. A picture has no theme style, so each is only what the picture states; by default neither draws, and a border shows only once it has a color (a width alone draws nothing, as in Excel). The same object answers for the life of the picture.

      Returns IShapeStyle

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

    • 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

    • Sets the part of the image shown. The frame stays as it is, so the part shown is stretched over it; to keep the image's scale, change the frame with IMovable.setBounds as well.

      Parameters

      Returns this

      ExpectedError when the insets leave nothing to show.

      picture.setCrop({ left: 10, right: 10 });

    • Set the alternative text used by assistive technologies.

      Parameters

      • description: string | null

      Returns this

    • Sets the hyperlink a click on the picture follows.

      Parameters

      • hyperlink: IHyperlink.Update

        An address, the link's properties, or null to remove it. An address takes the form a cell's does: a url, or #Sheet1!A1 for a location in this workbook.

      • Optionaloptions: ITransaction.OperationOptions

      Returns this

      picture.setHyperlink('https://www.sheetxl.com');

    • Set the name.

      Parameters

      • name: string

        The name of the content.

      Returns this

    • Shows another image, as Excel's Change Picture does: the frame's size and placement and the picture's formatting stay; only the image changes.

      The resource is taken as it is, not read: a source that cannot be fetched shows nothing. Read it first (toBuffer()) to be sure of it.

      Parameters

      Returns this

      picture.setResource('https://example.com/logo.png');

    • Crops the picture to a shape, as Excel's Crop to Shape does: the image, its frame, border and effects stay; the picture is clipped to the preset's outline.

      A picture takes any closed preset; a line or connector preset is refused.

      Parameters

      Returns this

      ExpectedError for a preset the picture cannot take.

      picture.setShapeType(IGeometry.Preset.Ellipse);

    • Return an html string or null if not supported.

      Returns string | Promise<string> | null

    • Returns an image blob.

      Returns Promise<Blob>

    Settings
    Member Visibility

    On This Page
    Properties
    Methods