@avolutions/canvas-painter
Version:
CanvasPainter.js is a simple yet powerful JavaScript library for drawing basic shapes (rectangles, circles, etc.) on HTML5 Canvas with ease. Perfect for creating 2D graphics in your web projects.
267 lines (266 loc) • 10.3 kB
TypeScript
import { ICanvasOptions } from "./options/interfaces/ICanvasOptions.js";
import { IShape } from "./shapes/IShape.js";
import { ICanvasStyle } from "./styles/interfaces/ICanvasStyle.js";
import { Point } from "./types/Point.js";
/**
* Class representing a Canvas element that can manage and render shapes.
*/
export declare class Canvas {
/** Stores instances of `Canvas` associated with HTML canvas elements. */
private static readonly instances;
/** The HTML canvas element being managed. */
private _canvas;
/** The 2D rendering context of the canvas. */
private _context;
/** Configuration options for the canvas, including dimensions. */
private _options;
/** Styling options for the canvas, such as border color and width. */
private _style;
/** List of shapes being watched for changes and re-rendered. */
private watchedShapes;
/** Current zoom scale factor of the canvas. */
private _zoomScale;
/** Current offset for panning, representing how much the canvas has been moved along the x and y axes. */
private _panOffset;
/** Indicates whether panning is currently active. */
private _isPanning;
/** The starting point of the pan operation. This is the position where the user initiated the panning action. */
private _panStart;
/** The shape currently being hovered over by the mouse. */
private _hoverShape;
/** The shape currently being dragged. */
private _dragShape;
/** The last mouse position of the drag operation. */
private _dragPosition;
/**
* Constructs a new Canvas instance.
*
* @param canvas - The HTML canvas element.
* @param context - The 2D rendering context of the canvas.
* @param options - Optional configuration options for the canvas.
* @param style - Optional styling options for the canvas.
*/
private constructor();
/**
* Adds event listeners for the canvas element.
*/
private addEventListener;
/**
* Removes all registered event listeners from the canvas element to prevent memory leaks and
* disable specific interactions.
*/
private removeEventListener;
/**
* Handles the `contextmenu` event to prevent the default context menu from appearing.
*
* @param event - The mouse event that triggers the context menu.
*/
private readonly onContextMenu;
/**
* Handles the `wheel` event for zooming in or out.
* When zooming, the current mouse position is used as the zoom center if panning is active.
*
* @param event - The wheel event that triggers the zoom action.
*/
private readonly onWheel;
/**
* Handles the `mousedown` event to start the panning action.
* The panning will only start if the pressed mouse button is configured for panning.
*
* @param event - The mouse event that triggers the panning action.
*/
private readonly onMouseDown;
/**
* Handles the `mousemove` event to update the panning offset.
* This is triggered when the user drags the canvas while panning.
*
* @param event - The mouse event that triggers the pan movement.
*/
private readonly onMouseMove;
/**
* Handles the `mouseup` and `mouseleave` events to stop the panning action.
* This is triggered when the user releases the mouse or when the mouse leaves the canvas.
*
* @param event - The mouse event that triggers the end of the panning action.
*/
private readonly onMouseUp;
/**
* Handles the mouse leave event for the canvas.
* This method is triggered when the mouse leaves the canvas area,
* setting the state of all watched shapes to `Default`.
*
* @param event - The mouse event that triggered this handler.
*/
private readonly onMouseLeave;
/**
* Retrieves the height of the canvas element, prioritizing the provided options,
* then the HTML canvas element's height attribute, followed by CSS height, and finally
* falls back to the default height.
*
* @param options - Optional canvas options that may contain a height.
* @returns The height value based on the order of priority described.
*/
private getHeight;
/**
* Retrieves the width of the canvas element, prioritizing the provided options,
* then the HTML canvas element's width attribute, followed by CSS width, and finally
* falls back to the default width.
*
* @param options - Optional canvas options that may contain a width.
* @returns The width value based on the order of priority described.
*/
private getWidth;
/**
* Returns the center point of the canvas based on its width and height.
*
* @returns The center point of the canvas as a `Point` object.
*/
getCenter(): Point;
/**
* Retrieves the CSS width and height dimensions of the canvas element by
* computing the styles applied to it. If the values are not present, it returns
* undefined for both width and height.
*
* @returns An object containing the CSS width and height, if available.
*/
private getCssDimensions;
/**
* Initializes a Canvas instance by retrieving the canvas element by ID and its context.
*
* @param id - The ID of the HTML canvas element.
* @param options - Optional configuration options for the canvas.
* @param style - Optional styling options for the canvas.
*
* @returns A new Canvas instance.
*
* @throws ReferenceError if the canvas element is not found.
* @throws TypeError if the element is not a valid canvas or can't get 2d context.
*/
static init(id: string, options?: ICanvasOptions, style?: ICanvasStyle): Canvas;
/**
* Sets the canvas and context styles based on the provided CanvasStyle.
*
* @param style - The style settings to apply to the canvas and context.
*/
private applyStyle;
/**
* Registers a shape or an array of shapes to be watched for changes and renders them.
*
* @param shapeOrShapes - The shape(s) to watch and render on the canvas.
* @param redraw - Whether to immediately redraw the canvas after registering the shape(s).
*/
watch(shapeOrShapes: IShape | IShape[], redraw?: boolean): void;
/**
* Unregisters a shape or an array of shapes from being watched and re-renders the canvas.
*
* @param shapeOrShapes - The shape(s) to stop watching.
* @param redraw - Whether to immediately redraw the canvas after unregistering the shape(s).
*/
unwatch(shapeOrShapes: IShape | IShape[], redraw?: boolean): void;
/**
* Gets the 2D rendering context of the canvas.
*
* @returns The 2D context of the canvas.
*/
get context(): CanvasRenderingContext2D;
/**
* Clears the canvas by removing all content.
*/
clear(): void;
/**
* Observes changes in shapes and triggers the canvas redraw process.
*/
private observerRedraw;
/**
* Clears the canvas and re-renders all watched and visible shapes.
*/
redraw(): void;
/**
* Renders the specified shape on the canvas if shape is visible.
*
* @param shape - The shape to render.
*/
draw(shape: IShape): void;
/**
* Zooms in on the canvas by increasing the zoom scale.
* If a position is provided, the zoom will be centered around that point.
* Otherwise, it defaults to zooming in on the center of the canvas.
*
* @param position - Optional position to center the zoom on.
*/
zoomIn(position?: Point): void;
/**
* Zooms out on the canvas by decreasing the zoom scale.
* If a position is provided, the zoom will be centered around that point.
* Otherwise, it defaults to zooming out from the center of the canvas.
*
* @param position - Optional position to center the zoom on.
*/
zoomOut(position?: Point): void;
/**
* Applies the zoom step to the canvas. The zoom scale is adjusted by the
* given `zoomStep`, and the pan offset is recalculated to keep the zoom
* centered on the provided position (or the center of the canvas if no
* position is provided).
*
* @param zoomStep - The zoom step to apply (positive to zoom in, negative to zoom out).
* @param position - Optional position to center the zoom on.
*/
private applyZoom;
/**
* Resets the zoom scale to its default value (1).
* If the canvas is both zoomable and pannable, it resets both zoom and pan.
*/
resetZoom(): void;
/**
* Resets the pan offset to its default value (0, 0).
*/
resetPan(): void;
/**
* Resets both the zoom scale and pan offset to their default values (1 for zoom scale and (0, 0) for pan).
*/
resetZoomPan(): void;
/**
* Gets the current zoom scale of the canvas.
* A value of `1` represents 100% zoom. Values below `1` indicate zooming out,
* and values above `1` indicate zooming in.
*
* @returns The current zoom scale.
*/
get zoomScale(): number;
/**
* Sets the zoom scale of the canvas and applies the zoom.
*
* @param value - The new zoom scale to set.
*/
set zoomScale(value: number);
/**
* Gets the current pan offset of the canvas.
*
* @returns The current pan offset as a `Point` object.
*/
get panOffset(): Point;
/**
* Enables or disables features like panning, zooming, and dragging shapes.
* Automatically adds or removes event listeners as needed.
*
* @param value - `true` to enable, `false` to disable interactivity.
*/
set interactive(value: boolean);
/**
* Sets the pan offset of the canvas and triggers a redraw.
*
* @param value - The new pan offset to set.
*/
set panOffset(value: Point);
/**
* Sets a specified state for all shapes being watched.
*
* @param state - The state to set for all watched shapes.
*/
private setStateForAllShapes;
/**
* Resets the canvas cursor style to the default cursor.
*/
private resetCursor;
}