Class CanvasHelper

A wrapper for the CANVAS element that scales the canvas for high-DPI displays and helps with resizing.

const canvas = new CanvasHelper(`#my-canvas`, { resizeLogic: `both` });
const { ctx, width, height } = canvas.ctx; // Get drawing context, width & height

Draw whenever it is resized using the 'resize' event

canvas.addEventListener(`resize`, ({ctx, size}) => {
 // Use ctx...  
});

Or provide a function when initialising:

const onResize = (ctx, size) => {
 // Do drawing
}
const canvas = new CanvasHelper(`#my-canvas`, { resizeLogic: `both`, onResize });

Automatically draw at animation speeds:

const draw = () => {
}
const canvas = new CanvasHelper(`#my-canvas`, { resizeLogic: `both`, draw });

Hierarchy (view full)

SimpleEventEmitter<CanvasEvents>
- CanvasHelper

Index

Constructors

constructor

new CanvasHelper(domQueryOrEl, opts?): CanvasHelper
Parameters
- domQueryOrEl: Readonly<
      | undefined
      | null
      | string
      | HTMLCanvasElement>
- opts: Partial<Readonly<{
      clearOnResize: boolean;
      colourSpace: PredefinedColorSpace;
      coordinateScale: ScaleBy;
      disablePointerEvents: boolean;
      draw?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void);
      height: number;
      onResize?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void);
      pixelZoom: number;
      resizeLogic?: ElementResizeLogic;
      skipCss: boolean;
      width: number;
      zIndex: number;
  }>> = {}
Returns CanvasHelper
Overrides SimpleEventEmitter.constructor

Properties

`Readonly`el

el: HTMLCanvasElement

`Readonly`opts

opts: Readonly<{
    clearOnResize: boolean;
    colourSpace: PredefinedColorSpace;
    coordinateScale: ScaleBy;
    disablePointerEvents: boolean;
    draw?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void);
    height: number;
    onResize?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void);
    pixelZoom: number;
    resizeLogic?: ElementResizeLogic;
    skipCss: boolean;
    width: number;
    zIndex: number;
}>

Type declaration

clearOnResize: boolean
If true (default) canvas is cleared when a resize happens
colourSpace: PredefinedColorSpace
Colour space to use. Defaults to sRGB.
coordinateScale: ScaleBy
disablePointerEvents: boolean
By default, the helper emits pointer events from the canvas. Set this to true to disable.
Optionaldraw?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void)
If specified, this function be called in an animation loop.
- - (ctx, size, helper): void
  - Parameters
    - ctx: CanvasRenderingContext2D
      Drawing context
    - size: Rect
      Viewport size
    - helper: CanvasHelper
      CanvasHelper instance
    Returns void
height: number
Logical height of canvas. This is used for establishing the desired aspect ratio.
OptionalonResize?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void)
Callback when canvas is resized
- - (ctx, size, helper): void
  - Parameters
    - ctx: CanvasRenderingContext2D
    - size: Rect
    - helper: CanvasHelper
    Returns void
pixelZoom: number
By default the display DPI is used for scaling. If this is set, this will override.
OptionalresizeLogic?: ElementResizeLogic
Automatic canvas resizing logic.
skipCss: boolean
If true, it won't add any position CSS
width: number
Logical width of canvas. This is used for establishing the desired aspect ratio.
zIndex: number
If set, the z-index for this canvas. By default, fullscreen canvas will be given -1

Accessors

center

get center(): {
x: number;
y: number;
}
Gets the center coordinate of the canvas

Returns {
x: number;
y: number;
}
- x: number
- y: number

ctx

get ctx(): CanvasRenderingContext2D
Gets the drawing context

Returns CanvasRenderingContext2D

dimensionMax

get dimensionMax(): number
Returns the width or height, whichever is largest

Returns number

dimensionMin

get dimensionMin(): number
Returns the width or height, whichever is smallest

Returns number

height

get height(): number
Gets the logical height of the canvas See also: width, size

Returns number

isDisposed

get isDisposed(): boolean
Returns boolean
Inherited from SimpleEventEmitter.isDisposed

logicalCenter

get logicalCenter(): {
x: number;
y: number;
}
Returns {
x: number;
y: number;
}
- x: number
- y: number

ratio

get ratio(): number
Gets the current scaling ratio being used to compensate for high-DPI display

Returns number

size

get size(): Rect
Gets the logical size of the canvas See also: width, height

Returns Rect

toAbsolute

get toAbsolute(): Scaler

Returns a Scaler that converts from relative to absolute coordinates. This is based on the canvas size.

// Assuming a canvas of 800x600
toAbsolute({ x: 1, y: 1 });      // { x: 800, y: 600}
toAbsolute({ x: 0, y: 0 });      // { x: 0, y: 0}
toAbsolute({ x: 0.5, y: 0.5 });  // { x: 400, y: 300}

Returns Scaler

toAbsoluteFixed

get toAbsoluteFixed(): Scaler
Returns a scaler for points based on width & height

Returns Scaler

toRelative

get toRelative(): Scaler

Returns a Scaler that converts from absolute to relative coordinates. This is based on the canvas size.

   * // Assuming a canvas of 800x500
toRelative({ x: 800, y: 600 });  // { x: 1,   y: 1 }
toRelative({ x: 0, y: 0 });   // { x: 0,   y: 0 }
toRelative({ x: 400, y: 300 }); // { x: 0.5, y: 0.5 }

Returns Scaler

toRelativeFixed

get toRelativeFixed(): Scaler
Returns a scaler for points based on width & height

Returns Scaler

viewport

get viewport(): RectPositioned
Returns RectPositioned

width

get width(): number
Gets the logical width of the canvas See also: height, size

Returns number

Methods

addEventListener

addEventListener<K>(name, listener): void
Adds event listener.
Type Parameters
- K extends keyof CanvasEvents
  Events
Parameters
- name: K
  Event name
- listener: ((event: CanvasEvents[K], sender: SimpleEventEmitter<CanvasEvents>) => void)
  Event handler
  - - (event, sender): void
    - Parameters
      event: CanvasEvents[K]
      sender: SimpleEventEmitter<CanvasEvents>
      Returns void
Returns void
Throws
Error if emitter is disposed

Inherited from SimpleEventEmitter.addEventListener

clear

clear(): void
Clears the canvas.

Shortcut for: ctx.clearRect(0, 0, this.width, this.height)

Returns void

dispose

dispose(reason?): void
Parameters
- Optionalreason: string
Returns void
Overrides SimpleEventEmitter.dispose

drawBounds

drawBounds(strokeStyle?): void
Parameters
- strokeStyle: string = ...
Returns void

fill

fill(colour?): void
Fills the canvas with a given colour.

Shortcut for:
```
   * ctx.fillStyle = ``;
ctx.fillRect(0, 0, this.width, this.height);
```
Parameters
- Optionalcolour: string
  Colour
Returns void

`Protected`fireEvent

fireEvent<K>(type, args): void
Fire event
Type Parameters
- K extends keyof CanvasEvents
Parameters
- type: K
  Type of event
- args: CanvasEvents[K]
  Arguments for event
Returns void
Inherited from SimpleEventEmitter.fireEvent

getDrawHelper

getDrawHelper(): void
Creates a drawing helper for the canvas. If one is already created it is reused.

Returns void

getImageData

getImageData(): ImageData
Gets the image data for the canvas. Uses the 'physical' canvas size. Eg. A logical size of 400x400 might be 536x536 with a high-DPI display.

Returns ImageData

getPhysicalSize

getPhysicalSize(): {
height: number;
width: number;
}
Gets the drawable area of the canvas. This accounts for scaling due to high-DPI displays etc.

Returns {
height: number;
width: number;
}
- height: number
- width: number

getRectangle

getRectangle(): RectPositioned
Returns RectPositioned

getWritableBuffer

getWritableBuffer(): {
    flip: (() => void);
    get: GridCellAccessor<Rgb8Bit>;
    grid: Grid;
    set: GridCellSetter<Rgb>;
}
Returns the canvas frame data as a writable grid. When editing, make as many edits as needed before calling flip, which writes buffer back to the canvas.
```
   * const g = helper.getWritableBuffer();
// Get {r,g,b,opacity} of pixel 10,10
const pixel = g.get({ x: 10, y: 10 });

// Set a colour to pixel 10,10
g.set({ r: 0.5, g: 1, b: 0, opacity: 0 }, { x: 10, y: 10 });

// Write buffer to canvas
g.flip();
```
Uses 'physical' size of canvas. Eg with a high-DPI screen, this will mean a higher number of rows and columns compared to the logical size.
Returns {
    flip: (() => void);
    get: GridCellAccessor<Rgb8Bit>;
    grid: Grid;
    set: GridCellSetter<Rgb>;
}
- flip: (() => void)
  - - (): void
    - Returns void
- get: GridCellAccessor<Rgb8Bit>
- grid: Grid
- set: GridCellSetter<Rgb>

removeEventListener

removeEventListener<K>(type, listener): void
Remove event listener
Type Parameters
- K extends keyof CanvasEvents
Parameters
- type: K
- listener: ((event: CanvasEvents[K], sender: SimpleEventEmitter<CanvasEvents>) => void)
  - - (event, sender): void
    - Parameters
      event: CanvasEvents[K]
      sender: SimpleEventEmitter<CanvasEvents>
      Returns void
Returns void
Inherited from SimpleEventEmitter.removeEventListener

setLogicalSize

setLogicalSize(logicalSize): void
Parameters
- logicalSize: Rect
Returns void

Class CanvasHelper

Hierarchy (view full)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns CanvasHelper

Properties

Readonlyel

Readonlyopts

Type declaration

clearOnResize: boolean

colourSpace: PredefinedColorSpace

coordinateScale: ScaleBy

disablePointerEvents: boolean

Optionaldraw?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void)

Parameters

Returns void

height: number

OptionalonResize?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void)

Parameters

Returns void

pixelZoom: number

OptionalresizeLogic?: ElementResizeLogic

skipCss: boolean

width: number

zIndex: number

Accessors

center

Returns { x: number; y: number; }

x: number

y: number

ctx

Returns CanvasRenderingContext2D

dimensionMax

Returns number

dimensionMin

Returns number

height

Returns number

isDisposed

Returns boolean

logicalCenter

Returns { x: number; y: number; }

x: number

y: number

ratio

Returns number

size

Returns Rect

toAbsolute

Returns Scaler

toAbsoluteFixed

Returns Scaler

toRelative

Returns Scaler

toRelativeFixed

Returns Scaler

viewport

Returns RectPositioned

width

Returns number

Methods

addEventListener

Type Parameters

Parameters

Parameters

Returns void

Returns void

Throws

clear

Returns void

dispose

Parameters

Returns void

drawBounds

`Readonly`el

`Readonly`opts

`Optional`draw?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void)

`Optional`onResize?: ((ctx: CanvasRenderingContext2D, size: Rect, helper: CanvasHelper) => void)

`Optional`resizeLogic?: ElementResizeLogic

Returns {
x: number;
y: number;
}

Returns {
x: number;
y: number;
}

`Protected`fireEvent

Returns {
height: number;
width: number;
}

Returns {
flip: (() => void);
get: GridCellAccessor<Rgb8Bit>;
grid: Grid;
set: GridCellSetter<Rgb>;
}