API

Static functions#

Function	Returns
`MathCanvas.init(target, options)`	`Instance`
`MathCanvas.initAll(selector, options)`	`Instance[]`
`MathCanvas.get(target)`	`Instance \| null`
`MathCanvas.getAll()`	`Instance[]`
`MathCanvas.destroyAll()`	`void`
`MathCanvas.parseDocument(raw)`	`{ doc, view } \| null`
`MathCanvas.emptyDocument()`	`Document`
`MathCanvas.isEmptyDocument(doc)`	`boolean`
`MathCanvas.version`	`string`
`MathCanvas.DOC_VERSION`	`number`

`init(target, options)`#

target: a CSS selector or an Element; throws Error when nothing matches. options: see Configuration.

The instance is usable the moment the call returns. Calling it again on the same element returns the existing instance.

`initAll(selector = '[data-math-canvas]', options)`#

Options are read from each element's data-* attributes and override options. Elements that already have an instance are skipped.

`parseDocument(raw)`#

A pure function; it touches no DOM. It applies exactly the sanitising rules setDocument() uses.

Instance properties#

Property	Type
`id`	`string`
`element`	`Element` — the element passed to `init`
`container`	`Element` — the frame the bundle created
`ready`	`Promise`
`destroyed`	`boolean`

Methods#

Method	Returns
`getDocument()`	`Envelope`
`getDocumentJSON()`	`string`
`setDocument(doc)`	`this`
`isEmpty()`	`boolean`
`clear()`	`this`
`undo()` / `redo()`	`this`
`fitView()`	`this`
`getTool()`	`string`
`setTool(id)`	`this`
`focus()`	`this`
`toSVG(options)`	`string \| null`
`toPNG(options)`	`Promise<Blob>`
`exportImage(format, options)`	`Promise<ExportPayload>`
`downloadSVG(name, options)`	`this`
`downloadPNG(name, options)`	`Promise<boolean>`
`clearStorage()`	`this`
`on(type, fn)` / `off(type, fn)`	`this`
`destroy()`	`void`

Every state-changing method renders synchronously; reading the result on the next statement is valid.

board.setTool('point');
board.getTool();          // 'point'

setDocument() and clear() push an undo step.

destroy() removes the interface, the keyboard listener and the ResizeObserver, emits destroy, and drops the instance from the registry. Without it those listeners stay alive after the element leaves the DOM. Calling it repeatedly is harmless.

Tool identifiers#

Group	`id`
Manipulation	`select`, `hand`
Construction	`point`, `segment`, `line`, `ray`, `circle`, `ellipse`, `arc`
Annotation	`angle`, `text`
Coordinates	`numberline`, `oxy`, `oxyz`, `curve`, `vartable`

Events#

board.on(type, handler)    // handler(payload, board)
board.off(type, handler)
board.off(type)            // drop every listener of this type

Type	Emitted when	`payload`
`ready`	Initialisation finished	`{}`
`change`	The document changed	`{}`
`export`	An export button is pressed in `handoff` mode	`ExportPayload`
`destroy`	Just before the instance is torn down	`{}`

change is not emitted for viewport changes alone, nor for the document loaded through the document option. Frequency: every stroke, every drag step past the 3 px threshold, every style change.

Exceptions thrown from a listener are caught and logged to the console.

onReady, onChange and onExport in options are equivalent to on() at initialisation time.

API