# Using the mouse or a pointing device

[Programming guides](README.md)

A **pointer** is the position controlled by a mouse, touch, or pen in a host that supports it. Pliro follows one **primary pointer** for a gesture: one press and its matching release. For a mouse, primary normally means its main button. Write the exact text `"primary"` in the header.

A **handler** is the block under `when` that reacts to an event. An **event descriptor** names the event in that header. You can register just the handler you need; you do not need all three.

## Press, release, and click

| Event | When it happens | Which position you get |
|---|---|---|
| `pointerPressed("primary")` | An accepted press starts inside the drawing area. | The position where it was pressed. |
| `pointerReleased("primary")` | The same pointer is really released, even outside the drawing area. | The position where it was released. |
| `pointerClicked("primary")` | An accepted press and its release both happen inside. It follows the release event. | The release position, not the original press position. |

`pointerX()` gives the horizontal coordinate and `pointerY()` the vertical coordinate. The **origin**, `(0, 0)`, is at the top-left. These calls work inside the active pointer handler, including functions it calls. Elsewhere they produce `E4020`. Try the [click example](../builtins/pointerClicked.md).

## Why the numbers can differ from your screen

The scene uses 640 by 360 **logical pixels**, the program's own coordinate system. The host converts from the displayed size and position back to those coordinates. See [pixels](../concepts/pixels.md).

Press and click positions stay within x = 0 through 639 and y = 0 through 359. Release coordinates can be outside that area. **Signed** means they may be negative: x = -5 is five logical pixels to the left of the scene. They fit in a signed 32-bit whole number.

**Flooring** rounds down toward the next lower whole number: 12.8 becomes 12, and -0.2 becomes -1. **Clamping** would force an outside position onto an edge; Pliro does not do that for releases. Releasing outside can trigger release, but never click.

## Remembering one gesture

The host **claims** a pointer by choosing to follow that pointer until the gesture ends. **Capture** helps it keep receiving that pointer's events outside the drawing area. If the gesture is cancelled or capture is lost, Pliro does not invent a release or click. An already accepted press stays accepted. Extra or duplicate presses and other pointers do not start another accepted gesture at that time.

Each handler receives a **snapshot**, the position saved when its event happened. It is **immutable**: moving the mouse later does not change it. It remains available when that same handler waits, calls a function, or broadcasts a message. A separately queued handler has its own execution and does not inherit that position.

Pointer handlers keep a suitable program ready for more input. The [host](hosts.md), the environment running the program, must support the required pointer events. Stop, exit, or a runtime failure ends the run. Pointer move and drag events are not implemented yet. See [events, timers, and messages](events.md) for their shared scheduling rules.

## Related entries

[Syntax and values](../syntax/README.md) · [Built-ins](../builtins/README.md) · [Programming guides](README.md)