feat: events

[gselzer]

This PR adds a hierarchical event system for responding to user interaction. This is the main barrier to usage in e.g. NDV. It is blocked by #27, it relies upon the camera projection matrix to map each event to a ray traveling through the world.

Event Objects

This PR introduces an Event class hierarchy designed to abstract the various event objects of each widget toolkit that could display a scenex scene. The Event dataclass itself is minimal, with only a type field indicating the category of event. Subdataclasses MouseEvent, WheelEvent, etc. provide the additional fields necessary for containing the information needed to process a mouse press, wheel scroll, etc. respectively.

Event generation:

Each CanvasAdaptor is responsible for passing its native widget to the relevant AppWrap object (QtAppWrap, GlfwAppWrap, etc.). The exact AppWrap object involved depends on the active widget toolkit and is selected similarly to how NDV selects its toolkit. The AppWrap object creates an EventFilter for the native widget, responsible for converting the qt/glfw/... events into scenex events.

Event propagation:

When an event occurs over a particular position on the canvas, it is converted into a ray emanating from the camera into the world. Each object in the scene is checked for an intersection with that ray. All objects intersected by the ray are sorted by the depth at which they intersect.

For objects [o1, o2, ..., on] in this list, events are passed to:

1. o1
2. o1's parent, grandparent, ... recursively
3. o2
4. o2's parent, grandparent, ... recursively
   ...
5. on
6. on's parent, grandparent, ... recursively
7. The view's camera.

Event filtering

The user is able to install an event filter on any node in the scene (including cameras) using

class Node(EventedBase):
    def set_event_filter(self, callable: Callable[[Event, Node], bool] | None) -> Callable[[Event, Node], bool] | None:

The Callable provided will receive the scenex Event as well as the Node oi that was intersected by the world ray. Within this function, they can edit the scene as needed and then return True if they wish to prevent further objects from processing this event.

Note that with the camera receiving the event as well, this seems the best way to enable controlling the camera with pan/zoom, orbit, etc.

TODOs

The main thing is to ensure this pattern is sufficient for our needs with (but not limited to!) NDV. We can certainly add:

• More event subdataclasses (Key events, Mouse enter/leave)
• More widget backends (wx, jupyter are the main ones)
• More camera filters/controllers

Of course, beyond that, testing/removing FIXMEs/etc is necessary.