Guide / Controls / Inputs

Pin board

Pin things onto a picture

When to use it. An option area plus a freeform surface you drag items onto at any (x, y) — a floor-plan device placer, a map pin board, a seating chart on a photo. Drag a palette item onto the surface to place it, drag a marker to reposition, drag it back to the palette to remove, and tap a placed marker to fire its action.

Type
pinboard
Also titled
Pinboard
Default size
10 rows × 4 columns
Symbol
mappin.and.ellipse
Docs
Docs complete
Search for it as
  • board
  • notes
  • sticky
  • pins
  • corkboard
  • cards
Pin board: Floor-plan device placement
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

The buzz you feel when you drag

Plays this haptic on the phone when you interact with the board.

  • noneno buzz
  • lighta small soft tap
  • mediuma medium tap
  • heavya strong thud
  • softa gentle muffled tap
  • 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 title above the board

Shows this text as the header of the pin board.

HeightcontrolHeightnumber100–1200step 10560

How tall the board is

Sets the board height in points in a flow grid; in a 2-D grid the span sets it instead.

backgroundpinboardConfig.backgroundtext—

A faint picture behind the surface

Draws this SF Symbol faintly behind the surface, e.g. house.fill for a floor plan or map for a map.

ShapepinboardConfig.surfaceAspectnumber0.2–5step 0.11.4

How wide the surface is

Sets the surface shape as width divided by height, 0.2 to 5; 1.4 is wider than tall.

SearchpinboardConfig.searchableon / offfalse (off)

A search box over the pile

Adds a filter field above the option area so you can find an item by its label.

Palette titlepinboardConfig.paletteLabeltextItems

The name of the item pile

Sets the header over the option area, e.g. Unplaced devices instead of Items.

PalettepinboardConfig.hidePaletteon / offfalse (off)

Hide the item pile

Removes the option area so only the surface shows, for boards whose markers all start placed.

eventspinboardConfig.eventsobject—

What happens when you drag

Holds the pickup, place and layout actions that fire as you lift, drop and settle a marker.

itemspinboardConfig.itemsobject—

The things you can pin

Lists the items, each with an id, label, icon, tint, optional starting x and y, a tap action and a locked flag.

pinboardConfigpinboardConfigobject—

The board settings in one bundle

Groups the backdrop, shape, search, palette, events and items settings; any entry left out uses its default.

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 lift a pinpickupliftid

the lifted pin's id

Example: item-1

When you drop a pinplacedropid

the dropped pin's id

Sends when you place a new pin or move a placed one; dragging a pin back to the options area removes it and sends only the layout

Example: item-1

When the board settleslayoutsettlejson

every placed pin's position, plus the move that just happened

Keys you add to this action's payload are sent along with the arrangement; a removal sends no changed part

Example: {"points": {"item-1": {"x": 0.5, "y": 0.5}}, "changed": {"item": "item-1", "x": 0.5, "y": 0.5}}

When you tap a placed pinpintapid

the tapped pin's id

Each pin carries its own action; a pin with none sends nothing

Example: item-1

Receives

Receives
TakesFromTypeWhat it does
arrangementfollowhub, mqtt, http, storejson

where each pin sits on the surface, as a fraction across and down

pins move to the positions it names; ids the board does not know are ignored

Example: {"points": {"item-1": {"x": 0.5, "y": 0.5}}}

Sample

The placeholder value the editor shows before real data arrives.

  • {"items": [{"id": "item-1", "label": "Item 1", "x": 0.3, "y": 0.4}, {"id": "item-2", "label": "Item 2"}, {"id": "item-3", "label": "Item 3"}]}

Examples

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

Floor-plan device placement

Demonstrates a house backdrop, one device pre-placed with a tap action, and place and layout events.

JSON 27 lines
{
  "type": "pinboard",
  "id": "home-plan",
  "position": [0, 0],
  "span": [10, 4],
  "controlHeight": 560,
  "label": "Home Devices",
  "pinboardConfig": {
    "background": "house.fill",
    "surfaceAspect": 1.6,
    "paletteLabel": "Unplaced devices",
    "items": [
      { "id": "living-lamp", "label": "Living Lamp", "icon": "lamp.table.fill", "tint": "#FF9500", "x": 0.28, "y": 0.4,
        "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                    "payload": { "target_name": "hub", "type": "toggle", "payload": { "device": "{{value}}" } } } },
      { "id": "front-door", "label": "Front Door", "icon": "door.left.hand.closed", "tint": "#34C759",
        "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                    "payload": { "target_name": "hub", "type": "toggle", "payload": { "device": "{{value}}" } } } }
    ],
    "events": {
      "place": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                 "payload": { "target_name": "hub", "type": "place_device",
                              "payload": { "device": "{{item}}", "x": "{{x}}", "y": "{{y}}" } } },
      "layout": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "floorplan_state" } }
    }
  }
}

Open in CAR-TER

Pin board: Floor-plan device placement
Rendered by the app

Demonstrates searchable and surfaceAspect: a wide map backdrop with a filter over the pile of pins.

JSON 19 lines
{
  "type": "pinboard",
  "id": "site-map",
  "position": [0, 0],
  "span": [10, 4],
  "controlHeight": 480,
  "label": "Site Map",
  "pinboardConfig": {
    "background": "map",
    "surfaceAspect": 2,
    "searchable": true,
    "paletteLabel": "Cameras",
    "items": [
      { "id": "cam-gate", "label": "Gate", "icon": "video.fill", "tint": "#FF3B30" },
      { "id": "cam-yard", "label": "Yard", "icon": "video.fill", "tint": "#5AC8FA" },
      { "id": "cam-shed", "label": "Shed", "icon": "video.fill", "tint": "#FF9500" }
    ]
  }
}

Open in CAR-TER

Server-seeded markers

Demonstrates hidePalette with items already placed by x and y, one locked so it cannot be dragged.

JSON 16 lines
{
  "type": "pinboard",
  "id": "seat-map",
  "position": [0, 0],
  "span": [8, 4],
  "controlHeight": 420,
  "label": "Seat Map",
  "pinboardConfig": {
    "hidePalette": true,
    "surfaceAspect": 1.6,
    "items": [
      { "id": "seat-a", "label": "A", "icon": "chair.fill", "tint": "#667eea", "x": 0.25, "y": 0.5 },
      { "id": "seat-b", "label": "B", "icon": "chair.fill", "tint": "#34C759", "x": 0.7, "y": 0.5, "locked": true }
    ]
  }
}

Open in CAR-TER

Try it: the bundled pinboard-demo layout has this floor plan (three devices pre-placed, two in the tray).

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 pinboard

carterkit quickstart

The second spatial (Pattern-3) drag control: placements ride normalized x/y (CARSpatialPlacementState) and round-trip through the synced value, so a server can seed or push a layout.

Sizing

In a mode: "flow" grid set controlHeight (e.g. 560); in a 2-D grid give it a real span. surfaceAspect controls the surface's shape. See Grid Dimensions.

Config (pinboardConfig)

Field Type Description
items array The catalog (below). An item with both x and y starts placed; otherwise it's in the option area.
background string SF Symbol drawn faint behind the surface (e.g. "house.fill", "map"). Omitted ⇒ a plain surface.
surfaceAspect number Surface width ÷ height (default 1.4).
searchable bool Filter field over the option area.
paletteLabel string Option-area header (default "Items").
hidePalette bool Hide the option area.
events object pickup / place / layout fired on drag.

Item { id, label?, icon?, tint?, x?, y?, action?, locked? }

Field Type Description
x, y number Initial normalized position 0…1. Both present ⇒ starts placed.
action object Fired when the placed marker is tapped. {{value}} = the id.
locked bool Can't be dragged (still tappable).

Events

Placing/moving a marker fires place { item, x, y } and layout { points: { id: {x,y} }, changed } (see DragEventActions). Tapping a placed marker fires that item's action. Removing a marker (drag back to the palette) fires layout.

Accessibility

Under VoiceOver tray chips expose a "Place at center" action and markers read their position ("28% across, 40% down"), fire on double-tap, and expose "Return to <tray>" — the full surface works without drag.

Synced value

{ "points": { "<id>": { "x": 0.28, "y": 0.4 } } }. Sync a value in this shape to let a server seed or rearrange placements; ids not in the catalog are ignored.

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