Home /Modules/ballum/05-pointer-input.md

05-pointer-input.md

lib/ballum/tutorials/05-pointer-input.md · 67 line(s) · markdown

Lesson 5 — Mouse and Touch Input

Ballum normalizes pointer input into raw events and, in the higher-level listener, gestures such as click and drag. The API is polled rather than relying on an application callback for every event. That makes polling straightforward to integrate into a loop, but it also means the program must manage work limits, idle behavior, and event processing deliberately.

Documented gesture codes

CodeGesture
0NONE
1DOWN
2MOVE
3CLICK
4DRAG_BEGIN
5DRAG_MOVE
6DRAG_END

Use the constants or mapping supplied by the current package where available; avoid scattering unexplained numeric values throughout an application. A raw event and a derived gesture are different abstraction levels. Do not assume every backend emits identical event sequences or that every physical input device produces every gesture type.

Poll without hanging

A typical event-processing pass should have a clear upper bound. A frame can drain available events until the poll reports that no event is ready, but a teaching example or diagnostic should cap the number of polls/events it processes in one pass. That keeps an event burst from monopolizing the program and prevents a broken polling contract from creating an infinite loop.

Conceptually:

processed = 0
while processed < maximum_events:
    result = poll next event
    if result means no event is available:
        stop this pass
    if result is an error:
        report it and stop or recover
    validate and handle the event
    processed = processed + 1

This is pseudocode; use the real SLeeLa syntax and Ballum return conventions. Distinguish “no event available” from an actual error if the API exposes those states separately.

Handle event data carefully

Platform and permission limits

The package README currently documents live X11 pointer input on Linux and unavailable global input capture on macOS and Windows pending their respective permission-aware hooks. This is a statement about the current project implementation, not a general statement that those operating systems cannot support input APIs. Platform support must be checked against the source and actual build in use.

Global input capture can have privacy and security implications. Respect operating-system permission prompts and user consent; do not attempt to bypass accessibility, input-monitoring, or desktop-session security boundaries.

Example

See 04-input-polling.sleela. It is intended to show bounded polling and basic event reporting. Before running it, confirm that input capture is implemented and permitted on the target host. On a host without support, the correct result is a clear unavailable/unsupported status, not fabricated events.

Troubleshooting

Checkpoint: explain why “no event” is not necessarily an error and why event polling needs both a bound and an idle strategy.