smudgy:widgets — Canvas

Generated from smudgy v0.4.2-dev (smudgy-widgets.d.ts @ e96061b683ea). Index: scriptref.

Draw a scene from shape records, update it through a state binding, and handle pointer input in scene coordinates. Smudgy runs declared animations without requiring a script callback for every frame.

For a guided scene and animation example, see Draw and animate a canvas.

export function Canvas(props?: CanvasProps, children?: WidgetChildren): SmudgyElement;

Draws shape records and runs their declared animations.

export interface CanvasProps {
    width?: Bindable<WidgetLength>;
    height?: Bindable<WidgetLength>;
    view_box?: [number, number, number, number];
    fit?: "fill" | "contain";
    scene?: Bindable<CanvasShape[]>;
    onPointer?: (event: CanvasPointerEvent) => void;
    children?: WidgetChildren;
}

Props for a script-drawn canvas (a leaf; children are ignored).

A scene is an array of shape records. When scene is a binding, each write to the bound path repaints the drawing, including changes to the number or order of shapes. Smudgy evaluates declared animations between writes; scripts do not need to submit an update for each frame.

Smudgy validates the whole scene before displaying it. If the scene exceeds a complexity limit or contains duplicate animation IDs, Smudgy reports an error and continues displaying the previous valid scene.

Drawing is clipped to the canvas bounds, including animated shapes. A canvas without onPointer does not capture pointer input from content behind it. With a view_box, a "fill"-sized canvas rescales the scene when its pane changes size. Fixed numeric dimensions keep a fixed widget size. Without a view_box, scene units are pixels.

• width — Default “fill”.
• height — Default “fill”.
• view_box — The scene rectangle [x, y, width, height] mapped onto the widget's bounds. Scene coordinates (and pointer events) then stay resolution-independent. Omitted, scene units are pixels. See CanvasProps.fit for how the mapping treats a mismatched aspect ratio.
• fit — How the view_box meets the widget bounds when their aspect ratios differ. "fill" (default) stretches the scene to cover the bounds exactly; "contain" scales uniformly to the limiting axis and centers, keeping the scene's aspect ratio with empty margins (a pointer event in a margin reports coordinates outside the view_box). Without a view_box, fit is ignored.
• scene — The shapes to draw, in paint order.
• onPointer — Pointer input, in scene coordinates. Omitted, the canvas is display-only.

export interface CanvasPointerEvent {
    kind: "down" | "move" | "up";
    x: number;
    y: number;
    button: "left" | "middle" | "right";
}

A pointer event on a canvas, in scene coordinates (the same numbers you draw with). down and up always arrive in pairs; move only arrives while a button is held, at most once per frame, and the release is delivered even when it happens outside the canvas.

export type CanvasShape =
| CanvasRect
| CanvasCircle
| CanvasEllipse
| CanvasLine
| CanvasPolyline
| CanvasPolygon
| CanvasPath
| CanvasText
| CanvasGroup;

One record in a canvas scene. Shapes draw in scene order, back to front (except text; see CanvasText).

Support type used by signatures on this page.

interface CanvasShapeBase {
    id?: string;
    opacity?: number;
    transient?: boolean;
}

Fields shared by every canvas shape.

Give an animated shape an id that is unique within its scene. When a bound scene changes or the widget is re-mounted, an animation keeps its progress if both its id and animation specification are unchanged. Changing the specification restarts the animation. Without an id, Smudgy identifies the animation by the shape's position in the scene, so reordering shapes may restart it.

• id — Stable identity for this shape's animations across scene rewrites. Must be unique among animated shapes within one scene.
• opacity — Overall opacity, 0..=1. Default 1.
• transient — When used with animate, removes the shape after every tween finishes. Later writes that still contain the same shape do not display it again. Remove the shape from subsequent scene values after a one-shot effect completes.

export interface CanvasRect extends CanvasShapeBase {
    kind: "rect";
    x?: number;
    y?: number;
    width?: number;
    height?: number;
    rx?: number;
    fill?: CanvasFill;
    stroke?: CanvasStroke;
    animate?: Partial<
        Record<"x" | "y" | "width" | "height" | "rx" | "opacity" | "stroke_width", NumberTween>
    > & { fill?: ColorTween; stroke?: ColorTween };
}

A rectangle, optionally rounded.

• rx — Corner radius.

export interface CanvasCircle extends CanvasShapeBase {
    kind: "circle";
    cx?: number;
    cy?: number;
    r?: number;
    fill?: CanvasFill;
    stroke?: CanvasStroke;
    animate?: Partial<
        Record<"cx" | "cy" | "r" | "opacity" | "stroke_width", NumberTween>
    > & { fill?: ColorTween; stroke?: ColorTween };
}

A circle.

export interface CanvasEllipse extends CanvasShapeBase {
    kind: "ellipse";
    cx?: number;
    cy?: number;
    rx?: number;
    ry?: number;
    fill?: CanvasFill;
    stroke?: CanvasStroke;
    animate?: Partial<
        Record<"cx" | "cy" | "rx" | "ry" | "opacity" | "stroke_width", NumberTween>
    > & { fill?: ColorTween; stroke?: ColorTween };
}

An axis-aligned ellipse.

export interface CanvasLine extends CanvasShapeBase {
    kind: "line";
    x1?: number;
    y1?: number;
    x2?: number;
    y2?: number;
    stroke?: CanvasStroke;
    animate?: Partial<
        Record<"x1" | "y1" | "x2" | "y2" | "opacity" | "stroke_width", NumberTween>
    > & { stroke?: ColorTween };
}

A line segment.

export interface CanvasPolyline extends CanvasShapeBase {
    kind: "polyline";
    points: [number, number][];
    stroke?: CanvasStroke;
    animate?: Partial<Record<"opacity" | "stroke_width", NumberTween>> & {
        stroke?: ColorTween;
    };
}

An open run of connected line segments.

• points — The vertices, as [x, y] pairs.

export interface CanvasPolygon extends CanvasShapeBase {
    kind: "polygon";
    points: [number, number][];
    fill?: CanvasFill;
    stroke?: CanvasStroke;
    animate?: Partial<Record<"opacity" | "stroke_width", NumberTween>> & {
        fill?: ColorTween;
        stroke?: ColorTween;
    };
}

A closed polygon.

• points — The vertices, as [x, y] pairs. The shape closes itself.

export interface CanvasPath extends CanvasShapeBase {
    kind: "path";
    d: string;
    fill?: CanvasFill;
    stroke?: CanvasStroke;
    animate?: Partial<Record<"opacity" | "stroke_width", NumberTween>> & {
        fill?: ColorTween;
        stroke?: ColorTween;
    };
}

An arbitrary path in SVG path-data syntax.

• d — SVG path data (M/L/H/V/C/S/Q/T/A/Z, absolute and relative).

export interface CanvasText extends CanvasShapeBase {
    kind: "text";
    x?: number;
    y?: number;
    text: string;
    size?: number;
    color?: string;
    align_x?: HorizontalAlign;
    align_y?: VerticalAlign;
    font?: "default" | "monospace";
    animate?: Partial<Record<"x" | "y" | "size" | "opacity", NumberTween>> & {
        color?: ColorTween;
    };
}

Text drawn in the canvas.

Canvas text is drawn after non-text shapes, regardless of scene order. A later rectangle therefore cannot cover earlier text.

• text — The text content.
• size — Text size in scene units. Default 16.
• color — A CSS color string. Default white.
• align_x — Which part of the text sits at x. Default “left”.
• align_y — Which part of the text sits at y. Default “top”.
• font — Font family. Default the UI font.

export interface CanvasGroup extends CanvasShapeBase {
    kind: "group";
    transform?: {
        translate?: [number, number];
        rotate?: number;
        scale?: number | [number, number];
    };
    children: CanvasShape[];
    animate?: Partial<
        Record<"translate_x" | "translate_y" | "rotate" | "scale", NumberTween>
    >;
}

A transformed group of shapes. Transform components always apply in the order translate, then rotate, then scale, about the group's local origin.

export type CanvasFill =
| string
| {
      gradient: {
          from: [number, number];
          to: [number, number];
          stops: [number, string][];
      };
  };

A paint for canvas shapes: a CSS color string, or a linear gradient between two scene-space points. Gradient endpoints follow the canvas view_box mapping and any group transforms, like the geometry they fill. At most 8 stops.

export interface CanvasStroke {
    color?: CanvasFill;
    width?: number;
    dash?: number[];
}

A stroke for canvas shapes.

• color — Stroke paint. Default black.
• width — Stroke width in scene units. Default 1.
• dash — Dash pattern (on/off lengths). Solid when omitted.

export type CanvasEase = "linear" | "in" | "out" | "in-out";

An animation easing curve.

export interface NumberTween {
    to: number;
    from?: number;
    duration: number;
    delay?: number;
    ease?: CanvasEase;
    repeat?: number | "infinite";
}

A tween for one numeric field of a canvas shape.

• to — The value animated to.
• from — The starting value. Defaults to the shape's own value for the field.
• duration — Duration of one run, in milliseconds.
• delay — Delay before the first run, in milliseconds (applied once, not per repeat).
• ease — Easing curve. Default “linear”.
• repeat — Run the tween this many times, or forever. Each repeat restarts from the beginning. Default 1.

export interface ColorTween {
    to: string;
    from?: string;
    duration: number;
    delay?: number;
    ease?: CanvasEase;
    repeat?: number | "infinite";
}

A tween for one color field of a canvas shape. Endpoints are CSS color strings.

• from — Defaults to the shape's own color for the field.

Script API reference · ← smudgy:widgets — Text & data display · Mapper → · Scripting manual