SheetXL - v0.8.0-beta.9+sites.210.e2d420901
    Preparing search index...

    Interface IMovable

    Capabilities for working with graphical elements that can be arbitrarily placed (floated) within a virtual 'canvas'.

    Encompasses objects like images, charts, shapes, and custom widgets.

    Key features include:

    • Inserting, positioning, resizing, and scaling movables.
    • Grouping and layering multiple movables.
    • Loading, saving, and copy/pasting movables.
    interface IMovable {
        isIAnchored: true;
        isIMovable: true;
        isSelected: () => boolean;
        scrollIntoView: (
            options?: boolean | ScrollIntoViewOptions,
        ) => Promise<boolean>;
        unselect: () => boolean;
        addListeners(
            listeners: IMovable.IListeners,
            options?: IListener.Options,
        ): Remove;
        beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
        close(): void;
        delete(): void;
        doBatch<R = any>(
            callback: (commit: ICommit) => R | Promise<R>,
            options?: string | ITransaction.OperationOptions,
        ): R | Promise<R>;
        getAnchorType?(): IAnchored.Type;
        getBounds(): Bounds | null;
        getContent<T extends IContent = IContent>(): T;
        getFlip(): Flip;
        getId(): string;
        getMovables(): IMovableCollection | null;
        getName?(): string | null;
        getParent(): IMovable | null;
        getRange(options?: ICellRange.GetRangeOptions): ICellRange;
        getRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
        getRotation(): number;
        getSnapshot(
            options?: CopyOptions,
        ): IHistory.ISnapshot<IMovable.SnapshotDestination, IMovable, Bounds, any>;
        getVersionId(): number;
        getZIndex(): number;
        isClosed(): boolean;
        isContentLoaded(): boolean;
        isDeleted(): boolean;
        isHidden(): boolean;
        isLockAspectRatio(): boolean;
        isProtected(): boolean;
        moveBackward(): this;
        moveForward(): this;
        moveToBack(): this;
        moveToFront(): this;
        select(options?: IMovable.SelectOptions): Promise<boolean>;
        setAnchorType(anchorType: IAnchored.Type): IMovable;
        setBounds(
            bounds: Partial<Bounds>,
            options?: ITransaction.OperationOptions,
        ): IMovable;
        setFlip(
            flip: Partial<Flip>,
            options?: ITransaction.OperationOptions,
        ): IMovable;
        setHidden(hidden: boolean): IMovable;
        setLockAspectRatio(locked: boolean): IMovable;
        setRotation(rotation: number): IMovable;
        toJSON?(
            toResourceId?: (resource: IResource) => number | null,
        ): IMovable.JSON;
        whenContentLoaded(): Promise<IContent>;
    }

    Hierarchy (View Summary)

    Index
    isIAnchored isIMovable isSelected scrollIntoView unselect
    addListeners beginCommit close delete doBatch getAnchorType? getBounds getContent getFlip getId getMovables getName? getParent getRange getRanges getRotation getSnapshot getVersionId getZIndex isClosed isContentLoaded isDeleted isHidden isLockAspectRatio isProtected moveBackward moveForward moveToBack moveToFront select setAnchorType setBounds setFlip setHidden setLockAspectRatio setRotation toJSON? whenContentLoaded
    isIAnchored: true

    For runtime type checking.

    isIMovable: true

    For runtime type checking.

    isSelected: () => boolean

    Returns a flag indicating if the movable is selected.

    scrollIntoView: (options?: boolean | ScrollIntoViewOptions) => Promise<boolean>

    Scroll the movable into the viewport.

    Type Declaration

      • (options?: boolean | ScrollIntoViewOptions): Promise<boolean>

      • Parameters

        • Optionaloptions: boolean | ScrollIntoViewOptions

        Returns Promise<boolean>

        A promise that resolve to a boolean when the scroll is complete.

    This will return when the scroll view is loaded but before any scroll animations have started or finished.

    unselect: () => boolean

    Remove the movable the current selection.

    Type Declaration

      • (): boolean

      • Returns boolean

        A flag indicating if it was previously in the selection.

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

    • Similar to delete but cleans resources and can't be undone.

      Returns void

    • Deletes the content, which removes this movable. The same as getContent().delete().

      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 movable's unrotated frame in pixels, or null if not yet laid out.

      Returns Bounds | null

      The frame is the box the movable is drawn in before it is turned by getRotation, about its center. A rotated movable is anchored to the cells of the box it occupies as rotated, which Excel takes to be the frame with its width and height swapped when the rotation is within 45° of 90° or 270°, and the frame itself otherwise.

    • Returns the content of the movable: what is drawn at this position.

      Type Parameters

      Returns T

      The content's getType() says which interface to read it as:

      getType() content
      'picture' IPicture
      'chart' IChart
      'shape' IShape — text boxes, callouts and connectors
      'group' IGroup — a group of movables, each a member with its own content
      'slicer' ISlicer
      'checkBox', 'button', 'scrollBar', … IFormControl — a form control, one type per kind (IFormControl.Type)

      A host adds kinds of its own through MovableContentRegistry. Anything else is content that is positioned and saved but not modeled; it answers IMovable.IContent and nothing more.

      The content owns what identifies it: its name, its description and its id. The movable owns where it is drawn. To remove both, delete the content.

      const content = movable.getContent();
      if (content.getType() === 'shape') {
        const text = (content as IShape).getTextFrame()?.getText();
      }
      content.delete();

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

    • The movables this one holds, in z-order (the first is drawn first), or null when its content holds none.

      Returns IMovableCollection | null

      A group's movable holds its members. As on a sheet (ISheet.getMovables), adding to the collection places a movable here, at canvas bounds; deleting a member's content takes it out. Each member's getParent is this movable.

      for (const member of movable.getMovables()?.getItems() ?? []) {
        console.log(member.getContent().getName?.(), member.getBounds());
      }

    • The name of the anchor or null if it has none.

      Returns string | null

    • Returns the movable that holds this one, or null at the root: the movable whose getMovables lists it.

      Returns IMovable | null

      A member's getBounds, getRotation and getFlip are where it is drawn on the canvas, as any movable's are: what holds it hands it, when it is made, the mapping between the space its placement is kept in (a group's child space, as the file states it) and where the holder is drawn, so a member is read and edited like a root and nothing walks the chain. A member's placement changes with every movable above it, and announces IMovable.Events.onBoundsChange when it does.

    • Returns the ranges this object is anchored to, in authored order.

      Parameters

      Returns ICellRanges

      • Never null. An item whose last range was removed by a row/column delete returns an invalid ranges — ask ICellRanges.isInvalid, the same contract as ITable.getDataRange.
      • This is the general accessor. Most anchored types hold exactly one range and declare their own getRange() for it, but data validations, conditional formats and protected ranges are authored as several, and any single range can become several when a delete splits it.

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

    • The order in the z plane. To adjust this use the move methods.

      Returns number

    • Returns if the model has been closed

      Returns boolean

    • Whether the content is the kind's own, rather than a stand-in for a kind still loading.

      Returns boolean

      A kind registered with a loader (MovableContentRegistry.Lazy) is fetched the first time a workbook holds one. Until it arrives, getContent answers a stand-in that has the kind's type, name and description, saves as it was read, and is read-only. Reading a workbook (IWorkbookIO.read) and IMovableCollection.add wait for the load, so this is only ever false for a workbook built directly from JSON.

    • Returns if the model has been deleted

      Returns boolean

    • Returns boolean

      setHidden

    • If the anchor is unable to be modified.

      Returns boolean

    • Move movable backward one layer in the zIndex.

      Returns this

    • Move movable forward one layer in the zIndex.

      Returns this

    • Move movable to the back in the zIndex.

      Returns this

    • Move movable to the font in the zIndex.

      Returns this

    • Selects the current movable.

      Parameters

      Returns Promise<boolean>

      An async boolean indicating the movable was selected.

    • Set the position and size of the movable's unrotated frame, in pixels.

      Parameters

      Returns IMovable

      If only some of the points are provided then only those will be moved. The frame is what getBounds returns; the cells the movable is anchored to follow from it and the rotation.

    • Mirror the content within its frame, left to right and/or top to bottom.

      Parameters

      Returns IMovable

      The frame keeps its position, size and rotation: a flip is applied in the frame's own axes, before the turn, as in Excel. Whether the content can be mirrored is the content's to say (IMovable.IContent.acceptFlip); a chart cannot, and ignores it.

    • If true then the movable object is hidden.

      Parameters

      • hidden: boolean

      Returns IMovable

    • If true then the aspect should be maintained during resize if using the corners or if the api only specifies one dimension.

      Parameters

      • locked: boolean

      Returns IMovable

      Lock aspect ratio will have different default values depending on the movable type.

    • Set the rotation in degrees, clockwise about the frame's center.

      Parameters

      • rotation: number

      Returns IMovable

      The frame keeps its position and size; the cells the movable is anchored to are those of the box it then occupies (see getBounds).

    • If defined this will be called when the containing sheet is being serialized.

      Parameters

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

      Returns IMovable.JSON

    • Resolves with the content once its kind has loaded: at once when it already has, and with the stand-in when the load fails.

      Returns Promise<IContent>

    Settings
    Member Visibility

    On This Page
    Properties
    Methods