Skip to main content

Class: default

Defined in: src/lib/classes/PaintCanvas/index.ts:314

The painting engine: canvas size, layers, brush and eraser settings, custom presets, the selected tool, foreground and background colours, selection, transforms, clipboard, undo/redo history, viewport and input settings. Where its data is kept and who it is shared with are up to the implementer (see onMessage and receive).

Dispatches a change event whenever its own state changes. Layers, brushes and selection dispatch their own change events. Also dispatches pointer when the pointer moves over the canvas.

Example​

const canvas = new PaintCanvas({ width: 1000, height: 800 });
canvas.selectTool(Tool.Brush, { fromToolbar: true });
canvas.setColour("#ff0000"); // the brush colour
canvas.setColour("#ffffff", "background");

Extends​

  • EventTarget

Constructors​

Constructor​

new default(options?): PaintCanvas

Defined in: src/lib/classes/PaintCanvas/index.ts:535

Parameters​

options?​

PaintCanvasOptions = {}

Returns​

PaintCanvas

Overrides​

EventTarget.constructor

Properties​

background​

readonly background: default

Defined in: src/lib/classes/PaintCanvas/index.ts:337

Slow work that waits for pauses in drawing (syncing, the canvas map and layer thumbnails, saving)


brush​

readonly brush: default

Defined in: src/lib/classes/PaintCanvas/index.ts:316

Brush settings


constrainProportions​

constrainProportions: boolean = false

Defined in: src/lib/classes/PaintCanvas/index.ts:403

Whether scaling the Move tool's box keeps its proportions ("Constrain proportions"), from its settings bar and when dragging a handle. Off by default; while drag-scaling, holding Shift turns it on (when off) and Alt turns it off (when on), until released.


createCanvas​

readonly createCanvas: CanvasFactory

Defined in: src/lib/classes/PaintCanvas/index.ts:516

Creates the canvases the app draws on (fake ones in tests)


customPresets​

readonly customPresets: default

Defined in: src/lib/classes/PaintCanvas/index.ts:322

The user's own and imported brush presets, listed with the brush and eraser presets


debugLogShown​

protected debugLogShown: boolean = false

Defined in: src/lib/classes/PaintCanvas/index.ts:334

Whether the debug log shows (see showDebugLog)


eraser​

readonly eraser: default

Defined in: src/lib/classes/PaintCanvas/index.ts:319

Eraser settings


heldTool​

heldTool: Tool | null = null

Defined in: src/lib/classes/PaintCanvas/index.ts:390

Tool used temporarily while a key is held (e.g. Space for pan), overriding the selected tool


input​

readonly input: default

Defined in: src/lib/classes/PaintCanvas/index.ts:340

How the user's input devices control the canvas (scrolling, pinching, touch gestures, focus pen mode)


interfaceVisible​

interfaceVisible: boolean = true

Defined in: src/lib/classes/PaintCanvas/index.ts:396

Whether the interface (toolbar, panels and anything the implementer adds) is visible ("tab" key)


lasso​

readonly lasso: default

Defined in: src/lib/classes/PaintCanvas/index.ts:325

Lasso shape in progress


maxCanvasSize​

readonly maxCanvasSize: number

Defined in: src/lib/classes/PaintCanvas/index.ts:521

The largest canvas width or height allowed


maxLayers​

readonly maxLayers: number

Defined in: src/lib/classes/PaintCanvas/index.ts:524

Most layers the user can have


names​

readonly names: Readonly<PaintCanvasNames>

Defined in: src/lib/classes/PaintCanvas/index.ts:527

Names users see and saved files are called by (see PaintCanvasNames)


palette​

readonly palette: default

Defined in: src/lib/classes/PaintCanvas/index.ts:346

The user's saved colours, shown as swatches


palettes​

readonly palettes: default

Defined in: src/lib/classes/PaintCanvas/index.ts:370

The user's own colour palettes (the one PaintCanvas comes with is palette)


panel​

panel: Panel | null = null

Defined in: src/lib/classes/PaintCanvas/index.ts:393

Open panel, if any


pointer?​

optional pointer?: Point

Defined in: src/lib/classes/PaintCanvas/index.ts:384

The user's pointer position over the canvas, in canvas pixels (undefined when off the canvas)


profiles​

readonly profiles: default

Defined in: src/lib/classes/PaintCanvas/index.ts:349

The user's own profile graphs (and the presets), for shaping how brush settings vary


rendering​

readonly rendering: "cpu" | "gpu"

Defined in: src/lib/classes/PaintCanvas/index.ts:513

Where the canvases draw, chosen when the canvas started (the user's choice for next time is ui.data.rendering)


sampleMode​

sampleMode: SampleMode = "point"

Defined in: src/lib/classes/PaintCanvas/index.ts:406

How the colour sample tool samples ("point" by default)


settingsExtensions​

readonly settingsExtensions: default

Defined in: src/lib/classes/PaintCanvas/index.ts:367

Settings wrapper apps add to the app settings (see SettingsExtension)


shortcuts​

readonly shortcuts: default

Defined in: src/lib/classes/PaintCanvas/index.ts:382

The user's keyboard shortcuts: each configurable action's key combination


strokeLog​

readonly strokeLog: default

Defined in: src/lib/classes/PaintCanvas/index.ts:331

Log of strokes started, ended, cancelled and ignored, with timings, for debugging


tips​

readonly tips: default

Defined in: src/lib/classes/PaintCanvas/index.ts:328

Brush shapes, loaded per preset, on canvases made by createCanvas


tool​

tool: Tool = Tool.Brush

Defined in: src/lib/classes/PaintCanvas/index.ts:387

Selected tool


ui​

readonly ui: default

Defined in: src/lib/classes/PaintCanvas/index.ts:343

The user's interface choices (theme, language and where canvases draw), kept with the other app settings

Accessors​

activeTool​

Get Signature​

get activeTool(): Tool

Defined in: src/lib/classes/PaintCanvas/index.ts:1790

The tool currently in effect: the held tool if a key is held, otherwise the selected tool

Returns​

Tool


assetStores​

Get Signature​

get assetStores(): Readonly<AssetStores>

Defined in: src/lib/classes/PaintCanvas/index.ts:1070

Where the user's assets are kept (see useAssetStores)

Returns​

Readonly<AssetStores>


author​

Get Signature​

get author(): AssetAuthor

Defined in: src/lib/classes/PaintCanvas/index.ts:1752

The author of assets the user makes, e.g. colour palettes (from the presetAuthor option).

Example​
app.palettes.create("Sunset", [], app.author);
Returns​

AssetAuthor


authorHandle​

Get Signature​

get authorHandle(): string

Defined in: src/lib/classes/PaintCanvas/index.ts:1742

The handle of the author of presets the user makes (from the presetAuthor option), or "" if they have none. Their own presets are the ones with this handle (see isOwnAuthor).

Returns​

string


autosave​

Get Signature​

get autosave(): default | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1134

Keeps the user's layers in a store, while one is used (see useLayerStore)

Returns​

default | undefined


backgroundColour​

Get Signature​

get backgroundColour(): string

Defined in: src/lib/classes/PaintCanvas/index.ts:1805

The background colour (the colour that isn't selected) as a hex string, e.g. #ffffff

Returns​

string


colour​

Get Signature​

get colour(): string

Defined in: src/lib/classes/PaintCanvas/index.ts:1800

The brush colour (the selected colour) as a hex string, e.g. #000000

Returns​

string


colours​

Get Signature​

get colours(): Readonly<Record<ColourSlot, string>>

Defined in: src/lib/classes/PaintCanvas/index.ts:1810

Both slots' colours as hex strings, e.g. { foreground: "#000000", background: "#ffffff" }

Returns​

Readonly<Record<ColourSlot, string>>


copyCount​

Get Signature​

get copyCount(): number

Defined in: src/lib/classes/PaintCanvas/index.ts:1497

How many times image data has been copied or cut, to tell whether it was copied here since something else may have been copied in another app (see KeyboardShortcuts).

Returns​

number


debugLog​

Get Signature​

get debugLog(): boolean

Defined in: src/lib/classes/PaintCanvas/index.ts:1325

Whether the debug log shows

Returns​

boolean


documentInfo​

Get Signature​

get documentInfo(): Readonly<DocumentInfo>

Defined in: src/lib/classes/PaintCanvas/index.ts:773

The drawing's details: its ID, name, authors and when it was made and last opened

Returns​

Readonly<DocumentInfo>


drawables​

Get Signature​

get drawables(): readonly DrawableLayer[]

Defined in: src/lib/classes/PaintCanvas/index.ts:621

Everything drawn on the canvas, top first: the user's own layers, then drawings from elsewhere

Returns​

readonly DrawableLayer[]


external​

Get Signature​

get external(): default

Defined in: src/lib/classes/PaintCanvas/index.ts:616

Drawings from elsewhere (e.g. other people's), drawn under the user's own layers (see receive)

Returns​

default


hasClipboard​

Get Signature​

get hasClipboard(): boolean

Defined in: src/lib/classes/PaintCanvas/index.ts:1502

Whether there is copied image data to paste (see copy and cut)

Returns​

boolean


height​

Get Signature​

get height(): number

Defined in: src/lib/classes/PaintCanvas/index.ts:611

Canvas height in pixels

Returns​

number


history​

Get Signature​

get history(): default

Defined in: src/lib/classes/PaintCanvas/index.ts:1354

The user's undoable actions

Returns​

default


layers​

Get Signature​

get layers(): default

Defined in: src/lib/classes/PaintCanvas/index.ts:1795

The user's layers

Returns​

default


paletteSync​

Get Signature​

get paletteSync(): default<ColourPalette> | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1080

Keeps the user's colour palettes in their store, while one is used (see useAssetStores)

Returns​

default<ColourPalette> | undefined


profileSync​

Get Signature​

get profileSync(): default<ProfileGraph> | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1075

Keeps the user's profile graphs in their store, while one is used (see useAssetStores)

Returns​

default<ProfileGraph> | undefined


remoteAutosave​

Get Signature​

get remoteAutosave(): default | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1107

Keeps the drawing in a remote store, while one is used (see useRemoteDocumentStore)

Returns​

default | undefined


selectedColour​

Get Signature​

get selectedColour(): ColourSlot

Defined in: src/lib/classes/PaintCanvas/index.ts:1818

Which colour is selected ("foreground" by default): the brush colour, which colour pickers and the colour sample tool set. The other is the background colour.

Returns​

ColourSlot


selection​

Get Signature​

get selection(): default

Defined in: src/lib/classes/PaintCanvas/index.ts:1344

The mask limiting where drawing applies

Returns​

default


sending​

Get Signature​

get sending(): boolean

Defined in: src/lib/classes/PaintCanvas/index.ts:691

Whether drawing messages are being sent (see startSending)

Returns​

boolean


strokes​

Get Signature​

get strokes(): default

Defined in: src/lib/classes/PaintCanvas/index.ts:1339

Draws brush and eraser strokes

Returns​

default


transform​

Get Signature​

get transform(): default

Defined in: src/lib/classes/PaintCanvas/index.ts:1349

Moves, scales and rotates the active layer's pixels with the Move tool

Returns​

default


viewport​

Get Signature​

get viewport(): default

Defined in: src/lib/classes/PaintCanvas/index.ts:1320

The user's view of the canvas (zoom and position)

Returns​

default


width​

Get Signature​

get width(): number

Defined in: src/lib/classes/PaintCanvas/index.ts:606

Canvas width in pixels

Returns​

number

Methods​

addEventListener()​

addEventListener(type, callback, options?): void

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14380

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

Parameters​

type​

string

callback​

EventListenerOrEventListenerObject | null

options?​

boolean | AddEventListenerOptions

Returns​

void

Inherited from​

EventTarget.addEventListener


applyLasso()​

applyLasso(result): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1725

Apply a finished lasso action to the mask: a shape is added, subtracted or replaces it; a plain click deselects.

Parameters​

result​

LassoResult

Returns​

void


applyPatch()​

applyPatch(layerId, patch): Promise<boolean>

Defined in: src/lib/classes/PaintCanvas/index.ts:1233

Put a patch's pixels onto one of the user's layers (replacing what was there), as an action they can undo. Returns whether it was applied: not for an invalid patch, or if there's no such layer.

Parameters​

layerId​

string

patch​

unknown

Returns​

Promise<boolean>

Example​

await canvas.applyPatch(canvas.layers.active.id, patch);

cancelTransform()​

cancelTransform(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1443

Put transformed pixels back where they were (Escape).

Returns​

void


canvasResized()​

protected canvasResized(width, height): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1917

Called when the canvas size changes, before change is dispatched. Subclasses resize anything of their own here.

Parameters​

width​

number

height​

number

Returns​

void


closePanel()​

closePanel(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:2001

Close the open panel, if any.

Returns​

void


commitTransform()​

commitTransform(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1399

Write the transformed pixels into the layer (Enter, or switching tool). The mask moves with them.

Returns​

void


copiedPng()​

copiedPng(): Promise<Blob | undefined>

Defined in: src/lib/classes/PaintCanvas/index.ts:1512

The copied image data as a PNG, if there is any (e.g. to use as a brush shape).

Returns​

Promise<Blob | undefined>

Example​

const png = await canvas.copiedPng(); // Blob of type "image/png", or undefined

copy()​

copy(): Rect | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1454

Copy the masked image data of the selected layer to the clipboard. Needs a mask with image data inside it; does nothing during a stroke or while a transform is pending. Returns the area copied, if any.

Returns​

Rect | undefined


copyMerged()​

copyMerged(): Rect | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1467

Copy the masked image data of all the shown layers, mixed as they're shown (each layer's opacity and blend mode, without the white background), to the clipboard. Hidden layers are left out. Like copy, it needs a mask with image data inside it, and does nothing during a stroke or while a transform is pending. Returns the area copied, if any.

Returns​

Rect | undefined

Example​

app.selection.selectAll();
app.copyMerged(); // { x: 10, y: 20, width: 30, height: 5 }: the part of the canvas with paint on any shown layer

createDocument()​

createDocument(__namedParameters?): Promise<DrawingDocument>

Defined in: src/lib/classes/PaintCanvas/index.ts:825

The drawing as a document (see DrawingDocument): its details, size, the user's layers and drawings from elsewhere as PNG blobs, and a thumbnail (at most THUMBNAIL_SIZE pixels on its longest side) unless left out. The user is added to its authors.

Parameters​

__namedParameters?​

CreateDocumentOptions = {}

Returns​

Promise<DrawingDocument>

Example​

await myStore.save(await canvas.createDocument());

cut()​

cut(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1533

Copy the masked image data of the selected layer to the clipboard, then remove it from the layer as one undoable action (see deleteMasked).

Returns​

void


deleteMasked()​

deleteMasked(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1543

Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). When the layer's alpha lock is on, it is painted with the background colour instead, keeping its transparency. Needs a mask with image data inside it; does nothing during a stroke or while a transform is pending.

Returns​

void


destroy()​

destroy(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1065

Stop timers the canvas keeps (a change waiting to be marked modified isn't marked). Call it when the canvas is no longer used.

Returns​

void

Example​

canvas.destroy();

dispatchEvent()​

dispatchEvent(event): boolean

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14386

The dispatchEvent() method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. The normal event processing rules (including the capturing and optional bubbling phase) also apply to events dispatched manually with dispatchEvent().

MDN Reference

Parameters​

event​

Event

Returns​

boolean

Inherited from​

EventTarget.dispatchEvent


drawStroke()​

drawStroke(layerId, stroke): boolean

Defined in: src/lib/classes/PaintCanvas/index.ts:1184

Draw a recorded stroke (e.g. received from elsewhere) onto one of the user's layers, as an action they can undo. It isn't sent as a stroke message. Does nothing during a stroke, or if there's no such layer. Returns whether it was drawn.

Parameters​

layerId​

string

stroke​

StrokeData

Returns​

boolean

Example​

canvas.drawStroke(canvas.layers.active.id, strokeMessage);

exportDocument()​

exportDocument(): Promise<DocumentFile>

Defined in: src/lib/classes/PaintCanvas/index.ts:946

The drawing as a document file (see DocumentFile): turn it into JSON to save it as a file.

Returns​

Promise<DocumentFile>

Example​

const json = JSON.stringify(await canvas.exportDocument());

fill()​

fill(slot): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1557

Fill the selected layer with a slot's colour as one undoable action (e.g. fill(canvas.selectedColour) for the brush colour): only the masked area when there is a mask (partly where it is partly), and only existing pixels when the layer's alpha lock is on. Does nothing during a stroke or while a transform is pending.

Parameters​

slot​

ColourSlot

Returns​

void

Example​

canvas.fill("foreground");

flushModified()​

flushModified(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1045

Mark a change still waiting (see DOCUMENT_MODIFIED_EVENT) now: set documentInfo.updatedAt and dispatch modified. Does nothing if no change is waiting. createDocument and remote saving call it so no change is missed.

Returns​

void

Example​

canvas.flushModified();
console.log(canvas.documentInfo.updatedAt); // the latest change

holdTool()​

holdTool(tool): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1983

Use a tool temporarily while a key is held (e.g. Space for pan). The selected tool is unchanged.

Parameters​

tool​

Tool

Returns​

void


importDocument()​

importDocument(file): Promise<boolean>

Defined in: src/lib/classes/PaintCanvas/index.ts:957

Replace the drawing with a document file (e.g. read from a file, see documentFromFile). Returns whether it was opened: not when it isn't a valid document or can't be opened (see openDocument), and then nothing changes.

Parameters​

file​

unknown

Returns​

Promise<boolean>

Example​

await canvas.importDocument(JSON.parse(text));

isBuiltInPreset()​

isBuiltInPreset(id): boolean

Defined in: src/lib/classes/PaintCanvas/index.ts:1734

Whether a preset comes with the app (it can't be deleted, replaced or exported).

Parameters​

id​

string

Returns​

boolean


markSent()​

markSent(area, rgba): void

Defined in: src/lib/classes/PaintCanvas/index.ts:707

Count pixels of the user's drawing as already sent, so they aren't sent again (e.g. their earlier work, restored from a shared drawing's history).

Parameters​

area​

BoundingBox

rgba​

Uint8ClampedArray

Returns​

void


newDocument()​

newDocument(name?): void

Defined in: src/lib/classes/PaintCanvas/index.ts:811

Start a new drawing: new details (a new ID, the user as its author, made now), and the layers replaced with one empty layer. Undo history starts again.

Parameters​

name?​

string

Returns​

void

Example​

canvas.newDocument("Sketch");

newPreset()​

newPreset(settings, name): BrushPreset

Defined in: src/lib/classes/PaintCanvas/index.ts:1765

Make a new custom preset from settings: a new ID, the given name, the author from the presetAuthor option, and made now (updatedAt). It has no group, as groups are only for the presets that come with the app.

Parameters​

settings​

BrushConfig

name​

string

Returns​

BrushPreset

Example​

app.newPreset(app.brush.preset, "My brush");
// { "@type": "PaintCanvas/BrushPreset", id: "0b5c…", name: "My brush", author: { name, handle }, content: settings }

notify()​

protected notify(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:2032

Returns​

void


onMessage()​

onMessage(listener): () => void

Defined in: src/lib/classes/PaintCanvas/index.ts:633

Listen for the drawing messages this canvas sends, e.g. to pass them to other people. Returns a function that stops listening.

Parameters​

listener​

MessageListener

Returns​

() => void

Example​

const stop = canvas.onMessage((message) => transport.send(message));
canvas.startSending();

openDocument()​

openDocument(document): Promise<boolean>

Defined in: src/lib/classes/PaintCanvas/index.ts:894

Replace the drawing with a document (e.g. from a store): its details (marked opened now), size, layers and drawings from elsewhere. Undo history starts again. Returns whether it was opened: not when it has too many layers, is too big, doesn't have its selected layer, or an image can't be decoded, and then nothing changes.

Parameters​

document​

DrawingDocument

Returns​

Promise<boolean>

Example​

await canvas.openDocument(await myStore.load(id));

paste()​

paste(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1671

Show the clipboard's image data over the selected layer where it was copied from, and select the Move tool to place, scale and rotate it. It is written into the layer (and sent) on Enter or when switching to another tool; Escape discards it. A pending transform is applied first.

Returns​

void


pasteImage()​

pasteImage(source): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1691

Show an image from elsewhere (e.g. pasted from another app) over the selected layer, in the middle of the part of the canvas in view, and select the Move tool to place, scale and rotate it, like paste. An image larger than the canvas is shrunk to fit it. Does nothing during a stroke.

Parameters​

source​

CanvasImageSource & object

Returns​

void

Example​

canvas.pasteImage(await createImageBitmap(file));

receive()​

receive(source, message): Promise<boolean>

Defined in: src/lib/classes/PaintCanvas/index.ts:739

Apply a drawing message received from a source (an ID the implementer chooses, e.g. a user ID): a patch is drawn onto that source's sheet. Messages are checked first; invalid ones are ignored. Resolves to whether it was applied.

Parameters​

source​

string

message​

unknown

Returns​

Promise<boolean>

Example​

transport.onMessage((from, message) => canvas.receive(from, message));

redo()​

redo(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1425

Redo the user's latest undone action. A move or rotate that hasn't been applied is cancelled instead, and nothing happens during a stroke.

Returns​

void


releaseHeldTool()​

releaseHeldTool(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1992

Stop using the held tool and return to the selected tool.

Returns​

void


removeEventListener()​

removeEventListener(type, callback, options?): void

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts:14392

The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.

MDN Reference

Parameters​

type​

string

callback​

EventListenerOrEventListenerObject | null

options?​

boolean | EventListenerOptions

Returns​

void

Inherited from​

EventTarget.removeEventListener


renameDocument()​

renameDocument(name): boolean

Defined in: src/lib/classes/PaintCanvas/index.ts:783

Rename the drawing. Returns whether it was renamed (not if the name is empty).

Parameters​

name​

string

Returns​

boolean

Example​

canvas.renameDocument("Sunset at sea");

restoreDocumentInfo()​

restoreDocumentInfo(info): void

Defined in: src/lib/classes/PaintCanvas/index.ts:795

Use details of a drawing being restored (e.g. kept in the browser), marking it opened now. Its updatedAt is kept (one without, from before documents had it, gets its dateCreated).

Parameters​

info​

DocumentInfo

Returns​

void


restoreLayers()​

restoreLayers(width, height, layers, images, activeLayer): void

Defined in: src/lib/classes/PaintCanvas/index.ts:974

Replace the canvas size and the user's layers (top first, each with its image) and select one by ID. Undo history starts again. Throws if the size or number of layers isn't allowed.

Parameters​

width​

number

height​

number

layers​

readonly LayerConfig[]

images​

readonly CanvasImageSource[]

activeLayer​

string

Returns​

void

Example​

canvas.restoreLayers(800, 600, [{ id: "a", name: "Sketch" }], [sketchImage], "a");

sampleAreaColour()​

sampleAreaColour(a, b, maxPixels?): string | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1273

The average colour shown in the rectangle between two canvas points (cut to the canvas), counting every pixel, or undefined outside the canvas. With maxPixels, it's worked out from the area scaled down to at most that many pixels across, which is quicker (for a preview while dragging).

Parameters​

a​

Point

b​

Point

maxPixels?​

number = Number.POSITIVE_INFINITY

Returns​

string | undefined

Example​

app.sampleAreaColour({ x: 0, y: 0 }, { x: 99, y: 99 }); // the average of 100 × 100 pixels

sampleColour()​

sampleColour(point): string | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1259

The colour shown at a canvas point (every layer mixed as shown, over the white background), or undefined outside the canvas.

Parameters​

point​

Point

Returns​

string | undefined

Example​

app.sampleColour({ x: 10.4, y: 20.9 }); // "#ff0000"

samplePixels()​

samplePixels(point): OffscreenCanvas

Defined in: src/lib/classes/PaintCanvas/index.ts:1296

The SAMPLE_PIXELS × SAMPLE_PIXELS canvas pixels around a point as shown (the point's pixel is at the middle, rounding down), for the colour sample tool's enlarged view. Pixels outside the canvas are transparent.

Parameters​

point​

Point

Returns​

OffscreenCanvas


selectColour()​

selectColour(slot): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1849

Select which colour is the brush colour (and set by colour pickers and the colour sample tool); the other becomes the background colour. One colour is always selected.

Parameters​

slot​

ColourSlot

Returns​

void

Example​

canvas.selectColour("background");

selectTool()​

selectTool(tool, options?): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1963

Select a tool.

  • Clicking a toolbar button (fromToolbar: true) only selects the tool: its presets open from the settings bar's preset button.
  • Pressing a tool's shortcut selects the tool, or toggles its panel if the tool is already selected.

Switching tools closes the previous tool's panel (the layers panel and app menu stay open).

Parameters​

tool​

Tool

options?​
fromToolbar?​

boolean

Returns​

void


sendNow()​

sendNow(): Promise<void>

Defined in: src/lib/classes/PaintCanvas/index.ts:699

Send a patch of what changed now instead of waiting. Resolves once sent (or straight away when not sending patches).

Returns​

Promise<void>


setCanvasSize()​

setCanvasSize(width, height): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1867

Change the canvas size, from 1 to the maximum canvas size (maxCanvasSize option). Replaces all layers.

Parameters​

width​

number

height​

number

Returns​

void


setColour()​

setColour(colour, slot?): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1830

Set a slot's colour: the selected one (the brush colour) unless another is given. Must be a 6-digit hex colour, e.g. #ff0000.

Parameters​

colour​

string

slot?​

ColourSlot = ...

Returns​

void

Example​

canvas.setColour("#ff0000"); // the brush colour
canvas.setColour("#ffffff", "background");

setConstrainProportions()​

setConstrainProportions(constrain): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1931

Set whether scaling the Move tool's box keeps its proportions.

Parameters​

constrain​

boolean

Returns​

void


setPointer()​

setPointer(position): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1947

Set where the user's pointer is over the canvas (undefined when it leaves). Dispatches pointer when it moves.

Parameters​

position​

Point | undefined

Returns​

void


setSampleMode()​

setSampleMode(mode): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1939

Set how the colour sample tool samples.

Parameters​

mode​

SampleMode

Returns​

void


showDebugLog()​

showDebugLog(shown): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1332

Show or hide the debug log. Strokes and timings are only recorded while it shows.

Parameters​

shown​

boolean

Returns​

void


snapshot()​

snapshot(): Promise<PatchMessage | undefined>

Defined in: src/lib/classes/PaintCanvas/index.ts:715

A patch of the user's whole drawing (all their layers, flattened), e.g. for someone who joins late. Undefined if nothing is drawn.

Returns​

Promise<PatchMessage | undefined>


startSending()​

startSending(options?): void

Defined in: src/lib/classes/PaintCanvas/index.ts:656

Start sending drawing messages to onMessage listeners:

  • patches (by default): shortly after the user's layers change (and once drawing pauses), the area of their drawing that changed
  • strokes (when asked): each finished brush or eraser stroke
  • undo and redo: the step undone or redone

Changing the canvas size stops sending.

Parameters​

options?​

SendingOptions = {}

Returns​

void


stats()​

stats(): CanvasStats

Defined in: src/lib/classes/PaintCanvas/index.ts:1162

How much the canvas holds: its size, layers, drawings from elsewhere, memory and undo steps.

Returns​

CanvasStats


stopSending()​

stopSending(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:678

Stop sending patches. Changes waiting to be sent are dropped.

Returns​

void


swapColours()​

swapColours(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1858

Swap the two slots' colours, so the brush colour and background colour swap. The selected slot stays the same.

Returns​

void


toggleInterface()​

toggleInterface(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:2018

Show or hide the interface.

Returns​

void


togglePanel()​

togglePanel(panel): void

Defined in: src/lib/classes/PaintCanvas/index.ts:2010

Open a panel, or close it if already open.

Parameters​

panel​

Panel

Returns​

void


undo()​

undo(): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1417

Undo the user's latest action. A move or rotate that hasn't been applied is cancelled instead, and nothing happens during a stroke.

Returns​

void


useAssetStores()​

useAssetStores(stores): void

Defined in: src/lib/classes/PaintCanvas/index.ts:1092

Keep the user's assets in stores, by kind: custom brush presets are loaded from theirs (in place of the current ones) and saved when they change; colour palettes and profile graphs saved there are added and changes saved (see AssetSync). Assets of a kind without a store are kept in memory only.

Parameters​

stores​

AssetStores

Returns​

void

Example​

canvas.useAssetStores({ brushes: new IndexedDbAssetStore("brushes"), profiles: new IndexedDbAssetStore("profiles") });

useLayerStore()​

useLayerStore(store, options?): default | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1146

Keep the user's layers in a store (or stop, without one), so the drawing survives reloading the page: the saved drawing is restored, then changes are saved. Only one window draws on a drawing at a time (see LayerAutosave). Returns the autosave.

Parameters​

store​

LayerStoreLike | undefined

options?​

AutosaveOptions

Returns​

default | undefined

Example​

canvas.useLayerStore(new IndexedDbLayerStore("my-drawing"));

useRemoteDocumentStore()​

useRemoteDocumentStore(store, options?): default | undefined

Defined in: src/lib/classes/PaintCanvas/index.ts:1120

Keep the whole drawing in a remote store (e.g. the user's account online), or stop, without one: changes are saved every few minutes, or in idle mode once drawing pauses and when the page is hidden (see RemoteDocumentAutosave), or when asked with canvas.remoteAutosave.save(). Returns the autosave.

Parameters​

store​

DocumentStoreLike | undefined

options?​

RemoteAutosaveOptions

Returns​

default | undefined

Example​

canvas.useRemoteDocumentStore(myAccountStore, { intervalMs: 10 * 60 * 1000 });
canvas.useRemoteDocumentStore(myAccountStore, { mode: "idle", idleMs: 60 * 1000 });