The on_touch contract: per-node, per-pointer touch streams (MOB-518).
box(on_touch: {self(), :pad}) # down, up, cancel
box(on_touch: {self(), :pad, moves: true}) # plus moves, 16 ms / 1 dp
box(on_touch: {self(), :pad, moves: true, throttle: 0, delta: 0})Every event arrives as {:touch, tag, payload}:
def handle_info({:touch, :pad, %{phase: :down, y: y, height: h}}, socket) do
velocity = round(127 * (1 - 0.85 * y / h))
...
endA pointer belongs to the node it went down on until it lifts: a finger that
slides onto another on_touch node sends that node nothing. Every :down
is followed by exactly one :up or :cancel with the same pointer_id,
however many renders happen in between. Moves are off unless moves: true,
and then sent per pointer when at least throttle ms have passed and the
pointer has moved at least delta dp (summed x and y distance) since its
last sent event. on_touch observes without consuming, so on_tap,
on_long_press, on_press_in / on_press_out and scrolling on the same
node keep working.
See guides/events.md ("Touch") and
decisions/2026-11-12-per-node-multi-pointer-on-touch.md.
Summary
Functions
The message a touch delivers, for driving a screen without a finger
(Mob.Test.touch/4, Mob.ScreenCase.render_touch/4). fields overrides
any of pointer_id (default 0), x, y, width, height (default 0.0)
and ts (default: this node's monotonic clock, in ms). Numbers are
converted to the types native sends.
Parse the options of on_touch: {pid, tag, opts}.
Types
@type config() :: %{moves: boolean(), throttle_ms: non_neg_integer(), delta: number()}
@type payload() :: %{ phase: phase(), pointer_id: integer(), x: float(), y: float(), width: float(), height: float(), ts: integer() }
pointer_id— the same from a pointer's down to its up or cancel, and different from every other pointer down at the same time. Not necessarily small or zero-based.x,y— dp from the node's top-left corner. Outside0..width/0..heightonce a pointer has left the node it went down on.width,height— the node's size in dp when the event happened.ts— milliseconds from the platform's monotonic input clock (AndroiduptimeMillis, iOSUITouch.timestamp). Only differences mean anything.
@type phase() :: :down | :move | :up | :cancel
Functions
The message a touch delivers, for driving a screen without a finger
(Mob.Test.touch/4, Mob.ScreenCase.render_touch/4). fields overrides
any of pointer_id (default 0), x, y, width, height (default 0.0)
and ts (default: this node's monotonic clock, in ms). Numbers are
converted to the types native sends.
iex> Mob.Event.Touch.message(:pad, :down, y: 30, height: 120, ts: 5)
{:touch, :pad, %{phase: :down, pointer_id: 0, x: 0.0, y: 30.0, width: 0.0, height: 120.0, ts: 5}}
Parse the options of on_touch: {pid, tag, opts}.
iex> Mob.Event.Touch.parse_opts([])
%{moves: false, throttle_ms: 16, delta: 1.0}
iex> Mob.Event.Touch.parse_opts(moves: true, throttle: 0, delta: 0)
%{moves: true, throttle_ms: 0, delta: 0}throttle: and delta: tune moves, so either one without moves: true
raises rather than doing nothing. Unknown options raise too.