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
readonlybackground: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
readonlybrush: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
readonlycreateCanvas:CanvasFactory
Defined in: src/lib/classes/PaintCanvas/index.ts:516
Creates the canvases the app draws on (fake ones in tests)
customPresets
readonlycustomPresets: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
protecteddebugLogShown:boolean=false
Defined in: src/lib/classes/PaintCanvas/index.ts:334
Whether the debug log shows (see showDebugLog)
eraser
readonlyeraser: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
readonlyinput: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
readonlylasso:default
Defined in: src/lib/classes/PaintCanvas/index.ts:325
Lasso shape in progress
maxCanvasSize
readonlymaxCanvasSize:number
Defined in: src/lib/classes/PaintCanvas/index.ts:521
The largest canvas width or height allowed
maxLayers
readonlymaxLayers:number
Defined in: src/lib/classes/PaintCanvas/index.ts:524
Most layers the user can have
names
readonlynames:Readonly<PaintCanvasNames>
Defined in: src/lib/classes/PaintCanvas/index.ts:527
Names users see and saved files are called by (see PaintCanvasNames)
palette
readonlypalette:default
Defined in: src/lib/classes/PaintCanvas/index.ts:346
The user's saved colours, shown as swatches
palettes
readonlypalettes: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?
optionalpointer?: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
readonlyprofiles: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
readonlyrendering:"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
readonlysettingsExtensions:default
Defined in: src/lib/classes/PaintCanvas/index.ts:367
Settings wrapper apps add to the app settings (see SettingsExtension)
shortcuts
readonlyshortcuts:default
Defined in: src/lib/classes/PaintCanvas/index.ts:382
The user's keyboard shortcuts: each configurable action's key combination
strokeLog
readonlystrokeLog:default
Defined in: src/lib/classes/PaintCanvas/index.ts:331
Log of strokes started, ended, cancelled and ignored, with timings, for debugging
tips
readonlytips: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
readonlyui: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
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
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
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
layers
Get Signature
get layers():
default
Defined in: src/lib/classes/PaintCanvas/index.ts:1795
The user's layers
Returns
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
selection
Get Signature
get selection():
default
Defined in: src/lib/classes/PaintCanvas/index.ts:1344
The mask limiting where drawing applies
Returns
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
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
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
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.
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
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()
protectedcanvasResized(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?
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().
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
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
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
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
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
name
string
Returns
Example
app.newPreset(app.brush.preset, "My brush");
// { "@type": "PaintCanvas/BrushPreset", id: "0b5c…", name: "My brush", author: { name, handle }, content: settings }
notify()
protectednotify():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
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
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.
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
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
b
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
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
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
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
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
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
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
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
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?
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?
Returns
default | undefined
Example
canvas.useRemoteDocumentStore(myAccountStore, { intervalMs: 10 * 60 * 1000 });
canvas.useRemoteDocumentStore(myAccountStore, { mode: "idle", idleMs: 60 * 1000 });