# `Mob.Event.Touch`
[🔗](https://github.com/genericjam/mob/blob/master/lib/mob/event/touch.ex#L1)

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`.

# `config`

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

# `payload`

```elixir
@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`

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

# `message`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
