Writing a plugin
A kind of shape of your own, its tool, its picture and its place in the toolbar.
Every kind of shape and every tool in Draw is a plugin, also the ones it comes with. A plugin is a list of classes for the engine and, for the screen, a view and an entry in the toolbar. This page builds one: a voting dot, as used in workshops to pick among ideas. It runs below.
Dark mode first
A shortcut list
Export to PDF
Pick Vote in the toolbar (or press B) and click a note. Each click is a vote.
The kind and its tool
A ShapeUtil says what a dot is to the engine: its default props, its box, what
counts as touching it, and its outline (for hover and selection). It draws nothing. The tool is
a StateNode with one state that waits for a click; a tool with more to do (a drag, a second
click) has a state for each step.
import { ShapeUtil, StateNode } from '@klementine/draw';
import type { Box, PointerInfo, ShapeRecord, StyleKey, Vec } from '@klementine/draw';
/** A voting dot, as plain data: its record. */
export type DotShape = ShapeRecord<'dot', { r: number }>;
/** What the engine knows about a dot: size, touch, resize. */
export class DotUtil extends ShapeUtil<DotShape> {
static override kind = 'dot';
// The style panel offers only a colour for dots.
override readonly styles: readonly StyleKey[] = ['color'];
defaultProps() {
return { r: 12 };
}
bounds(shape: DotShape): Box {
const d = shape.props.r * 2;
return { x: 0, y: 0, w: d, h: d };
}
override hitTest(shape: DotShape, point: Vec, margin: number) {
const { r } = shape.props;
return Math.hypot(point.x - r, point.y - r) <= r + margin;
}
override outline(shape: DotShape) {
const { r } = shape.props;
const arc = `a${r},${r} 0 1,0`;
return `M0,${r}${arc} ${r * 2},0${arc} ${-r * 2},0z`;
}
// A vote is a vote: dots keep their size.
override canResize() {
return false;
}
resize(shape: DotShape) {
return { x: shape.x, y: shape.y, props: shape.props };
}
}
/** Waits for a click; each click puts a dot there. */
class Idle extends StateNode {
static override id = 'idle';
override onEnter() {
this.editor.cursor.set('crosshair');
}
override onPointerDown(event: PointerInfo) {
if (event.button !== 0) return;
const { editor } = this;
const { x, y } = editor.inputs.page;
const r = 12;
editor.history.mark();
// Red, like the stickers in a workshop, so a dot shows on any note.
const style = { color: 'red' as const };
editor.createShape({ kind: 'dot', x: x - r, y: y - r, style });
editor.history.mark();
}
override onCancel() {
this.editor.setTool('select');
}
}
/** The dot tool: a state machine with one state. */
export class DotTool extends StateNode {
static override id = 'dot';
static override initial = 'idle';
static override children = () => [Idle];
} The view
A Svelte component draws one shape in its own space; the canvas puts it in place, turns it and
cuts it off at a frame's edge. --kd-color is the shape's colour from its style.
<script lang="ts">
import type { ShapeViewProps } from '@klementine/draw/svelte';
import type { DotShape } from './dot.ts';
// How a dot looks: drawn in its own space, the canvas puts it in place.
let { shape }: ShapeViewProps<DotShape> = $props();
const r = $derived(shape.props.r);
</script>
<svg class="kd-svg">
<circle cx={r} cy={r} {r} fill="var(--kd-color)" />
</svg> The plugin
The plugin puts them together: the kind, the tool, the key that picks it, the view and the toolbar's entry. Give it to the editor and the toolbar with the others.
import type { DrawSveltePlugin } from '@klementine/draw/svelte';
import { DotTool, DotUtil } from './dot.ts';
import DotIcon from './dot-icon.svelte';
import DotView from './dot-view.svelte';
/** The kind, its tool, the key, the view, the place in the toolbar. */
export const dotPlugin: DrawSveltePlugin = {
name: 'dot',
shapes: [DotUtil],
tools: [DotTool],
shortcuts: { b: 'dot' },
views: { dot: DotView },
toolbar: [{ tool: 'dot', label: 'Vote', icon: DotIcon, shortcut: 'B' }]
}; const plugins = [...defaultPlugins, dotPlugin];
const editor = new Editor({ plugins }); More a kind can say
A ShapeUtil has more hooks, each with a default that does nothing: whether a shape
holds text (canEdit), which styles it shows, handles of its own (a line's ends),
where an arrow attached to it stops (edgePoint), whether it is made from pasted
text or a dropped file (fromText, fromFile), switches in the
right-click menu (toggles). The API reference lists them all.