Guide / Controls / Inputs

Free canvas

Place things anywhere on a surface

When to use it. A freeform container: real, live controls hosted at normalized (x, y, w, h) on a pannable, zoomable surface. Where Palette places markers, canvas places whole working controls — each card renders through the real renderer, so its bindings, actions, sync and theming all work exactly as they would in a grid cell.

Type
canvas
Also titled
Canvas
Default size
10 rows × 4 columns
Symbol
square.on.square.dashed
Docs
Docs complete
Search for it as
  • draw
  • drawing
  • sketch
  • paint
  • shapes
  • freeform
Free canvas: Freeform status board
Rendered by the app

Fields

10 fields you can set on a canvas control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

The buzz you feel on a lift

Plays this haptic on the phone when you long-press and lift a card.

  • noneno vibration
  • lighta small soft tap
  • mediuma medium tap
  • heavya strong thud
  • softa muted cushioned bump
  • rigida firm sharp click
  • selectionthe faint tick of picking an item
  • successthe double tap of a success
  • warninga two-pulse warning
  • errora sharp triple buzz of an error
Labellabeltext—

The name shown with the canvas

Shows this text as the canvas header label.

HeightcontrolHeightnumber100–1200step 10560

How tall the canvas is

Sets the rendered height of the surface in points.

ShapecanvasConfig.aspectnumber0.2–5step 0.11.0

How wide versus tall the surface is

Reshapes the surface to this width-to-height ratio, fitted inside the available space.

EditablecanvasConfig.editableon / offfalse (off)

Touch and hold a card to move it

Lets you long-press a card to lift and drag it, firing place and layout actions on drop.

GridcanvasConfig.showGridon / offfalse (off)

Dots to line things up

Draws a faint dot lattice on the surface, spaced by the snap step when set.

SnapcanvasConfig.snapnumber0–1step 0.050

Snap cards to a grid

Rounds a dropped card to this fraction of the surface; 0 leaves it where you let go.

Max zoomcanvasConfig.maxZoomnumber0.5–4step 0.13

How far you can pinch in

Caps how far a pinch can zoom the surface; 1 turns zoom and panning off.

itemscanvasConfig.itemslist—

The cards on the board

Places each listed control on the surface at its own position and size, later ones on top.

eventscanvasConfig.eventsobject—

What happens when you move a card

Runs the pickup, place and layout actions as a card is lifted and dropped.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you drop a cardplacedropjson

the card you dropped and its new position and size

Only when Editable is on; a layout event with every card's frame follows, and lifting a card sends a pickup first

Example: {"item": "Item 1", "x": 0.25, "y": 0.5, "w": 0.25, "h": 0.25}

Receives

Receives
TakesFromTypeWhat it does
arrangementfollowhub, mqtt, http, storejson

a frame (position and size, as fractions from 0 to 1) for each card id

the cards move to their new frames; ids that are not on the canvas are ignored and cards left out stay where they were configured

Example: {"frames": {"Item 1": {"x": 0.25, "y": 0.5, "w": 0.25, "h": 0.25}}}

Sample

The placeholder value the editor shows before real data arrives.

  • {"frames": {"Item 1": {"x": 0.1, "y": 0.1, "w": 0.4, "h": 0.3}, "Item 2": {"x": 0.5, "y": 0.5, "w": 0.4, "h": 0.3}}} then {"frames": {"Item 1": {"x": 0.5, "y": 0.1, "w": 0.4, "h": 0.3}, "Item 2": {"x": 0.1, "y": 0.5, "w": 0.4, "h": 0.3}}}

Examples

3 examples, each one a control you can paste into a layout.

Freeform status board

JSON 23 lines
{
  "type": "canvas",
  "id": "status-board",
  "position": [0, 0],
  "span": [10, 4],
  "controlHeight": 560,
  "label": "Ops Board",
  "canvasConfig": {
    "aspect": 1.2,
    "items": [
      { "id": "cpu", "x": 0.05, "y": 0.05, "w": 0.42, "h": 0.3,
        "control": { "type": "gauge", "id": "cpu-gauge", "label": "CPU", "min": 0, "max": 100,
                     "sync": [{ "method": "meshsocket", "event": "broadcast", "filter": { "msg_type": "telemetry" }, "valuePath": "cpu" }] } },
      { "id": "temp", "x": 0.53, "y": 0.05, "w": 0.42, "h": 0.3,
        "control": { "type": "sparkline", "id": "temp-spark", "label": "Temp",
                     "sync": [{ "method": "meshsocket", "event": "broadcast", "filter": { "msg_type": "telemetry" }, "valuePath": "temp" }] } },
      { "id": "power", "x": 0.05, "y": 0.42, "w": 0.42, "h": 0.18,
        "control": { "type": "toggle", "id": "rig-power", "label": "Rig Power",
                     "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                                 "payload": { "target_name": "hub", "type": "power", "payload": { "on": "{{value}}" } } } } }
    ]
  }
}

Open in CAR-TER

Free canvas: Freeform status board
Rendered by the app

Editable, server-seeded board

JSON 25 lines
{
  "type": "canvas",
  "id": "war-room",
  "position": [0, 0],
  "span": [12, 4],
  "label": "War Room",
  "canvasConfig": {
    "editable": true,
    "showGrid": true,
    "snap": 0.05,
    "items": [
      { "id": "feed", "x": 0.05, "y": 0.05, "w": 0.9, "h": 0.35,
        "control": { "type": "logConsole", "id": "feed-log", "label": "Feed", "maxLines": 40 } },
      { "id": "arm", "x": 0.05, "y": 0.5, "w": 0.42, "h": 0.2, "locked": true,
        "control": { "type": "button", "id": "arm-btn", "label": "Arm",
                     "action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "arm" } } } }
    ],
    "events": {
      "place": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                 "payload": { "target_name": "hub", "type": "board_place",
                              "payload": { "card": "{{item}}", "x": "{{x}}", "y": "{{y}}" } } },
      "layout": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "board_state" } }
    }
  }
}

Open in CAR-TER

Free canvas: Editable, server-seeded board
Rendered by the app

Static zoomable board

A fixed single-card surface you can pinch to zoom but not rearrange.

JSON 17 lines
{
  "type": "canvas",
  "id": "static-board",
  "position": [0, 0],
  "span": [10, 4],
  "controlHeight": 400,
  "label": "Overview",
  "haptic": "light",
  "canvasConfig": {
    "aspect": 1.5,
    "maxZoom": 2,
    "items": [
      { "id": "note", "x": 0.1, "y": 0.1, "w": 0.5, "h": 0.3,
        "control": { "type": "label", "id": "note-label", "label": "Hello" } }
    ]
  }
}

Open in CAR-TER

Try it: the bundled canvas-demo layout has both — a live status board and an editable, snapping war-room board.

Try it

These examples need more room than carterkit demo gives one control, so paste one into a layout instead. carterkit prints this page's fields in your terminal.

  1. Install the Python kit.

    pip install carterkit
  2. Read the fields offline.

    carterkit doc canvas

carterkit quickstart

Pinch to zoom (up to maxZoom), drag empty surface to pan while zoomed. With editable: true, long-press lifts a card (so hosted controls keep their own taps/drags), dragging moves it, and dropping emits place + layout and round-trips the synced value — a server or a peer can seed or rearrange the board.

The structural (Pattern-7) drag control; the on-device Layout Editor speaks the same lift/snap language but authors real grid layouts.

Sizing

In a mode: "flow" grid set controlHeight (e.g. 560); in a 2-D grid give it a real span (rough guide: [10, 4]). aspect shapes the surface itself. See Grid Dimensions.

Config (canvasConfig)

Field Type Description
items array The hosted controls (below). Order is z-order: later items draw on top.
aspect number Surface width ÷ height (default 1.0).
editable bool Allow rearranging cards (default false — a static freeform dashboard).
showGrid bool Faint dot lattice (spatial affordance for editable boards).
snap number Normalized drop-snap increment; 0/absent = free placement.
maxZoom number Max pinch-zoom scale (default 3; 1 disables zoom/pan).
events object pickup / place / layout fired on drag (see DragEventActions).

Item { id, x, y, w, h, locked?, control }

Field Type Description
id string Stable card id — the key in the synced frames and in events.
x, y number Top-leading corner, 0…1 fractions of the surface.
w, h number Size, 0…1 fractions of the surface (default 0.25 each).
locked bool Card can't be moved in editable mode (still live/interactive).
control object Any control object. position may be omitted (it's meaningless on a canvas).

Events

Lifting a card fires pickup { item, from: "canvas" }. Dropping (or a VoiceOver nudge) fires place { item, x, y, w, h } and layout { frames: { id: {x,y,w,h} }, changed }. Token substitution ({{item}}, {{x}}, …) works as in every drag control.

Accessibility

Cards keep their child elements (the hosted control stays fully usable) and expose Move left/right/up/down actions that step by the snap increment (5% when unset) — the whole surface works without drag.

Synced value

{ "frames": { "<id>": { "x": 0.1, "y": 0.2, "w": 0.4, "h": 0.25 } } }. Sync a value in this shape to seed or rearrange cards; ids not in items are ignored, and frames the push omits fall back to the item's configured spot.

Generated from ControlDocs/canvas.md. Something unclear or missing? Tell me.