@sheetxl/models/types/drawing/IDrawingModel.d.ts

Models - A Headless javascript spreadsheet library.

import { RemoveListener, Bounds, Point, CellCoords, SetOptions } from "@sheetxl/common";
import { SerializableProperties } from "../primitives";
import { ISharedResource } from "../resource";
import { IListenerSource, ListenerEvent } from "../listener";
import { CellRangeCoordsAddress, HyperlinkValues } from "../cell";
import { IAnchoredItemListener, AnchorType, IAnchoredItem } from "../anchor";
export interface IDrawingModelListener extends IAnchoredItemListener {
    /**
     * Called when the drawing bounds are updated.
     * @param bounds
     */
    onBoundsChange?(bounds: Bounds): void;
    /**
     * Called when the Drawing model has changed.
     *
     * This is not called when individual properties on the view change.
     * @param src
     */
    onAnyChange?(src: IDrawingModel | null | undefined): void;
}
export interface IDrawingModel<J extends DrawingJSON = DrawingJSON> extends IAnchoredItem {
    /**
     * Set the absolution position of a drawing in pixels.
     * If only some of the points are provided then only those will be moved.
     * @param bounds T
     */
    setBounds(bounds: Partial<Bounds>, options?: SetOptions): void;
    /**
     * Return the absolute bounds of the drawing object in pixels.
     */
    getBounds(): Bounds;
    /**
     * Set the name for a drawing object.
     * @param name
     */
    setName(name: string): void;
    /**
     * @see #setName
     */
    getName(): string;
    /**
     * This is the alternative text use for assistive technologies.
     * @defaultValue null
     */
    setDescription(description: string): void;
    /**
     * @see #setDescription
     */
    getDescription(): string;
    /**
     * If true then the drawing object is hidden.
     * @defaultValue false
     */
    setHidden(hidden: boolean): void;
    /**
     * @see #setHidden
     */
    isHidden(): boolean;
    /**
     * Set the rotation in degrees.
     * @defaultValue 0
     */
    setRotation(rotation: number): void;
    /**
     * @see #setHidden
     */
    getRotation(): number;
    /**
     * If true then the aspect should be maintained during resize if using the corners or if
     * the api only specifies one dimension.
     *
     * @defaultValue depends on the drawing type.
     */
    setLockAspectRatio(locked: boolean): void;
    /**
     * @see #setLockAspectRatio
     */
    isLockAspectRatio(): boolean;
    /**
     * The order in the z plane. To adjust this use the move methods.
     */
    readonly zIndex: number;
    /**
     * Move drawing to the back in the zIndex.
     */
    moveToBack: () => void;
    /**
     * Move drawing backward one layer in the zIndex.
     */
    moveBackward: () => void;
    /**
     * Move drawing to the font in the zIndex.
     */
    moveToFront: () => void;
    /**
     * Move drawing forward one layer in the zIndex.
     */
    moveForward: () => void;
    /**
     * Unique type for the drawing object.
     */
    readonly type: string;
    /**
     * All for listen to changes to the sheet. To remove listener call the returned function.
     * @param listener
     * @returns An unsubscribe function
     */
    addListener: (listener: IDrawingModelListener) => RemoveListener;
    /**
     * If defined this will be called when the containing sheet is being
     * serialized.
     */
    toJSON?(toResourceId?: (resource: ISharedResource) => number): DrawingAnchorJSON<J>;
    /**
     * For runtime inspection.
     */
    readonly isDrawing: true;
    /**
     * A specific uuid for use in memory.
     * @remarks
     * Useful for caches and react keys. This is not persisted.
     */
    readonly uuid: string;
}
/**
 * Interface to support copying drawings to other containers.
 */
export interface ICopyableDrawingModel<J extends DrawingJSON = DrawingJSON> extends IDrawingModel<J> {
    /**
     * Return any copyable sources for the drawing object.
     * @param bounds
     */
    getCopyableDrawings(bounds: Bounds): ICopyableDrawingModel[];
    /**
     * Called when the drawing is copied to a new container.
     */
    copyTo(destination: IDrawingContainer, bounds: Bounds): IDrawingModel<J>;
    /**
     * Allow items to be copied as text.
     */
    toText?(): Promise<string> | string;
    /**
     * Allow items to be copied as html.
     */
    toHtml?(): Promise<string> | string;
    /**
     * Allow items to be copied as an image Blob.
     */
    toImage?(): Promise<Blob> | Blob;
    /**
     * For runtime introspection.
     */
    readonly isCopyableDrawing: true;
}
export interface DrawingSearchOptions {
    /**
     * The type of overlay to search for. If not provided all overlays will be returned.
    */
    type?: string;
    /**
     * This is if the drawings are hidden due to hidden rows or columns. or because they hidden flag is true
     *
     * @defaultValue false
     */
    includeHidden?: boolean;
    /**
     * If provided, the search will be limited to the range.
    */
    range?: CellRangeCoordsAddress;
    /**
     * Only find items in this bounds
     */
    bounds?: Bounds;
}
export interface TypedAddDrawingOptions<J extends DrawingJSON = DrawingJSON> extends AddDrawingOptions<J> {
    /**
     * The type of drawing to add.
     */
    type: string;
    /**
     * If a referenceId is provided then the drawing will be linked to the resource.
     * @param resourceId
     * @returns ISharedResource
     */
    fromResourceId?: (resourceId: number) => ISharedResource;
}
export interface AddDrawingOptions<J extends DrawingJSON = DrawingJSON> {
    /**
     * Initial drawing value.
     */
    drawing?: J;
    /**
     * The boundary for the drawing object in pixels.
     */
    bounds?: Partial<Bounds>;
    /**
     * The initial anchor for the drawing object.
     * @defaultValue TwoCell for Shapes and OneCell for Images
     */
    anchorType?: AnchorType;
    /**
     * Used for transactional operations.
     */
    description?: string;
    /**
     * Auto select after creation
     * @defaultValue true
     */
    autoSelect?: boolean;
}
export declare enum DrawingContainerListenerType {
    Drawings = "drawings"
}
export interface DrawingContainerEvent<T> extends ListenerEvent<T> {
    type: string;
}
/**
 * Implemented by ISheetModel
 */
export interface IDrawingContainer<T = any> extends IListenerSource<DrawingContainerEvent<T>> {
    /**
     * Add a drawing to the container
     * @param options
     * @returns
     */
    addDrawing(options?: TypedAddDrawingOptions): IDrawingModel;
    /**
     * Return drawings that match the search criteria.
     * If no search criteria is provided, all drawings will be returned.
     * @param options {@link DrawingSearchOptions}
     * @returns
     */
    searchDrawings(options?: DrawingSearchOptions): IDrawingModel[];
    /**
     * Return the total drawings available.
     * This is useful for quick escape of searching drawings.
     */
    getDrawingsCount(): number;
    /**
     * Update all of the selected drawing in a single transaction
     */
    updateSelectedDrawings(update: (drawing: IDrawingModel) => void, action?: string): void;
}
export declare enum DrawingContainerViewListenerType {
    DrawingSelection = "drawingSelection"
}
export interface DrawingContainerViewEvent<T> extends ListenerEvent<T> {
    type: string;
}
export interface IDrawingContainerView<T = any> extends IListenerSource<DrawingContainerViewEvent<T>> {
    /**
     * The drawing selection
     */
    drawingSelection: readonly IDrawingModel[];
    /**
     * Select a drawing object.
     * @param drawing
     * @param addToSelection
     */
    selectDrawings(drawing: readonly IDrawingModel[], addToSelection?: boolean): void;
    /**
     * Returns the drawing from the selection.
     * @param drawing
     */
    unselectDrawings(drawing: IDrawingModel[]): void;
}
export interface OffsetCoords extends CellCoords, Partial<Point> {
}
export interface DrawingAnchorOffset {
    tl: OffsetCoords;
    br: OffsetCoords;
}
export interface DrawingAnchorJSON<J = DrawingJSON> {
    type: string;
    /**
     * The anchor for the drawing object.
     */
    anchor: DrawingAnchorOffset;
    /**
     * The behavior of how the drawing resizes as the anchor/cells change.
     */
    anchorType?: AnchorType;
    drawing: J;
}
export interface DrawingClientData {
    /**
     * disable selection on drawing elements when the sheet is protected
     * @defaultValue false
     */
    fLocksWithSheet?: boolean;
    /**
     * print drawing elements when printing the sheet
     * @defaultValue true
     */
    fPrintsWithSheet?: boolean;
}
export interface DrawingJSON {
    /**
     * The name of the drawing object.
     */
    name?: string;
    /**
     * This is the alternative text use for assistive technologies.
     * @defaultValue null
     */
    desc?: string;
    /**
     * If true then the drawing object is hidden.
     * @defaultValue false
     */
    hidden?: boolean;
    /**
     * The rotation in degrees.
     * @defaultValue 0
     */
    rotation?: number;
    /**
     * A hyperlink for the entire drawing area
     */
    hyperlink?: SerializableProperties<HyperlinkValues>;
    /**
     * A unique identifier for the drawing object.
     * This is not used by SheetXL
     */
    id?: string;
    /**
     * lock specific fields*/
    locks?: any;
    /**
     * Whether resizing should keep the aspect ratio.
     */
    lockAspect?: boolean;
}
export interface DrawingGraphicFrameJSON extends DrawingJSON {
    /**
     * localName of the graphicFrame
     */
    type: string;
    /**
     * Data for the graphicFrame
     */
    gf: any;
}
export interface DrawingChartJSON extends DrawingJSON {
    /**
     * charting data
     */
    chart: any;
}
export interface DrawingShapeJSON extends DrawingJSON {
    /**
     * The preset Geometry for the shape. This could also be custom.
     * @defaultValue 'rect'
     */
    presetGeom?: string;
}
export interface DrawingConnectionShapeJSON extends DrawingShapeJSON {
    cxnSp?: any;
}
export interface DrawingGroupShapeJSON extends DrawingShapeJSON {
    grpSp?: any;
}
//# sourceMappingURL=IDrawingModel.d.ts.map