Using the mouse or a pointing device
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.
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.
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, 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 for their shared scheduling rules.