# pointerPressed

[Built-ins](README.md)

Canonical ID: `events.pointerPressed`. Nederlands: `aanwijzerGedrukt`.

A **pointer** can be a mouse, touch, or pen in a supporting host. **Primary** selects the main pointer action; a mouse normally uses its main button. A **handler** is the block below `when`. The host **claims** a pointer by following that one pointer through its press and release. [The pointer guide](../guides/pointer-input.md) explains snapshots, capture, signed coordinates, flooring, and clamping with examples.

Runs once when a primary down inside the logical scene claims a pointer. Its coordinate reporters use the bounded down position. Later cancellation does not retract an accepted press. Extra or duplicate downs and non-primary buttons do not create another press. Registering this handler alone is sufficient; the other pointer handlers are optional. The host must support the required persistent pointer stream.

## Signature

```text
when pointerPressed("primary"):
```

## Arguments

| Parameter | Type | Requirement |
|---|---|---|
| `button` | Text literal | Exactly the direct literal "primary"; not a variable or translated word. |

## Return value

Event descriptor.

## Example

```pliro
# language: en
when started():
    clearCanvas("white")
when pointerPressed("primary"):
    say pointerX(), pointerY()
```

Use a graphical host and perform the documented gesture; the program prints the event coordinates. Stop ends the persistent program.

## Notes and common mistakes

Use the function name for your source language. Its [canonical ID](../concepts/canonical-identity.md) is a shared documentation label; you do not type that ID as a call. Giving your own variable or function the same name can hide the built-in. Supply the documented [arguments](../concepts/parameters-and-arguments.md) and value types. Pliro reports mismatches when checking can detect them, or when the call runs.

An **event descriptor** selects the event in a top-level `when` header, outside other blocks (`E3201`–`E3203`). A **reporter** is an ordinary function that returns a value, such as `pointerX`; `broadcast` is an ordinary call too. A **handler** is the block reacting to an event. Key and pointer handlers keep a run ready for future input and need [host support](../guides/hosts.md) (`E4019`). Pointer reporters need the current pointer event (`E4020`). The whole run has a shared [event-work limit](../guides/limits.md) (`E4018`). Ordinary setup must finish before handlers get turns. See [event rules](../guides/events.md) and [pointer positions](../guides/pointer-input.md).

## Related entries

[started](started.md) · [after](after.md) · [messageReceived](messageReceived.md) · [keyPressed](keyPressed.md) · [pointerReleased](pointerReleased.md) · [Programming guides](../guides/events.md) · [Host support](../guides/hosts.md) · [Calls and arguments](../syntax/calls.md)