Input System

Object-Level Events

import { ElementObject } from "@snap-engine/core";

const object = new ElementObject(engine);
object.element = myElement;

object.event.input.pointerDown = (props) => {
  console.log(props.position.x, props.position.y);
};

object.event.input.pointerMove = (props) => {
  console.log(props.position.cameraX, props.position.cameraY);
};

object.event.input.pointerUp = (props) => {
  console.log(props.position.screenX, props.position.screenY);
  console.log(props.cancelled);
};

object.event.input.mouseWheel = (props) => {
  console.log(props.delta);
};

Keyboard Events

object.event.input.keyDown = ({ event, focusedObject }) => {
  console.log(event.key);
  console.log(focusedObject);
};

focusedObject is the nearest registered ElementObject in the focused element’s composed event path. Input aliases resolve to their owning object, so a focused handle can deliver its Item directly. The same originating object is provided when the event bubbles through engine-object parents. It is null for a key event inside the engine that has no registered object owner.

Call event.preventDefault() when an application handles a key whose browser behavior should be suppressed.

Global Events

object.event.global.pointerMove = (props) => {
  console.log(props.position.x, props.position.y);
};

object.event.global.mouseWheel = (props) => {
  console.log(props.delta);
};

Drag Gestures

object.event.input.dragStart = (props) => {
  console.log(props.start.x, props.start.y);
};

object.event.input.drag = (props) => {
  console.log(props.position.x, props.position.y);
  console.log(props.delta.x, props.delta.y);
};

object.event.input.dragEnd = (props) => {
  console.log(props.end.x, props.end.y);
  console.log(props.event.target, props.cancelled);
};

Gesture handoff

Only active derived gestures expose handoff: dragStart, drag, pinchStart, and pinch. The destination may be a connected ElementObject or its engine object ID.

handle.event.input.dragStart = (props) => {
  props.handoffTo(draggable);
};

Drag handoff transfers native pointer capture and changes targeted delivery for later drag events. It does not emit cancellation to the previous owner and does not turn global subscriptions into owner callbacks. Invalid, destroyed, cross-engine, headless, or disconnected destinations throw synchronously. Pinch handoff moves only pinch/pinchEnd delivery; each finger’s native capture and pointer/drag delivery remain with its origin.

Native capture begins when a drag or pinch is recognized, not on pointerDown, so nested buttons and other pre-threshold controls retain their normal click targeting.

Constructed PointerEvent objects are always untrusted and cannot create a browser-owned active pointer. If native setPointerCapture() rejects such an event with NotFoundError, SnapEngine retains logical capture internally so the synthetic pointer stream continues to route to its gesture owner until pointerup or pointercancel. This fallback does not make the event trusted. Trusted pointer events and every other capture failure keep the normal native capture and error-reporting behavior.

handoffTo is intentionally absent from pointerDown, pointerMove, pointerUp, dragEnd, and pinchEnd.

Pinch Gestures

object.event.input.pinchStart = (props) => {
  console.log(props.start.distance);
  console.log(props.start.pointerList);
};

object.event.input.pinch = (props) => {
  const scale = props.current.distance / props.start.distance;
  console.log(scale);
};

object.event.input.pinchEnd = (props) => {
  console.log(props.end.pointerList);
  console.log(props.cancelled);
};

Targeted bubbling and global fan-out

Targeted handlers run on a snapshot of the original owner-to-parent path, leaf first. A handler failure is isolated, so later ancestors and global listeners still run. There is no propagation-stop API.

Global listeners run after targeted delivery. Claiming a pointer suppresses non-terminal global delivery for that gesture; terminal events still fan out so already-engaged listeners can clean up.

Event Position

Event Names