Mob.Event.Touch (mob v0.9.30)

Copy Markdown View Source

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))
  ...
end

A 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

config()

@type config() :: %{moves: boolean(), throttle_ms: non_neg_integer(), delta: number()}

payload()

@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. Outside 0..width / 0..height once 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 (Android uptimeMillis, iOS UITouch.timestamp). Only differences mean anything.

phase()

@type phase() :: :down | :move | :up | :cancel

Functions

message(tag, phase, fields \\ [])

@spec message(term(), phase(), keyword()) :: {:touch, term(), payload()}

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_opts(opts)

@spec parse_opts(keyword()) :: config()

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.