on_move Event for Pixel-Level Mouse Tracking #141

New issue

Closed

opened 2025-11-27 18:34:43 +00:00 by john · 0 comments

john commented

2025-11-27 18:34:43 +00:00

Owner

Expose per-pixel mouse movement to Python via on_move callback.

Context

Some UI patterns need continuous mouse position updates:

Custom mouse cursor graphics
Drag-and-drop operations
Drawing/painting interfaces
Grid cell highlighting (internal requirement)

This is opt-in and has performance implications that should be documented.

Definition of Done

drawable.on_move callback property
Called with (x, y) screen coordinates when mouse moves within bounds
Only fires while mouse is within drawable's AABB
C++ fast path: skip entirely when callback is None (zero overhead)
Works in both windowed and headless modes
Documentation includes performance guidance

Callback Signature

def handle_move(x, y):
    # x, y are screen coordinates (float)
    pass

frame.on_move = handle_move

Technical Notes

Performance Contract

C++ guarantees:

When on_move is None, no Python calls, no overhead
When on_move is set, called at most once per frame per drawable
Mouse position is polled, not event-driven (SFML gives us this)

Developer responsibility:

Keep on_move handlers fast
Don't set on_move on many overlapping elements
Consider throttling in Python if needed

Interaction with Enter/Exit

on_enter fires first when mouse enters
on_move fires for subsequent movement within bounds
on_exit fires when mouse leaves
If mouse enters and exits in same frame (unlikely), enter→exit, no move

Grid Internal Use

Grid cell enter/exit events need to know when mouse moves within the grid to detect cell transitions. This could be:

Internal C++ tracking (no Python call)
Grid registers an internal on_move handler

Recommend option 1 for performance - Grid tracks mouse internally and only calls Python on cell transitions.

Documentation

Should include warnings:

Note: on_move is called every frame while the mouse is within bounds 
and moving. For performance-sensitive applications, consider:
- Using on_enter/on_exit instead when possible
- Throttling updates in your handler
- Checking if actual work is needed before doing it

Dependencies

Blocked by: AABB / Hit Testing System (NEW)
Blocked by: Mouse Enter/Exit Events (NEW) - shares infrastructure

Required for: Grid Cell Events (NEW)
Enables: Custom cursor implementations
Enables: Drag-and-drop patterns

Expose per-pixel mouse movement to Python via `on_move` callback. ## Context Some UI patterns need continuous mouse position updates: - Custom mouse cursor graphics - Drag-and-drop operations - Drawing/painting interfaces - Grid cell highlighting (internal requirement) This is opt-in and has performance implications that should be documented. ## Definition of Done - [ ] `drawable.on_move` callback property - [ ] Called with `(x, y)` screen coordinates when mouse moves within bounds - [ ] Only fires while mouse is within drawable's AABB - [ ] C++ fast path: skip entirely when callback is None (zero overhead) - [ ] Works in both windowed and headless modes - [ ] Documentation includes performance guidance ## Callback Signature ```python def handle_move(x, y): # x, y are screen coordinates (float) pass frame.on_move = handle_move ``` ## Technical Notes ### Performance Contract C++ guarantees: - When `on_move` is None, no Python calls, no overhead - When `on_move` is set, called at most once per frame per drawable - Mouse position is polled, not event-driven (SFML gives us this) Developer responsibility: - Keep `on_move` handlers fast - Don't set `on_move` on many overlapping elements - Consider throttling in Python if needed ### Interaction with Enter/Exit - `on_enter` fires first when mouse enters - `on_move` fires for subsequent movement within bounds - `on_exit` fires when mouse leaves - If mouse enters and exits in same frame (unlikely), enter→exit, no move ### Grid Internal Use Grid cell enter/exit events need to know when mouse moves within the grid to detect cell transitions. This could be: 1. Internal C++ tracking (no Python call) 2. Grid registers an internal on_move handler Recommend option 1 for performance - Grid tracks mouse internally and only calls Python on cell transitions. ## Documentation Should include warnings: ``` Note: on_move is called every frame while the mouse is within bounds and moving. For performance-sensitive applications, consider: - Using on_enter/on_exit instead when possible - Throttling updates in your handler - Checking if actual work is needed before doing it ``` ## Dependencies - **Blocked by**: AABB / Hit Testing System (NEW) - **Blocked by**: Mouse Enter/Exit Events (NEW) - shares infrastructure ## Related Issues - Required for: Grid Cell Events (NEW) - Enables: Custom cursor implementations - Enables: Drag-and-drop patterns