free-drawing

Appearance

@fabwcie/free-drawing / Drawer / Drawer

Class: Drawer ​

Defined in: packages/free-drawing/src/Drawer.ts:134

Infinite canvas drawing board created in an element: Konva stage of the drawing, toolbar and interface, public API. Events of the drawer are listened with on (see drawerEvents).

Example ​

ts
const drawer = new Drawer(document.getElementById('draw'), {
  width: 500,
  height: 800,
});

Extends ​

Constructors ​

Constructor ​

new Drawer($el, options?): Drawer

Defined in: packages/free-drawing/src/Drawer.ts:246

Create a drawer in an element: its content is replaced by the drawer

Parameters ​

$el ​

HTMLDivElement

Element of the drawer

options? ​

Partial<DrawerOptions> = {}

Options merged with defaultOptions (widgets replaces default list)

Returns ​

Drawer

Overrides ​

default.constructor

Properties ​

_events ​

_events: object = {}

Defined in: packages/free-drawing/src/utils/MicroEvent.ts:46

Listeners by event name, in order of registration

Index Signature ​

[key: string]: TCallback[]

Inherited from ​

default._events

$el ​

$el: HTMLDivElement

Defined in: packages/free-drawing/src/Drawer.ts:148

Element given to the constructor, holding the container of the drawer

$stageContainer ​

$stageContainer: HTMLDivElement

Defined in: packages/free-drawing/src/Drawer.ts:152

Konva content of the stage (its canvases): cursor of active tool is set on it

activeTool ​

activeTool: "pan" | "selection" | "brush" | "eraser" | "undo" | "redo" | "text" | "rect" | "circle" | "ellipse" | "square" | "arrow" | "line" | "star" | "triangle" | "polygon" | "diamond" | "heart" | "cloud" | "highlighter" | "laser" | "frame" = 'brush'

Defined in: packages/free-drawing/src/Drawer.ts:165

Id of active tool, see activeWidget

activeWidget ​

activeWidget: BaseWidget

Defined in: packages/free-drawing/src/Drawer.ts:167

Widget of active tool, set by toolbar.setActiveWidget (activate one with widget.setActive(true))

background ​

background: Rect

Defined in: packages/free-drawing/src/Drawer.ts:172

Background rectangle of the drawing, its color set with setBgColor

bgLayer ​

bgLayer: Layer

Defined in: packages/free-drawing/src/Drawer.ts:237

Layer of background rectangle, first one (not listening), moved with the view

clearConfirmModal ​

clearConfirmModal: ConfirmModal | null = null

Defined in: packages/free-drawing/src/Drawer.ts:196

Confirmation of clearCanvas, created on first use

clearStoredConfirmModal ​

clearStoredConfirmModal: ConfirmModal | null = null

Defined in: packages/free-drawing/src/Drawer.ts:198

Confirmation of clearStoredData, created on first use

collaboration ​

collaboration: Collaboration | null = null

Defined in: packages/free-drawing/src/Drawer.ts:144

Collaboration session: drawing changes sent to and received from other users of a room

collaborationModal ​

collaborationModal: CollaborationModal | null = null

Defined in: packages/free-drawing/src/Drawer.ts:146

Created on first use, see showCollaboration

commandPalette ​

commandPalette: CommandPalette | null = null

Defined in: packages/free-drawing/src/Drawer.ts:202

Created on first use, see showCommandPalette

contextMenu ​

contextMenu: ContextMenu

Defined in: packages/free-drawing/src/Drawer.ts:233

Menu of right click on drawing

debug ​

debug: boolean = false

Defined in: packages/free-drawing/src/Drawer.ts:207

Development messages: collaboration connection logged, toast when shapes are moved without selection tool

drawLayer ​

drawLayer: Layer

Defined in: packages/free-drawing/src/Drawer.ts:159

Drawing shapes, add them with addShape (named ' draw': select it with .draw)

exportModal ​

exportModal: ExportModal | null = null

Defined in: packages/free-drawing/src/Drawer.ts:200

Created on first use, see showExport

grid ​

grid: boolean = false

Defined in: packages/free-drawing/src/Drawer.ts:235

Grid shown (see showGrid, hideGrid), shapes snapped to it

gridLayer ​

gridLayer: Layer

Defined in: packages/free-drawing/src/Drawer.ts:157

Grid shown with showGrid (not listening)

help ​

help: Help

Defined in: packages/free-drawing/src/Drawer.ts:192

Help dialog (shortcuts, documentation links) and its footer button

hotKey ​

hotKey: HotKey

Defined in: packages/free-drawing/src/Drawer.ts:239

Keyboard shortcuts of the drawer (keydown on its container)

i18n ​

i18n: I18n

Defined in: packages/free-drawing/src/Drawer.ts:186

Texts of interface, see t and setLanguage

layersPanel ​

layersPanel: LayersPanel | undefined

Defined in: packages/free-drawing/src/Drawer.ts:180

Panel listing shapes (layersPanel option)

layout ​

layout: DrawerLayout

Defined in: packages/free-drawing/src/Drawer.ts:150

Container of the drawer and regions of its interface, see layout.add

options ​

options: DrawerOptions

Defined in: packages/free-drawing/src/Drawer.ts:169

Options given to the constructor merged with defaults, updated by setters (color, width...) and preferences

position ​

position: Position | undefined

Defined in: packages/free-drawing/src/Drawer.ts:176

Position of view with a button back to origin (positionWidget option)

preferencesModal ​

preferencesModal: PreferencesModal | null = null

Defined in: packages/free-drawing/src/Drawer.ts:204

Created on first use, see showPreferences

readOnly ​

readOnly: boolean = false

Defined in: packages/free-drawing/src/Drawer.ts:136

Drawing can't be modified by user (see setReadOnly)

ready ​

ready: Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:217

Resolved once drawing of storage option is loaded (rejected if it can't be), at once without it

saveButton ​

saveButton: SaveButton | undefined

Defined in: packages/free-drawing/src/Drawer.ts:182

Button of header saving the drawing while auto save is off (saveButton option)

selectionLayer ​

selectionLayer: Layer

Defined in: packages/free-drawing/src/Drawer.ts:161

Transient nodes: transformer, selection rectangle, snapping guides, cursors of collaborators

selectionMenu ​

selectionMenu: SelectionMenu | undefined

Defined in: packages/free-drawing/src/Drawer.ts:178

Menu next to selected shapes (selectionMenu option)

setting ​

setting: Settings

Defined in: packages/free-drawing/src/Drawer.ts:194

Settings menu of header: file actions, collaboration, view toggles, language, background color

socket ​

socket: CollaborationSocket | null = null

Defined in: packages/free-drawing/src/Drawer.ts:142

Collaboration socket, connected during a collaboration session

stage ​

stage: Stage

Defined in: packages/free-drawing/src/Drawer.ts:154

Konva stage: background, grid, drawing and selection layers

theme ​

theme: Theme = 'light'

Defined in: packages/free-drawing/src/Drawer.ts:184

Theme chosen ('system': device one), see setTheme

toolbar ​

toolbar: Toolbar

Defined in: packages/free-drawing/src/Drawer.ts:163

Toolbar of the footer: widgets (tools) and their groups

undoRedo ​

undoRedo: UndoRedo

Defined in: packages/free-drawing/src/Drawer.ts:231

History of drawing (undo / redo) and its footer buttons

zoom ​

zoom: Zoom | undefined

Defined in: packages/free-drawing/src/Drawer.ts:174

Zoom out, level (reset) and zoom in buttons (zoomWidget option)

Accessors ​

$drawerContainer ​

Get Signature ​

get $drawerContainer(): HTMLDivElement

Defined in: packages/free-drawing/src/Drawer.ts:2091

Container of the drawer: canvas and interface (layout.$container)

Returns ​

HTMLDivElement

$footerContainer ​

Get Signature ​

get $footerContainer(): HTMLElement

Defined in: packages/free-drawing/src/Drawer.ts:2107

Footer region of the layout (toolbar, help)

Deprecated ​

use layout.add('footer', $element)

Returns ​

HTMLElement

$footerLeftElement ​

Get Signature ​

get $footerLeftElement(): HTMLDivElement

Defined in: packages/free-drawing/src/Drawer.ts:2115

Start of the footer (zoom, undo / redo)

Deprecated ​

use layout.add('footerStart', $element)

Returns ​

HTMLDivElement

$headerContainer ​

Get Signature ​

get $headerContainer(): HTMLDivElement

Defined in: packages/free-drawing/src/Drawer.ts:2099

Header region of the layout (top left: settings menu, layers button, position)

Deprecated ​

use layout.add('header', $element)

Returns ​

HTMLDivElement

language ​

Get Signature ​

get language(): "en" | "fr" | "es" | "de"

Defined in: packages/free-drawing/src/Drawer.ts:1867

Language of interface shown

Returns ​

"en" | "fr" | "es" | "de"

languageChoice ​

Get Signature ​

get languageChoice(): "en" | "fr" | "es" | "de" | "auto"

Defined in: packages/free-drawing/src/Drawer.ts:1874

Language chosen: 'auto' (browser one) or a language

Returns ​

"en" | "fr" | "es" | "de" | "auto"

user ​

Get Signature ​

get user(): DrawerUser | null

Defined in: packages/free-drawing/src/Drawer.ts:568

User of the app (user option), null for anonymous user

Returns ​

DrawerUser | null

Methods ​

_applyTheme() ​

private _applyTheme(): void

Defined in: packages/free-drawing/src/Drawer.ts:1998

Show theme chosen (drawer-dark class on container), drawer.theme.change event

Returns ​

void

_connected() ​

private _connected(socket): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:667

Resolved when socket is connected, rejected if server can't be reached (no retry)

Parameters ​

socket ​

CollaborationSocket

Socket of the collaboration session being started

Returns ​

Promise<void>

Promise resolved on connection, rejected with the connection error

_createSocket() ​

protected _createSocket(): Promise<CollaborationSocket>

Defined in: packages/free-drawing/src/Drawer.ts:679

Socket connected to collaboration server: true is page origin, string is server url, options give url and data read by server on connection (socket.io client is loaded only then)

Returns ​

Promise<CollaborationSocket>

New socket (new connection each session), connecting

_drawGrid() ​

private _drawGrid(): void

Defined in: packages/free-drawing/src/Drawer.ts:2285

Draw grid: one shape drawing lines of visible area, redrawn with stage (pan, zoom) without creating nodes

Returns ​

void

_duringAction() ​

_duringAction(): boolean

Defined in: packages/free-drawing/src/Drawer.ts:945

Pointer action of active tool or text edition in progress: shortcuts and interface ignore keys and pointer

Returns ​

boolean

True while an action or a text edition is in progress

_getCenter() ​

private _getCenter(shapes): Vector2d

Defined in: packages/free-drawing/src/Drawer.ts:1262

Center of the box of shapes (absolute position)

Parameters ​

shapes ​

DrawingShape[]

Shapes whose client rects make the box

Returns ​

Vector2d

Absolute position of the center of the box

_getOwnerKey() ​

private _getOwnerKey(room): string | undefined

Defined in: packages/free-drawing/src/Drawer.ts:613

Secret of owner of a room created in this browser

Parameters ​

room ​

string

Room id

Returns ​

string | undefined

Owner key kept for this room, undefined if this browser did not create it

_getPointerPos() ​

_getPointerPos(): Vector2d

Defined in: packages/free-drawing/src/Drawer.ts:819

Pointer in view, center of view when pointer is out of canvas (menu, keyboard)

Returns ​

Vector2d

Position relative to the stage container

_getRelativePointerPos() ​

_getRelativePointerPos(): Vector2d

Defined in: packages/free-drawing/src/Drawer.ts:811

Pointer in drawing (view moved and zoomed), center of view when pointer is out of canvas (menu, keyboard)

Returns ​

Vector2d

Position in drawing coordinates

_getStorageItem() ​

private _getStorageItem(key): string | null

Defined in: packages/free-drawing/src/Drawer.ts:1115

Read localStorage item, null if storage is unavailable (blocked cookies, sandboxed iframe...)

Parameters ​

key ​

string

Key of the item

Returns ​

string | null

Item value, null if missing or storage unavailable

_hasPointer() ​

_hasPointer(): boolean

Defined in: packages/free-drawing/src/Drawer.ts:803

Pointer registered by stage: over canvas, or during a pointer action (konva forgets it when pointer leaves canvas)

Returns ​

boolean

True when stage knows a pointer position

_initEvents() ​

private _initEvents(): void

Defined in: packages/free-drawing/src/Drawer.ts:838

Listen to shortcuts, zoom wheel, view moves, shape drags and transforms (frames, linked arrows, collaboration) and drawing changes (change of stage: save, history, drawer.change event)

Returns ​

void

_initHotKey() ​

private _initHotKey(): void

Defined in: packages/free-drawing/src/Drawer.ts:928

Keyboard shortcuts on drawer container

Returns ​

void

_initKeyboardFocus() ​

private _initKeyboardFocus(): void

Defined in: packages/free-drawing/src/Drawer.ts:907

Focus frame on drawer only when focused with keyboard (Tab, Escape from a menu). Not with :focus-visible, which matches after programmatic focus (on load, after tool change...) for mouse users too.

Returns ​

void

_initSnapGridEvents() ​

private _initSnapGridEvents(): void

Defined in: packages/free-drawing/src/Drawer.ts:2180

Snap to grid while grid is shown: dragged shapes (but lines), resize anchors of selection, rotation by 90°

Returns ​

void

_initTheme() ​

private _initTheme(saved?): void

Defined in: packages/free-drawing/src/Drawer.ts:1986

Theme chosen in menu (saved) or by option, device theme followed with 'system'

Parameters ​

saved? ​

Theme

Theme of saved preferences, theme option when undefined

Returns ​

void

_initZoomWheel() ​

private _initZoomWheel(): void

Defined in: packages/free-drawing/src/Drawer.ts:953

Ctrl + wheel zooms around pointer (zoom option), by scaling option

Returns ​

void

private _loadFromLink(): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:1777

Drawing of a link (see getLink) replaces saved one (undo restores it), removed from page url once loaded

Returns ​

Promise<void>

_loadSavedStage() ​

private _loadSavedStage(): Stage | null

Defined in: packages/free-drawing/src/Drawer.ts:1127

Stage saved in localStorage, null if none or invalid (corrupted, other app data...)

Returns ​

Stage | null

Stage created from saved JSON with its required layers, else null

_onActionEnd() ​

_onActionEnd(): void

Defined in: packages/free-drawing/src/Drawer.ts:695

Pointer action of a widget ended: changes of collaborators received meanwhile are applied

Returns ​

void

_onCollaborationRight() ​

_onCollaborationRight(canEdit): void

Defined in: packages/free-drawing/src/Drawer.ts:474

Right to draw of this user given or removed by owner of collaboration room

Parameters ​

canEdit ​

boolean

True when this user may draw (still read only with readOnly option), told in a toast

Returns ​

void

_onSaveError() ​

private _onSaveError(error, type): void

Defined in: packages/free-drawing/src/Drawer.ts:1072

Drawing stays in page, warned once until a save succeeds

Parameters ​

error ​

Error

Error of the save, its message shown in the toast

type ​

"error" | "warning"

Toast type: warning for localStorage, error for app storage

Returns ​

void

_openFromUrl() ​

private _openFromUrl(): void

Defined in: packages/free-drawing/src/Drawer.ts:419

Drawing of a link, or room of a collaboration link

Returns ​

void

_preferencesChanged() ​

_preferencesChanged(): void

Defined in: packages/free-drawing/src/Drawer.ts:1957

A preference may have changed: saved in browser, event once current code ends (several changes give one event)

Returns ​

void

_prepareExport() ​

private _prepareExport(format, options): { box: Box; imageOptions: { background: string | undefined; dark: boolean; scale: number; }; shapes: DrawingShape[]; } | null

Defined in: packages/free-drawing/src/Drawer.ts:1649

Shapes, their box and image options of an export, null if nothing to export

Parameters ​

format ​

ImageFormat

Image format (pdf gets a white background when it has no color)

options ​

ExportImageOptions

Export options, defaults applied

Returns ​

Shapes, box and rendering options, null if nothing to export

Type Literal ​

{ box: Box; imageOptions: { background: string | undefined; dark: boolean; scale: number; }; shapes: DrawingShape[]; }

box ​

box: Box

Area of the image, around shapes

imageOptions ​

imageOptions: object

Rendering options

imageOptions.background ​

background: string | undefined

Background color, none for a transparent image

imageOptions.dark ​

dark: boolean

Dark mode colors

imageOptions.scale ​

scale: number

Pixel ratio of png and pdf

shapes ​

shapes: DrawingShape[]

Shapes exported

null

_readPreferences() ​

private _readPreferences(): Partial<Preferences>

Defined in: packages/free-drawing/src/Drawer.ts:1929

Preferences saved in browser, and choices of previous versions (<key>-theme, <key>-language)

Returns ​

Partial<Preferences>

Valid saved preferences only, empty when none

_removeSnapGridEvents() ​

private _removeSnapGridEvents(): void

Defined in: packages/free-drawing/src/Drawer.ts:2264

Stop snapping to grid (grid hidden)

Returns ​

void

_saveToStorage() ​

private _saveToStorage(storage): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:1045

One save at a time: changes made during a save are saved once it ends (last drawing only)

Parameters ​

storage ​

DrawerStorage

Storage of the app receiving the drawing file

Returns ​

Promise<void>

Promise of the save in progress, resolved once last changes are saved (errors shown in a toast)

_setOwnerKey() ​

private _setOwnerKey(room, ownerKey): void

Defined in: packages/free-drawing/src/Drawer.ts:626

Keep secret of owner of a room in browser (20 last rooms), owner again when coming back to it

Parameters ​

room ​

string

Room id

ownerKey ​

string

Secret proving to the server that this user owns the room

Returns ​

void

_setShapesState() ​

private _setShapesState(changed, apply): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1566

Lock or hide shapes of the drawing (not removed ones), selection updated, change saved

Parameters ​

changed ​

DrawingShape[]

Shapes whose state changes

apply ​

(shape) => void

Changes the state of a shape

Returns ​

boolean

true if a shape changed

_setUnsaved() ​

private _setUnsaved(unsaved): void

Defined in: packages/free-drawing/src/Drawer.ts:1033

Drawing has changes not saved or is saved: drawer.unsaved.change event when it changes

Parameters ​

unsaved ​

boolean

True when drawing has changes not saved, false once saved

Returns ​

void

_setupShape() ​

private _setupShape(shape): void

Defined in: packages/free-drawing/src/Drawer.ts:763

Shape identity for collaboration and layers panel (kept in history and saves), also of shapes in groups (moved with their group, not alone), hit region

Parameters ​

shape ​

DrawingShape

Shape or group added to drawing, shapes of frames set up too

Returns ​

void

_triggerOptionsChange() ​

private _triggerOptionsChange(change): void

Defined in: packages/free-drawing/src/Drawer.ts:1806

Notify overlays (and any listener) that options changed

Parameters ​

change ​

OptionsChange

Changed options only

Returns ​

void

_unScale() ​

private _unScale(val): number

Defined in: packages/free-drawing/src/Drawer.ts:2278

Length of screen (px) in stage coordinates, at current zoom level

Parameters ​

val ​

number

Length on screen (px)

Returns ​

number

Length in stage coordinates

_update() ​

_update(): void

Defined in: packages/free-drawing/src/Drawer.ts:828

Update bg position (grid is redrawn with stage) and position widget, after view move or zoom

Returns ​

void

addShape() ​

addShape<T>(shape): T

Defined in: packages/free-drawing/src/Drawer.ts:750

Add drawing shape (or group) to draw layer, draggable only with selection tool. Every drawing shape must be added with this method (tools, history, collaboration...)

Type Parameters ​

T ​

T extends DrawingShape

Parameters ​

shape ​

T

Shape or group to add on top of drawing, given an id if it has none

Returns ​

T

added shape

canGroupShapes() ​

canGroupShapes(shapes?): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1419

Shapes can be grouped: 2 at least, of the same group (or drawing)

Parameters ​

shapes? ​

DrawingShape[] = ...

Selected shapes by default

Returns ​

boolean

True for 2 shapes or more of the same parent, none of them a frame

clearCanvas() ​

clearCanvas(force?): void

Defined in: packages/free-drawing/src/Drawer.ts:2123

Clear canvas draw

Parameters ​

force? ​

boolean = false

Force clear (don't show confirm modal)

Returns ​

void

clearStoredData() ​

clearStoredData(force?): void

Defined in: packages/free-drawing/src/Drawer.ts:2144

Remove localstorage data

Parameters ​

force? ​

boolean = false

Force clear (don't show confirm modal)

Returns ​

void

copyImage() ​

copyImage(format?, options?): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:1279

Copy image of selected shapes (whole drawing without selection) to clipboard: png image, or svg image and text (pasted as svg code in editors), message shown

Parameters ​

format? ​

"png" | "svg" = 'png'

Image format copied, png by default

options? ​

ExportImageOptions = {}

Export options (selection only, background, dark mode, scale)

Returns ​

Promise<void>

copyLink(): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:1762

Copy link to drawing (see getLink) to clipboard

Returns ​

Promise<void>

deleteShapes() ​

deleteShapes(shapes?): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1357

Remove shapes (selected ones by default), removed from selection

Parameters ​

shapes? ​

DrawingShape[] = ...

Shapes to remove (groups left empty removed too), selected shapes by default

Returns ​

boolean

true if a shape was removed (change saved)

duplicateShapes() ​

duplicateShapes(shapes?): DrawingShape[]

Defined in: packages/free-drawing/src/Drawer.ts:1305

Copy shapes (selected ones by default) a little further, copies are selected

Parameters ​

shapes? ​

DrawingShape[] = ...

Shapes to copy (removed ones ignored), selected shapes by default

Returns ​

DrawingShape[]

copies, on top of drawing (change saved)

exportCanvas() ​

exportCanvas(options?): HTMLCanvasElement | null

Defined in: packages/free-drawing/src/Drawer.ts:1637

Drawing (or selected shapes) rendered on a canvas as exported in png, synchronous (preview), null if nothing to export

Parameters ​

options? ​

ExportImageOptions = {}

Export options (selection only, background, dark mode, scale)

Returns ​

HTMLCanvasElement | null

Canvas of the png image, null if nothing to export

exportImage() ​

exportImage(format, options?): Promise<Blob>

Defined in: packages/free-drawing/src/Drawer.ts:1613

Drawing (or selected shapes) as png, svg or pdf image

Parameters ​

format ​

ImageFormat

Image format

options? ​

ExportImageOptions = {}

Export options (selection only, background, dark mode, scale)

Returns ​

Promise<Blob>

Image file of the format

Throws ​

nothing to export

fitFrame() ​

fitFrame(frame): void

Defined in: packages/free-drawing/src/Drawer.ts:1523

Frame drawn or resized: takes shapes of drawing entirely in it, gives back to drawing its shapes out of it

Parameters ​

frame ​

Frame

Frame drawn or resized

Returns ​

void

fitTextWidth() ​

fitTextWidth(shapes?): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1249

Fit width of texts (selected ones by default, also texts of groups) to their content: box of their longest line, lines no longer wrapped, text stays in place

Parameters ​

shapes? ​

DrawingShape[] = ...

Shapes whose texts are fitted, selected shapes by default

Returns ​

boolean

true if a text changed (change saved)

flipShapes() ​

flipShapes(direction, shapes?): void

Defined in: packages/free-drawing/src/Drawer.ts:1178

Flip shapes (selected ones by default) around the center of their box, texts are still read from left to right

Parameters ​

direction ​

"horizontal" | "vertical"

Horizontal mirrors left and right, vertical mirrors top and bottom

shapes? ​

DrawingShape[] = ...

Shapes to flip (frames ignored), selected shapes by default

Returns ​

void

focus() ​

focus(options?): void

Defined in: packages/free-drawing/src/Drawer.ts:2336

Focus drawer div container (usefull for keyevent for example)

Parameters ​

options? ​

FocusOptions

Focus options of the browser (e.g. preventScroll)

Returns ​

void

getCollaborationLink(room?): string

Defined in: packages/free-drawing/src/Drawer.ts:545

Link to join a room: current page with #room=<id>&by=<user id>, owner knows who shared it

Parameters ​

room? ​

string | undefined = ...

Room id, room of current session by default

Returns ​

string

Url of current page with room hash, without hash when there is no room

getDrawingFile() ​

getDrawingFile(shapes?): DrawingFile

Defined in: packages/free-drawing/src/Drawer.ts:1154

Drawing as file content (.freedrawing file, link): background color and drawing shapes

Parameters ​

shapes? ​

DrawingShape[] = ...

Shapes written in the file, all drawing shapes by default

Returns ​

DrawingFile

Drawing file with background color and states of shapes

getDrawingShapeByName() ​

getDrawingShapeByName(shapeType): (Shape<ShapeConfig> | Group)[]

Defined in: packages/free-drawing/src/Drawer.ts:791

Get all drawing shape by name

Parameters ​

shapeType ​

"selection" | "text" | "rect" | "ellipse" | "arrow" | "line" | "triangle" | "diamond" | "heart" | "cloud" | "highlighter" | "frame" | "background" | "group" | "straightLine" | "guideLine" | "gridLine"

Shape type

Returns ​

(Shape<ShapeConfig> | Group)[]

Top nodes of draw layer having the name of this type

getDrawingShapes() ​

getDrawingShapes(): DrawingShape[]

Defined in: packages/free-drawing/src/Drawer.ts:739

Get all shape drawing

Returns ​

DrawingShape[]

Copy of the top nodes of draw layer (shapes and groups), bottom first

getExportShapes() ​

getExportShapes(selected?): DrawingShape[]

Defined in: packages/free-drawing/src/Drawer.ts:1600

Shapes to export: selected ones when there is a selection, else all drawing shapes

Parameters ​

selected? ​

boolean = true

Selected shapes only

Returns ​

DrawingShape[]

Selected shapes, else visible drawing shapes

getLink(): Promise<string>

Defined in: packages/free-drawing/src/Drawer.ts:1751

Link to current page with drawing in its hash (#<drawer id>=<data>), no server needed

Returns ​

Promise<string>

Url of current page with compressed drawing file in its hash

getPreferences() ​

getPreferences(): Preferences

Defined in: packages/free-drawing/src/Drawer.ts:1894

Interface settings of user (e.g. saved by the app for its logged in user)

Returns ​

Preferences

Current theme, language choice, grid, snapping, zen mode, auto save and keep tool

getSelectedShapes() ​

getSelectedShapes(): DrawingShape[]

Defined in: packages/free-drawing/src/Drawer.ts:1167

Drawing shapes selected with selection tool

Returns ​

DrawingShape[]

Nodes of the transformer, empty without selection widget

getShapeLabel() ​

getShapeLabel(shape): string

Defined in: packages/free-drawing/src/Drawer.ts:1471

Name of a shape (layers panel): name given by user, else first line of a text, else type of shape

Parameters ​

shape ​

DrawingShape

Shape or group to name

Returns ​

string

Label shown for the shape, in current language for a type of shape

getUserId() ​

getUserId(): string

Defined in: packages/free-drawing/src/Drawer.ts:590

Id of this user in collaboration sessions (rights given by owners): of user option, else kept in browser

Returns ​

string

Id of the user, or a new one saved in localStorage (new each session if storage is unavailable)

getUserName() ​

getUserName(): string

Defined in: packages/free-drawing/src/Drawer.ts:643

Name shown to other users in collaboration sessions: given for this visit, else of user option, else kept in browser

Returns ​

string

User name, empty string if none was given

getWidget() ​

getWidget<T>(name): T | undefined

Defined in: packages/free-drawing/src/Drawer.ts:937

Get widget by name

Type Parameters ​

T ​

T

Parameters ​

name ​

"pan" | "selection" | "brush" | "eraser" | "undo" | "redo" | "text" | "rect" | "circle" | "ellipse" | "square" | "arrow" | "line" | "star" | "triangle" | "polygon" | "diamond" | "heart" | "cloud" | "highlighter" | "laser" | "frame"

Widget id

Returns ​

T | undefined

Widget of the toolbar, undefined if it is not in toolbar

getZoomLevel() ​

getZoomLevel(): number

Defined in: packages/free-drawing/src/Drawer.ts:703

Get zoom level

Returns ​

number

Scale of the stage (1 = 100%)

groupShapes() ​

groupShapes(shapes?): Group | null

Defined in: packages/free-drawing/src/Drawer.ts:1387

Group shapes (selected ones by default, 2 at least, of the same group): moved, transformed, hidden, locked, ordered and named together. The group takes place of top shape and is selected

Parameters ​

shapes? ​

DrawingShape[] = ...

Shapes to group, selected shapes by default

Returns ​

Group | null

group (change saved), null if shapes can't be grouped

hasUnsavedChanges() ​

hasUnsavedChanges(): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1002

Drawing has changes not saved yet: without auto save, until save (or saveNow)

Returns ​

boolean

True when changes are not saved

hideGrid() ​

hideGrid(): void

Defined in: packages/free-drawing/src/Drawer.ts:2323

Hide grid

Returns ​

void

isDarkMode() ​

isDarkMode(): boolean

Defined in: packages/free-drawing/src/Drawer.ts:2019

Dark theme shown (chosen, or of device with 'system' theme)

Returns ​

boolean

True when dark theme is shown

loadDrawing() ​

loadDrawing(file): void

Defined in: packages/free-drawing/src/Drawer.ts:1706

Replace drawing by a drawing file content, undo restores previous drawing

Parameters ​

file ​

string | DrawingFile

Content or its JSON

Returns ​

void

Throws ​

not a drawing file

loadFromStorage() ​

loadFromStorage(): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:1084

Load drawing of storage option (on init, again after login...): it replaces drawing (kept if nothing is stored), history starts from it, changes are saved in storage once it is loaded

Returns ​

Promise<void>

Rejected if drawing can't be loaded (shown in a toast): changes are not saved

off() ​

off(events, fct): void

Defined in: packages/free-drawing/src/utils/MicroEvent.ts:71

Remove a listener of events: without listener all listeners of these events, without arguments all listeners

Parameters ​

events ​

string

event name, or several separated by spaces

fct ​

TCallback

listener given to on

Returns ​

void

Inherited from ​

default.off

on() ​

on(events, fct): void

Defined in: packages/free-drawing/src/utils/MicroEvent.ts:58

Listen to events

Parameters ​

events ​

string

event name, or several separated by spaces

fct ​

TCallback

listener, called on each trigger

Returns ​

void

Inherited from ​

default.on

open() ​

open(): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:1735

Open a .freedrawing file chosen by user, it replaces drawing (undo restores it)

Returns ​

Promise<void>

placeInFrames() ​

placeInFrames(shapes): void

Defined in: packages/free-drawing/src/Drawer.ts:1507

Shapes (drawn, moved, transformed) put in the frame containing their center, or back in drawing out of frames. Frames and shapes of groups are not concerned.

Parameters ​

shapes ​

DrawingShape[]

Shapes drawn, moved or transformed

Returns ​

void

reorderShapes() ​

reorderShapes(order, shapes?): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1587

Move shapes in stacking order: forward / backward above / below the next shape they overlap, front / back above / below all shapes (relative order of moved shapes is kept)

Parameters ​

order ​

ShapeOrder

Move: forward, backward, front or back

shapes? ​

DrawingShape[] = ...

Selected shapes by default

Returns ​

boolean

true if a shape moved (change saved)

resetDrawer() ​

resetDrawer(): void

Defined in: packages/free-drawing/src/Drawer.ts:2344

Reset drawer to its initial state: remove drawing (without confirmation), white background and drawing options given on init (color, width, opacity, text style...)

Returns ​

void

rotateShapes() ​

rotateShapes(angle, shapes?): void

Defined in: packages/free-drawing/src/Drawer.ts:1211

Rotate shapes (selected ones by default) around the center of their box

Parameters ​

angle ​

number

Degrees, clockwise when positive (90: quarter turn right, -90: left)

shapes? ​

DrawingShape[] = ...

Shapes to rotate (frames ignored), selected shapes by default

Returns ​

void

save() ​

save(): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:974

Save drawing in storage option (once its drawing is loaded), else in localStorage

Returns ​

Promise<void>

Resolved once saved (errors are shown in a toast)

saveAs() ​

saveAs(name?): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:1721

Save drawing in a .freedrawing file, with browser save dialog when available (Chromium) else downloaded

Parameters ​

name? ​

string = 'drawing'

File name without extension

Returns ​

Promise<void>

saveNow() ​

saveNow(): Promise<void>

Defined in: packages/free-drawing/src/Drawer.ts:993

Save drawing (save) and tell it, from menu and command palette

Returns ​

Promise<void>

setAutoSave() ​

setAutoSave(autoSave): void

Defined in: packages/free-drawing/src/Drawer.ts:1010

Save drawing on each change, or only with save / saveNow (preference): pending changes saved when enabled

Parameters ​

autoSave ​

boolean

True saves on each change, false marks changes unsaved until a save

Returns ​

void

setBgColor() ​

setBgColor(color): void

Defined in: packages/free-drawing/src/Drawer.ts:1794

Change background color

Parameters ​

color ​

ColorLike

Color of the canvas background (change saved)

Returns ​

void

setEdges() ​

setEdges(value): void

Defined in: packages/free-drawing/src/Drawer.ts:2034

Set corners of rectangles (new and selected ones)

Parameters ​

value ​

Edges

'sharp', 'round' (radius following rectangle size) or radius (px, 0 is sharp)

Returns ​

void

setFillColor() ​

setFillColor(color): void

Defined in: packages/free-drawing/src/Drawer.ts:1824

Set background color of rectangles and ellipses (new and selected ones)

Parameters ​

color ​

ColorLike

'transparent' for none

Returns ​

void

setKeepTool() ​

setKeepTool(keepTool): void

Defined in: packages/free-drawing/src/Drawer.ts:1022

Keep drawing tool after drawing a shape, else selection tool is activated, nothing selected (preference)

Parameters ​

keepTool ​

boolean

True keeps the drawing tool, false activates selection tool after each drawing

Returns ​

void

setLanguage() ​

setLanguage(language): void

Defined in: packages/free-drawing/src/Drawer.ts:1882

Set language of interface (saved for next visits): every text is translated at once

Parameters ​

language ​

"en" | "fr" | "es" | "de" | "auto"

'en', 'fr', 'es', 'de' or 'auto' (browser one)

Returns ​

void

setOpacity() ​

setOpacity(opacity): void

Defined in: packages/free-drawing/src/Drawer.ts:2046

Set opacity of shape 0 to 1

Parameters ​

opacity ​

number

Opacity of new shapes (0 transparent, 1 opaque), applied to selected ones

Returns ​

void

setPreferences() ​

setPreferences(preferences): void

Defined in: packages/free-drawing/src/Drawer.ts:1910

Apply interface settings (given ones only), one drawer.preferences.change event

Parameters ​

preferences ​

Partial<Preferences>

Grid wins when grid and snapping are both true

Returns ​

void

setReadOnly() ​

setReadOnly(readOnly): void

Defined in: packages/free-drawing/src/Drawer.ts:443

Read only: drawing can't be modified by user (tools except pan, shortcuts and menu items modifying drawing, text edition), API methods still modify it

Parameters ​

readOnly ​

boolean

True disables tools modifying drawing (pan activated), false enables them and the previous tool

Returns ​

void

setShapeLabel() ​

setShapeLabel(shape, label, save?): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1488

Give a name to a shape (saved with it), an empty name gives back its default name (frames: their title)

Parameters ​

shape ​

DrawingShape

Shape or group to name

label ​

string

New name, trimmed (empty removes it)

save? ​

boolean = true

Change saved (default true)

Returns ​

boolean

true if name changed

setShapesHidden() ​

setShapesHidden(hidden, shapes?): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1553

Hide shapes (selected ones by default): not drawn, selected nor exported

Parameters ​

hidden ​

boolean

True hides shapes, false shows them

shapes? ​

DrawingShape[] = ...

Shapes to hide or show, selected shapes by default

Returns ​

boolean

true if a shape changed (change saved)

setShapesLocked() ​

setShapesLocked(locked, shapes?): boolean

Defined in: packages/free-drawing/src/Drawer.ts:1540

Lock shapes (selected ones by default): not moved, transformed nor erased on canvas, only selected to be unlocked

Parameters ​

locked ​

boolean

True locks shapes, false unlocks them

shapes? ​

DrawingShape[] = ...

Shapes to lock or unlock, selected shapes by default

Returns ​

boolean

true if a shape changed (change saved)

setSize() ​

setSize(width, height): void

Defined in: packages/free-drawing/src/Drawer.ts:2363

Resize the stage (px), e.g. when the window of a drawer of window size is resized

Parameters ​

width ​

number

New width of the stage (px)

height ​

number

New height of the stage (px)

Returns ​

void

setStrokeColor() ​

setStrokeColor(color): void

Defined in: packages/free-drawing/src/Drawer.ts:1814

Set color for draw

Parameters ​

color ​

ColorLike

Stroke color of new shapes, applied to selected ones

Returns ​

void

setStrokeStyle() ​

setStrokeStyle(style): void

Defined in: packages/free-drawing/src/Drawer.ts:1846

Set stroke style of lines, arrows, rectangles and ellipses (new and selected ones)

Parameters ​

style ​

StrokeStyle | number[] | undefined

'solid', 'dashed' or 'dotted' (deprecated dash array gives 'dashed', undefined 'solid')

Returns ​

void

setStrokeWidth() ​

setStrokeWidth(width): void

Defined in: packages/free-drawing/src/Drawer.ts:1834

Set stroke width for draw

Parameters ​

width ​

string | number

Stroke width (px) of new shapes, applied to selected ones (string converted to number)

Returns ​

void

setTextStyle() ​

setTextStyle(style): void

Defined in: packages/free-drawing/src/Drawer.ts:2056

Set text style (font family, size, style, decoration, align) of new and selected text

Parameters ​

style ​

Partial<TextStyle>

Changed properties only, merged with current text style

Returns ​

void

setTheme() ​

setTheme(theme): void

Defined in: packages/free-drawing/src/Drawer.ts:2009

Set theme (saved for next visits): in dark mode, drawing is shown with inverted colors, its colors are kept

Parameters ​

theme ​

Theme

'light', 'dark' or 'system' (device one)

Returns ​

void

setUser() ​

setUser(user): void

Defined in: packages/free-drawing/src/Drawer.ts:576

User logged in or out: their id is used by next collaboration sessions, their name at once

Parameters ​

user ​

DrawerUser | null

null for anonymous user (id and name kept in browser)

Returns ​

void

setUserName() ​

setUserName(name): void

Defined in: packages/free-drawing/src/Drawer.ts:651

Change name shown to other users (current session and next ones)

Parameters ​

name ​

string

New name, trimmed and cut to 40 characters

Returns ​

void

setZoomLevel() ​

setZoomLevel(scale, point?): void

Defined in: packages/free-drawing/src/Drawer.ts:712

Set zoom level, limited from 10% to 3000%

Parameters ​

scale ​

number

Zoom level (1 = 100%)

point? ​

Vector2d = ...

Absolute position that stays in place, stage center by default

Returns ​

void

showCollaboration() ​

showCollaboration(joinRoom?, invitedBy?): void

Defined in: packages/free-drawing/src/Drawer.ts:560

Live collaboration dialog: owner starts / stops session, shares link and QR code, gives rights; other users give their name

Parameters ​

joinRoom? ​

string | null = null

Room of a link, joined once user gave a name

invitedBy? ​

string

Id of user who shared the link

Returns ​

void

showCommandPalette() ​

showCommandPalette(): void

Defined in: packages/free-drawing/src/Drawer.ts:1688

Command palette: search a tool or command available now and run it

Returns ​

void

showExport() ​

showExport(): void

Defined in: packages/free-drawing/src/Drawer.ts:1680

Export dialog: preview, png, svg, pdf, drawing file, copy to clipboard

Returns ​

void

showGrid() ​

showGrid(): void

Defined in: packages/free-drawing/src/Drawer.ts:2162

Show grid

Returns ​

void

showPreferences() ​

showPreferences(): void

Defined in: packages/free-drawing/src/Drawer.ts:1696

Preferences dialog: theme, language, zen mode, grid, snapping, name in collaboration sessions

Returns ​

void

startCollaboration() ​

startCollaboration(room?, name?, invitedBy?): Promise<string>

Defined in: packages/free-drawing/src/Drawer.ts:486

Start a live collaboration session in a room (collaboration option gives the server), current session is stopped

Parameters ​

room? ​

string

Room id, new room by default

name? ​

string = ...

Name shown to other users, saved for next sessions

invitedBy? ​

string

Id of user who shared the link (see getCollaborationLink), shown to owner

Returns ​

Promise<string>

Link to join the room

stopCollaboration() ​

stopCollaboration(): void

Defined in: packages/free-drawing/src/Drawer.ts:526

Stop live collaboration session (drawing is kept)

Returns ​

void

t() ​

t(key, params?): string

Defined in: packages/free-drawing/src/Drawer.ts:1860

Text of interface in current language

Parameters ​

key ​

"drawer.label" | "language.auto" | "toast.collaborationUnavailable" | "toast.canDraw" | "toast.viewOnly" | "toast.saveFailed" | "toast.saved" | "toast.loadFailed" | "toast.invalidFile" | "toast.linkCopied" | "toast.linkNotCopied" | "toast.invalidLink" | "toast.clipboardUnavailable" | "toast.exportFailed" | "toast.imageCopied" | "toast.imageNotCopied" | "toast.selectionTool" | "modal.close" | "confirm.message" | "confirm.clearCanvas" | "confirm.clearStorage" | "confirm.cancel" | "confirm.confirm" | "menu.label" | "menu.open" | "menu.saveAs" | "menu.save" | "menu.unsaved" | "menu.copyLink" | "menu.collaboration" | "menu.collaborationOn" | "menu.collaborationUsers" | "menu.export" | "menu.clearCanvas" | "menu.showGrid" | "menu.zenMode" | "menu.darkMode" | "menu.github" | "menu.githubLabel" | "menu.clearStorage" | "menu.background" | "menu.language" | "menu.commands" | "menu.preferences" | "preferences.title" | "preferences.autoSave" | "preferences.save" | "preferences.appearance" | "preferences.theme" | "preferences.light" | "preferences.dark" | "preferences.system" | "preferences.drawing" | "commands.search" | "commands.empty" | "commands.file" | "commands.language" | "color.white" | "color.lightGray" | "color.lightBlue" | "color.lightYellow" | "color.lightBeige" | "color.lightRed" | "color.lightGreen" | "color.black" | "color.red" | "color.green" | "color.blue" | "color.orange" | "color.yellow" | "color.pink" | "color.transparent" | "color.custom" | "help.title" | "help.documentation" | "help.issue" | "help.shortcuts" | "help.tools" | "help.editor" | "help.view" | "help.or" | "help.selectAll" | "help.deleteSelection" | "help.duplicate" | "help.group" | "help.selectInGroup" | "help.constrainDrawing" | "help.whileDrawing" | "help.arrowUnlinked" | "help.constrainSelection" | "help.whileTransforming" | "help.move" | "help.forwardBackward" | "help.frontBack" | "help.lock" | "help.paste" | "help.open" | "help.save" | "help.export" | "help.grid" | "help.layers" | "help.layersSelect" | "help.snap" | "help.zoom" | "help.toolsConstrain" | "key.delete" | "key.arrows" | "key.click" | "key.space" | "key.wheel" | "toolbar.label" | "toolbar.moreTools" | "toolbar.keepTool" | "tools.pan" | "tools.selection" | "tools.brush" | "tools.eraser" | "tools.text" | "tools.line" | "tools.square" | "tools.circle" | "tools.arrow" | "tools.triangle" | "tools.diamond" | "tools.heart" | "tools.cloud" | "tools.highlighter" | "tools.laser" | "tools.frame" | "zoom.label" | "zoom.out" | "zoom.in" | "zoom.reset" | "history.label" | "history.undo" | "history.redo" | "position.label" | "position.recenter" | "context.paste" | "context.snap" | "context.lock" | "context.unlock" | "selectionMenu.label" | "action.duplicate" | "action.group" | "action.ungroup" | "action.sendToBack" | "action.sendBackward" | "action.bringForward" | "action.bringToFront" | "action.delete" | "action.rotateRight" | "action.rotateLeft" | "action.flipHorizontal" | "action.flipVertical" | "action.fitTextWidth" | "action.copyPng" | "action.copySvg" | "overlay.tool" | "overlay.selection" | "overlay.shape" | "overlay.brush" | "overlay.highlighter" | "overlay.text" | "overlay.stroke" | "overlay.color" | "overlay.background" | "overlay.strokeWidth" | "overlay.strokeStyle" | "overlay.edges" | "overlay.opacity" | "overlay.layers" | "width.thin" | "width.medium" | "width.thick" | "width.extraThick" | "style.solid" | "style.dashed" | "style.dotted" | "edges.sharp" | "edges.round" | "edges.radius" | "edges.auto" | "text.fontFamily" | "text.fontSize" | "text.small" | "text.medium" | "text.large" | "text.extraLarge" | "text.style" | "text.bold" | "text.italic" | "text.underline" | "text.strikethrough" | "text.align" | "text.alignLeft" | "text.alignCenter" | "text.alignRight" | "layers.title" | "layers.group" | "layers.close" | "layers.empty" | "layers.drag" | "layers.shapesOf" | "layers.hide" | "layers.lock" | "layers.delete" | "layers.name" | "layers.toggle" | "layers.range" | "shapes.freehand" | "shapes.line" | "shapes.rect" | "shapes.ellipse" | "shapes.arrow" | "shapes.triangle" | "shapes.diamond" | "shapes.heart" | "shapes.cloud" | "shapes.highlighter" | "shapes.frame" | "shapes.frameName" | "shapes.text" | "shapes.group" | "export.title" | "export.empty" | "export.options" | "export.selected" | "export.background" | "export.dark" | "export.scale" | "export.saveAs" | "export.saveFile" | "export.copy" | "export.preview" | "collab.title" | "collab.intro" | "collab.introInvited" | "collab.introJoined" | "collab.introJoinedOf" | "collab.name" | "collab.anonymous" | "collab.link" | "collab.copy" | "collab.qrCode" | "collab.start" | "collab.join" | "collab.stop" | "collab.connected" | "collab.connecting" | "collab.you" | "collab.invitedBy" | "collab.canDrawLabel" | "collab.canDraw" | "collab.newUsersCanDraw" | "collab.owner" | "collab.viewOnly"

Key of the text in translations

params? ​

TranslationParams

Values of {name} placeholders

Returns ​

string

Translated text with placeholders replaced

toast() ​

toast(message, type?, timeout?, showIcon?): Toast

Defined in: packages/free-drawing/src/Drawer.ts:2071

Show toast message for user

Parameters ​

message ​

string

Message to show

type? ​

"error" | "neutral" | "info" | "warning" | "danger"

Type of toast

timeout? ​

number

Delay (ms) before it hides, 5000 by default, 0 keeps it shown

showIcon? ​

boolean

Show the icon of its type (default true)

Returns ​

Toast

Toast shown

toggleDarkMode() ​

toggleDarkMode(): void

Defined in: packages/free-drawing/src/Drawer.ts:2026

Switch between light and dark themes

Returns ​

void

trigger() ​

trigger(events, ...args): void

Defined in: packages/free-drawing/src/utils/MicroEvent.ts:99

Call listeners of events, in order of registration

Parameters ​

events ​

string

event name, or several separated by spaces

args ​

...any

arguments given to listeners

Returns ​

void

Inherited from ​

default.trigger

UIPointerEvents() ​

UIPointerEvents(state): void

Defined in: packages/free-drawing/src/Drawer.ts:2084

Interface panels receive pointer or not (--drawer-pointer-events)

Parameters ​

state ​

"none" | "all"

'none' during pointer actions, 'all' after

Returns ​

void

Deprecated ​

use layout.setPointerEvents

ungroupShapes() ​

ungroupShapes(shapes?): DrawingShape[]

Defined in: packages/free-drawing/src/Drawer.ts:1432

Ungroup groups (selected ones by default): their shapes take their place with the same look (transform, hidden, locked) and are selected

Parameters ​

shapes? ​

DrawingShape[] = ...

Groups to ungroup (other shapes and frames ignored), selected shapes by default

Returns ​

DrawingShape[]

shapes of groups (change saved)