Driving the editor

Everything a person does on the canvas, done from code.

The editor has a method for everything a person does on the canvas, and the tools use the same methods. So what you can do with the mouse, a script can do too: build a board from your data, react to a button outside the canvas, or test your own plugin without a browser.

Make shapes

createShape takes a kind, a place and the props that differ from the kind's defaults. A line's ends can be tied to shapes by their ids. Run it, and the board above fills.

import type { Editor } from '@klementine/draw';

/** Two shapes and an arrow between them, as one undo step. */
export default function run(editor: Editor) {
	// Everything after a mark undoes together.
	editor.history.mark();
	const idea = editor.createShape({
		kind: 'geo',
		x: 0,
		y: 0,
		props: { w: 180, h: 100, text: 'Idea' }
	});
	const plan = editor.createShape({
		kind: 'geo',
		x: 320,
		y: -20,
		props: { geo: 'ellipse', w: 140, h: 140, text: 'Plan' },
		style: { color: 'blue', fill: 'tint' }
	});
	// An arrow attached at both ends: it follows when either shape moves.
	editor.createShape({
		kind: 'line',
		x: 0,
		y: 0,
		props: { arrow: true, start: idea.id, end: plan.id }
	});
	editor.zoomToFit();
}

Change them

updateShape changes a record; nothing else needs to know. The arrow follows, because an attached end is worked out from the shape each time it is drawn.

import type { Editor } from '@klementine/draw';

/** Moves the first box down a little; the arrow attached to it follows. */
export default function run(editor: Editor) {
	const box = editor.getShapes().find((shape) => shape.kind === 'geo');
	if (!box) return 'Add the shapes first.';
	editor.history.mark();
	editor.updateShape(box.id, { y: box.y + 60 });
}

Work on the selection

What the right-click menu offers is a method too: align, space evenly, flip, group, lock, bring to front.

import type { Editor } from '@klementine/draw';

/** Picks everything and lines it up along the middle. */
export default function run(editor: Editor) {
	editor.selectAll();
	editor.alignSelection('middle');
}

Read the document

The whole board is a list of plain records. This is what is saved, sent to other tabs and written to a file.

import type { Editor } from '@klementine/draw';

/** Reads the whole document: plain records, ready to save or send. */
export default function run(editor: Editor) {
	const { records } = editor.getDocument();
	const shapes = records.filter((record) => record.type === 'shape');
	return `${records.length} records, ${shapes.length} of them shapes.`;
}

Undo

Each example above is one step, because it marks the history before it starts.

import type { Editor } from '@klementine/draw';

/** Takes back the last step, as Ctrl Z would. */
export default function run(editor: Editor) {
	editor.undo();
}

Listen

editor.store.listen calls you after every change with the diff and where it came from. Saving, the history and the channel between tabs are all built this way.

const stop = editor.store.listen((diff, source) => {
	if (source === 'user') send(diff);
});

The methods are listed, with what each does, in the API reference.