# `Drafter.Terminal.PixelMouse`
[🔗](https://github.com/jaman/drafter/blob/main/lib/drafter/terminal/pixel_mouse.ex#L1)

What a driver writes to turn pixel mouse reporting (SGR-Pixels, DECSET 1016) on and
off, and when.

A driver keeps one of three states per terminal:

  * `:off` — mouse reports are in cells.
  * `:waiting` — pixel reports are wanted, but the terminal has not yet said how big a
    cell is, so pixels could not be turned into cells. The driver has asked.
  * `:on` — mode 1016 has been set and the terminal asked whether it took.

Each function returns the new state and the bytes to write. Reports are read as
pixels only after the terminal answers `Drafter.Terminal.Reports.pixel_mouse_query/0`
with `{:pixel_mouse, true}`; a terminal that ignores mode 1016 answers `false`, its
reports stay in cells, and their payloads carry no `:px`. Every terminal that knows
mode 1016 answers the query; a terminal that answers neither yes nor no keeps cell
reading.

    iex> Drafter.Terminal.PixelMouse.enable(:off, nil)
    {:waiting, "\e[16t"}

    iex> Drafter.Terminal.PixelMouse.after_input(:waiting, {8, 16})
    {:on, "\e[?1016h\e[?1016$p"}

# `cell_size`

```elixir
@type cell_size() :: {pos_integer(), pos_integer()} | nil
```

The terminal's cell size in pixels, or `nil` when it has not reported one.

# `t`

```elixir
@type t() :: :off | :waiting | :on
```

# `after_input`

```elixir
@spec after_input(t(), cell_size()) :: {t(), iodata()}
```

Call after decoding input, with the cell size now known: a `:waiting` driver sets
mode 1016 and asks whether it took once the cell size has arrived.

# `cleanup`

```elixir
@spec cleanup(t()) :: iodata()
```

What to write when the terminal is restored: mode 1016 off when it was set.

# `disable`

```elixir
@spec disable(t()) :: {t(), iodata()}
```

Return to cell reports. The terminal's answer to the query that follows turns pixel
reading off in the parser.

# `enable`

```elixir
@spec enable(t(), cell_size()) :: {t(), iodata()}
```

Ask for pixel reports. Sets mode 1016 at once when the cell size is known, and asks
for the cell size otherwise.

# `resized`

```elixir
@spec resized(t()) :: iodata()
```

What to write when the terminal is resized: the cell size query while pixel reports
are on, since a change of font size changes both the grid and the cell.

# `start`

```elixir
@spec start(boolean()) :: t()
```

The state a driver starts in for its `pixel_mouse` setup option. A driver starting
in `:waiting` must ask for the cell size among its startup queries.

    iex> Drafter.Terminal.PixelMouse.start(true)
    :waiting

---

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