OpenLIME

Class: PointerManager

PointerManager

The PointerManager class serves as a central event manager that interprets raw pointer events (like mouse clicks, touch gestures, or stylus inputs) into higher-level gestures. It abstracts away the complexity of handling multiple input types and transforms them into common gestures like taps, holds, panning (drag), and pinch-to-zoom, which are common in modern user interfaces.

Key mechanisms:

  1. Event Handling and Gesture Recognition:

    • PointerManager listens for low-level pointer events (such as pointerdown, pointermove, and pointerup) and converts them into higher-level gestures.
    • For example, a quick touch and release is interpreted as a "tap," while a sustained touch (greater than 600ms) is recognized as a "hold."
    • It handles both mouse and touch events uniformly, making it ideal for web applications that need to support diverse input devices (mouse, trackpad, touch screens).

  2. Multi-pointer Support:

    • PointerManager supports multiple pointers simultaneously, making it capable of recognizing complex gestures involving more than one finger or pointer, such as pinch-to-zoom.
    • For multi-pointer gestures, it tracks each pointer's position and movement separately, allowing precise gesture handling.

  3. Idle Detection:

    • The class includes idle detection mechanisms, which can trigger actions or events when no pointer activity is detected for a specified period. This can be useful for implementing user inactivity warnings or pausing certain interactive elements when the user is idle.

  4. Callback-based Gesture Management:

    • The core of the PointerManager class revolves around registering and triggering callbacks for different gestures. Callbacks are provided by the user of this class for events like pan (onPan), pinch (onPinch), and others.
    • The class ensures that once a gesture starts, it monitors and triggers the appropriate callbacks, such as panStart, panMove, and panEnd, depending on the detected gesture.

  5. Buffer Management:

    • The PointerManager class also includes a buffer system for managing and storing recent events, allowing the developer to enqueue, push, pop, or shift pointer data as needed. This can be helpful for applications that need to track the history of pointer events for gesture recognition or undo functionality.

  6. Error Handling:

    • The class includes error handling to ensure that all required gesture handlers are defined by the user. For example, it will throw an error if any essential callback functions for pan or pinch gestures are missing, ensuring robust gesture management.

Typical usage involves:

  • Registering gesture handlers (e.g., for taps, panning, pinching).
  • The class then monitors all pointer events and triggers the corresponding gesture callbacks when appropriate.

Example:

const manager = new PointerManager();
manager.onPan({
  panStart: (e) => console.log('Pan started', e),
  panMove: (e) => console.log('Panning', e),
  panEnd: (e) => console.log('Pan ended', e),
  priority: 1
});
manager.onPinch({
  pinchStart: (e) => console.log('Pinch started', e),
  pinchMove: (e) => console.log('Pinching', e),
  pinchEnd: (e) => console.log('Pinch ended', e),
  priority: 1
});

In this example, PointerManager registers handlers for pan and pinch gestures, automatically converting pointer events into the desired interactions. By abstracting the raw pointer events, PointerManager allows developers to focus on handling higher-level gestures without worrying about the underlying complexity.

new PointerManager(target [, options])

Creates a new PointerManager instance.

Parameters:
Name Type Argument Description
target HTMLElement

DOM element to attach event listeners to
options Object <optional>

Configuration options

Properties
Name Type Argument Default Description
pinchMaxInterval number <optional>
 250

Maximum time (ms) between touches to trigger pinch
idleTime number <optional>
 60

Seconds of inactivity before idle event
Source:
Fires:
  • PointerManager#event:fingerHover - Triggered when a pointer moves over a target.
  • PointerManager#event:fingerSingleTap - Triggered on a quick touch or click.
  • PointerManager#event:fingerDoubleTap - Triggered on two quick touches or clicks.
  • PointerManager#event:fingerHold - Triggered when a touch or click is held for more than 600ms.
  • PointerManager#event:mouseWheel - Triggered when the mouse wheel is rotated.
  • PointerManager#event:panStart - Triggered when a pan (drag) gesture begins.
  • PointerManager#event:panMove - Triggered during a pan gesture.
  • PointerManager#event:panEnd - Triggered when a pan gesture ends.
  • PointerManager#event:pinchStart - Triggered when a pinch gesture begins.
  • PointerManager#event:pinchMove - Triggered during a pinch gesture.
  • PointerManager#event:pinchEnd - Triggered when a pinch gesture ends.

Members

<static, readonly> ANYPOINTER :number

Constant for targeting all pointers.

Type:
  • number
Source:

Methods

off(eventTypes, callback [, idx])

Unregisters event handlers.

Parameters:
Name Type Argument Default Description
eventTypes string

Space-separated list of event types
callback Object | function

Handler to remove
idx number <optional>
 ANYPOINTER

Pointer index to target
Source:

on(eventTypes, obj [, idx])

Registers event handlers.

Parameters:
Name Type Argument Default Description
eventTypes string

Space-separated list of event types
obj Object | function

Handler object or function
idx number <optional>
 ANYPOINTER

Pointer index to target, or ANYPOINTER for all
Source:
Returns:

Handler object

Type
Object

onEvent(handler)

Registers a complete event handler with multiple callbacks.

Parameters:
Name Type Description
handler Object

Handler object

Properties
Name Type Argument Description
priority number

Handler priority (higher = earlier execution)
fingerHover function <optional>

Hover callback
fingerSingleTap function <optional>

Single tap callback
fingerDoubleTap function <optional>

Double tap callback
fingerHold function <optional>

Hold callback
mouseWheel function <optional>

Mouse wheel callback
panStart function <optional>

Pan start callback
panMove function <optional>

Pan move callback
panEnd function <optional>

Pan end callback
pinchStart function <optional>

Pinch start callback
pinchMove function <optional>

Pinch move callback
pinchEnd function <optional>

Pinch end callback
Source:
Throws:

If handler lacks priority or required callbacks

Type
Error

onPan(handler)

Registers callbacks for pan gestures (start, move, and end).

Parameters:
Name Type Description
handler Object

The handler object containing pan gesture callbacks.

Properties
Name Type Description
panStart function

Callback function executed when the pan gesture starts.
panMove function

Callback function executed during the pan gesture movement.
panEnd function

Callback function executed when the pan gesture ends.
Source:
Throws:

Throws an error if any required callback functions (panStart, panMove, panEnd) are missing.

Type
Error

onPinch(handler)

Registers callbacks for pinch gestures (start, move, and end).

Parameters:
Name Type Description
handler Object

The handler object containing pinch gesture callbacks.

Properties
Name Type Description
pinchStart function

Callback function executed when the pinch gesture starts.
pinchMove function

Callback function executed during the pinch gesture movement.
pinchEnd function

Callback function executed when the pinch gesture ends.
Source:
Throws:

Throws an error if any required callback functions (pinchStart, pinchMove, pinchEnd) are missing.

Type
Error