Skip to main content

Canvas Mode

SimpleKit's canvas mode exposes a lightweight event loop for drawing directly on a single HTML canvas. This mode is intended for quick experiments or projects that need only basic event handling without the full widget system.

Starting the toolkit​

  1. Ensure the HTML file running SimpleKit contains only a single script tag in the <body> and no extra stylesheets. startSimpleKit checks these conditions and creates the canvas element for you.
  2. Import the module:
import {
  startSimpleKit,
  setSKDrawCallback,
  setSKEventListener,
  setSKAnimationCallback,
  addSKEventTranslator,
  skTime,
} from "simplekit/src/canvas-mode";
  1. Call startSimpleKit() once during startup. The function returns the canvas size or false if the HTML page does not meet the requirements.
const canvasInfo = startSimpleKit();
if (!canvasInfo) throw new Error("SimpleKit failed to start");

Drawing and animation​

Use setSKDrawCallback to supply a function that draws to the canvas each frame. The callback receives the CanvasRenderingContext2D used by the toolkit. For animations, register a function with setSKAnimationCallback. The animation callback receives the current timestamp (available globally as skTime).

setSKDrawCallback((gc) => {
  gc.clearRect(0, 0, gc.canvas.width, gc.canvas.height);
  gc.fillStyle = "tomato";
  gc.fillRect(50, 50, 100, 100);
});

setSKAnimationCallback((time) => {
  // update positions or physics here
});

Receiving events​

The canvas mode translates low‑level browser events into SKEvent objects. Register a listener with setSKEventListener to receive all translated events:

setSKEventListener((e) => {
  if (e.type === "click") console.log("canvas clicked at", e.x, e.y);
});

Event translators​

SimpleKit includes translators for fundamental events (mousedown, mouseup, mousemove, keydown, keyup, and resize) as well as higher level ones:

  • click – generated by clickTranslator
  • dblclick – generated by dblclickTranslator
  • dragstart, drag, dragend – generated by dragTranslator

You may provide your own translators using addSKEventTranslator(translator) where a translator is an object with an update(fundamentalEvent) method returning an SKEvent.

Typical flow​

  1. Call startSimpleKit.
  2. Register optional translators with addSKEventTranslator.
  3. Provide drawing, animation and event callbacks.
  4. SimpleKit runs an internal loop that translates events, dispatches them to your listener, then calls your animation and draw callbacks every frame.

Canvas mode does not handle any widgets or layout; you are free to draw whatever you like to the canvas using the provided graphics context.

Customising the Canvas​

startSimpleKit automatically inserts a canvas element that fills the browser window. The helper in common.ts sets a default background colour of whitesmoke. If you want to style the canvas further simply access the element returned by startSimpleKit and adjust its CSS properties:

const info = startSimpleKit();
if (info) {
  const canvas = document.querySelector('canvas')!;
  canvas.style.border = '1px solid black';
}

The canvas resizes with the window so your drawing code should rely on gc.canvas.width and gc.canvas.height each frame.

Graphics Context Methods​

Below is a summary of the key methods available on the CanvasRenderingContext2D used in canvas mode. For the full API, refer to the MDN documentation.

Saving and State​

  • save() and restore() push and pop the current drawing state.
  • lineWidth, lineCap, lineJoin, miterLimit control stroke appearance.
  • strokeStyle, fillStyle set colours or gradients.
  • setLineDash(segments) / getLineDash() for dashed lines.
  • globalAlpha, globalCompositeOperation manage compositing.

Transformations​

  • translate(x, y)
  • rotate(angle)
  • scale(x, y)
  • transform(m11, m12, m21, m22, dx, dy)
  • setTransform(...) and resetTransform()

Path Construction​

  • beginPath() starts a new path.
  • moveTo(x, y) sets the start of a sub-path.
  • lineTo(x, y) draws a line.
  • rect(x, y, w, h) or roundRect(x, y, w, h, radii) for rectangles.
  • arc(x, y, r, start, end, anticlockwise?)
  • arcTo(x1, y1, x2, y2, r)
  • bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)
  • quadraticCurveTo(cpx, cpy, x, y)
  • ellipse(x, y, rx, ry, rot, start, end, anticlockwise?)
  • closePath() closes the current sub-path.
  • fill() / stroke() render the path.
  • clip() sets the clipping region.
  • fillRect(x, y, w, h) and strokeRect(x, y, w, h) draw rectangles directly.
  • clearRect(x, y, w, h) clears a region.

Text Drawing​

  • font – CSS font string used for text rendering.
  • textAlign – alignment relative to the provided x position.
  • textBaseline – vertical alignment within the line box.
  • direction – text direction for languages like RTL scripts.
  • fillText(text, x, y, maxWidth?)
  • strokeText(text, x, y, maxWidth?)
  • measureText(text)

Images and Gradients​

  • drawImage(image, ...args) draws an HTML image, canvas or video.
  • createPattern(image, repetition) creates a repeating fill style.
  • createLinearGradient(x0, y0, x1, y1)
  • createRadialGradient(x0, y0, r0, x1, y1, r1)
  • createImageData(w, h), getImageData(x, y, w, h), putImageData(data, x, y) for pixel level access.