PointerEvent interface

dictionary PointerEventInit : MouseEventInit {
    long        pointerId = 0;
    double      width = 1;
    double      height = 1;
    float       pressure = 0;
    float       tangentialPressure = 0;
    long        tiltX;
    long        tiltY;
    long        twist = 0;
    double      altitudeAngle;
    double      azimuthAngle;
    DOMString   pointerType = "";
    boolean     isPrimary = false;
    long        persistentDeviceId = 0;
    sequence<PointerEvent> coalescedEvents = [];
    sequence<PointerEvent> predictedEvents = [];
};

[Exposed=Window]
interface PointerEvent : MouseEvent {
    constructor(DOMString type, optional PointerEventInit eventInitDict = {});
    readonly        attribute long        pointerId;
    readonly        attribute double      width;
    readonly        attribute double      height;
    readonly        attribute float       pressure;
    readonly        attribute float       tangentialPressure;
    readonly        attribute long        tiltX;
    readonly        attribute long        tiltY;
    readonly        attribute long        twist;
    readonly        attribute double      altitudeAngle;
    readonly        attribute double      azimuthAngle;
    readonly        attribute DOMString   pointerType;
    readonly        attribute boolean     isPrimary;
    readonly        attribute long        persistentDeviceId;
    [SecureContext] sequence<PointerEvent> getCoalescedEvents();
    sequence<PointerEvent> getPredictedEvents();
};

/* Converting between tiltX/tiltY and altitudeAngle/azimuthAngle */

function spherical2tilt(altitudeAngle, azimuthAngle) {
  const radToDeg = 180/Math.PI;

  let tiltXrad = 0;
  let tiltYrad = 0;

  if (altitudeAngle == 0) {
    // the pen is in the X-Y plane
    if (azimuthAngle == 0 || azimuthAngle == 2*Math.PI) {
      // pen is on positive X axis
      tiltXrad = Math.PI/2;
    }
    if (azimuthAngle == Math.PI/2) {
      // pen is on positive Y axis
      tiltYrad = Math.PI/2;
    }
    if (azimuthAngle == Math.PI) {
      // pen is on negative X axis
      tiltXrad = -Math.PI/2;
    }
    if (azimuthAngle == 3*Math.PI/2) {
      // pen is on negative Y axis
      tiltYrad = -Math.PI/2;
    }
    if (azimuthAngle>0 && azimuthAngle<Math.PI/2) {
      tiltXrad = Math.PI/2;
      tiltYrad = Math.PI/2;
    }
    if (azimuthAngle>Math.PI/2 && azimuthAngle<Math.PI) {
      tiltXrad = -Math.PI/2;
      tiltYrad = Math.PI/2;
    }
    if (azimuthAngle>Math.PI && azimuthAngle<3*Math.PI/2) {
      tiltXrad = -Math.PI/2;
      tiltYrad = -Math.PI/2;
    }
    if (azimuthAngle>3*Math.PI/2 && azimuthAngle<2*Math.PI) {
      tiltXrad = Math.PI/2;
      tiltYrad = -Math.PI/2;
    }
  }

  if (altitudeAngle != 0) {
    const tanAlt = Math.tan(altitudeAngle);

    tiltXrad = Math.atan(Math.cos(azimuthAngle) / tanAlt);
    tiltYrad = Math.atan(Math.sin(azimuthAngle) / tanAlt);
  }

  return {"tiltX":tiltXrad*radToDeg, "tiltY":tiltYrad*radToDeg};
}

function tilt2spherical(tiltX, tiltY) {
  const tiltXrad = tiltX * Math.PI/180;
  const tiltYrad = tiltY * Math.PI/180;

  // calculate azimuth angle
  let azimuthAngle = 0;

  if (tiltX == 0) {
    if (tiltY > 0) {
      azimuthAngle = Math.PI/2;
    }
    else if (tiltY < 0) {
      azimuthAngle = 3*Math.PI/2;
    }
  } else if (tiltY == 0) {
    if (tiltX < 0) {
      azimuthAngle = Math.PI;
    }
  } else if (Math.abs(tiltX) == 90 || Math.abs(tiltY) == 90) {
    // not enough information to calculate azimuth
    azimuthAngle = 0;
  } else {
    // Non-boundary case: neither tiltX nor tiltY is equal to 0 or +-90
    const tanX = Math.tan(tiltXrad);
    const tanY = Math.tan(tiltYrad);

    azimuthAngle = Math.atan2(tanY, tanX);
    if (azimuthAngle < 0) {
      azimuthAngle += 2*Math.PI;
    }
  }

  // calculate altitude angle
  let altitudeAngle = 0;

  if (Math.abs(tiltX) == 90 || Math.abs(tiltY) == 90) {
      altitudeAngle = 0
  } else if (tiltX == 0) {
    altitudeAngle = Math.PI/2 - Math.abs(tiltYrad);
  } else if (tiltY == 0) {
    altitudeAngle = Math.PI/2 - Math.abs(tiltXrad);
  } else {
    // Non-boundary case: neither tiltX nor tiltY is equal to 0 or +-90
    altitudeAngle =  Math.atan(1.0/Math.sqrt(Math.pow(Math.tan(tiltXrad),2) + Math.pow(Math.tan(tiltYrad),2)));
  }

  return {"altitudeAngle":altitudeAngle, "azimuthAngle":azimuthAngle};
}

Pointer Event types

Below are the event types defined in this specification.

In the case of the primary pointer, these events (with the exception of {{GlobalEventHandlers/gotpointercapture}} and {{GlobalEventHandlers/lostpointercapture}}) may also fire compatibility mouse events.

The touch-action CSS property

The touch-action CSS property determines whether direct manipulation interactions (which are not limited to touch, despite the property's name) MAY trigger the user agent's panning and zooming behavior. See the section on touch-action values.

Right before starting to pan or zoom, the user agent MUST suppress a pointer event stream if all of the following conditions are true:

• The user agent has determined (via methods out of scope for this specification) that a direct manipulation interaction is to be consumed for panning or zooming,
• a {{GlobalEventHandlers/pointerdown}} event has been sent for the pointer, and
• a {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointercancel}} event (following the above mentioned {{GlobalEventHandlers/pointerdown}}) has not yet been sent for the pointer.

Determining supported direct manipulation behavior

When a user interacts with an element using a direct manipulation pointer (such as touch or stylus on a touchscreen), the effect of that input is determined by the value of the touch-action property, and the default direct manipulation behaviors of the element and its ancestors, as follows:

• A direct manipulation interaction for panning and zooming conforms to an element's touch-action if the behavior is allowed in the coordinate space of the element. Note that if CSS transforms have been applied, the element's coordinate space may differ from the screen coordinate in a way that affects the conformity here; for example, the X axis of an element rotated by 90 degrees with respect to the screen will be parallel to the Y-axis of the screen coordinate.
• A direct manipulation interaction for panning is supported if it conforms to the touch-action property of each element between the hit tested element and its nearest inclusive ancestor that is a [=scroll container=] (as defined in [[CSS-OVERFLOW-3]]).
• A direct manipulation interaction for zooming is supported if it conforms to the touch-action property of each element between the hit tested element and the document element of the [=top-level browsing context=] (as defined in [[HTML]]).
• Once panning or zooming has been started, and the user agent has already determined whether or not the gesture should be handled as a user agent direct manipulation behavior, any changes to the relevant touch-action value will be ignored for the duration of the action. For instance, programmatically changing the touch-action value for an element from auto to none as part of a {{GlobalEventHandlers/pointerdown}} handler script will not result in the user agent aborting or suppressing any of the pan or zoom behavior for that input for as long as that pointer is active.
• Similarly, in the case of the various touch-action values of pan-*, once the user agent has determined whether to handle a gesture directly or not at the start of the gesture, a subsequent change in the direction of the same gesture SHOULD be ignored by the user agent for as long as that pointer is active. For instance, if an element has been set to touch-action: pan-y (meaning that only vertical panning is handled by the user agent), and a touch gesture starts off horizontally, no vertical panning should occur if the user changes the direction of their gesture to be vertical while their finger is still touching the screen.

Details of touch-action values

The touch-action property covers direct manipulation behaviors related to viewport panning and zooming. Any additional user agent behaviors, such as text selection/highlighting, or activating links and form controls, MUST NOT be affected by this CSS property.

auto

The user agent MAY consider any permitted direct manipulation behaviors related to panning and zooming of the viewport that begin on the element.

none

Direct manipulation interactions that begin on the element MUST NOT trigger behaviors related to viewport panning and zooming.

pan-x
pan-left
pan-right
pan-y
pan-up
pan-down

The user agent MAY consider direct manipulation interactions that begin on the element only for the purposes of panning that starts in any of the directions specified by all of the listed values. Once panning has started, the direction may be reversed by the user even if panning that starts in the reversed direction is disallowed. In contrast, when panning is restricted to a single axis (eg. pan-y), the axis cannot be changed during panning.

manipulation

The user agent MAY consider direct manipulation interactions that begin on the element only for the purposes of panning and continuous zooming (such as pinch-zoom), but MUST NOT trigger other related behaviors that rely on multiple activations that must happen within a set period of time (such as double-tap to zoom, or double-tap and hold for single-finger zoom).

Setting pointer capture

Pointer capture is set on an |element| of type {{Element}} by calling the element.setPointerCapture(pointerId) method. When this method is invoked, the user agent MUST run the following steps:

1. If the pointerId provided as the method's argument does not match any of the active pointers, then [=exception/throw=] a {{"NotFoundError"}} {{DOMException}}.
2. Let the |pointer| be the active pointer specified by the given pointerId.
3. If the |element| is not [=connected=] [[DOM]], [=exception/throw=] an {{"InvalidStateError"}} {{DOMException}}.
4. If this method is invoked while the |element|'s [=Node/node document=] [[DOM]] has a locked element ([[PointerLock]] {{DocumentOrShadowRoot/pointerLockElement}}), [=exception/throw=] an {{"InvalidStateError"}} {{DOMException}}.
5. If the |pointer| is not in the active buttons state or the |element|'s [=Node/node document=] is not the active document of the |pointer|, then terminate these steps.
6. For the specified pointerId, set the pending pointer capture target override to the {{Element}} on which this method was invoked.

Releasing pointer capture

Pointer capture is released on an element explicitly by calling the element.releasePointerCapture(pointerId) method. When this method is called, the user agent MUST run the following steps:

1. If the pointerId provided as the method's argument does not match any of the active pointers and these steps are not being invoked as a result of the implicit release of pointer capture, then [=exception/throw=] a {{"NotFoundError"}} {{DOMException}}.
2. If hasPointerCapture is false for the {{Element}} with the specified pointerId, then terminate these steps.
3. For the specified pointerId, clear the pending pointer capture target override, if set.

Implicit pointer capture

Inputs that implement direct manipulation interactions for panning and zooming (such as touch or stylus on a touchscreen) SHOULD behave exactly as if setPointerCapture() was called on the target element just before the invocation of any {{GlobalEventHandlers/pointerdown}} listeners. The hasPointerCapture API may be used (eg. within any {{GlobalEventHandlers/pointerdown}} listener) to determine whether this has occurred. If releasePointerCapture() is not called for the pointer before the next pointer event is fired, then a {{GlobalEventHandlers/gotpointercapture}} event will be dispatched to the target (as normal) indicating that capture is active.

Implicit release of pointer capture

Immediately after firing the {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointercancel}} events, the user agent MUST clear the pending pointer capture target override for the pointerId of the {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointercancel}} event that was just dispatched, and then run process pending pointer capture steps to fire {{GlobalEventHandlers/lostpointercapture}} if necessary. After running process pending pointer capture steps, if the pointer supports hover, user agent MUST also send corresponding boundary events necessary to reflect the current position of the pointer with no capture.

When the pointer capture target override is no longer [=connected=] [[DOM]], the pointer capture target override SHOULD be set to the document.

When the pending pointer capture target override is no longer [=connected=] [[DOM]], the pending pointer capture target override node SHOULD be cleared.

When a pointer lock [[PointerLock]] is successfully applied on an element, the user agent MUST run the steps as if the releasePointerCapture() method has been called if any element is set to be captured or pending to be captured.

Coalesced events

For performance reasons, user agents may choose not to send a {{GlobalEventHandlers/pointermove}} event every time a measurable property (such as coordinates, pressure, tangential pressure, tilt, twist, or contact geometry) of a pointer is updated. Instead, they may coalesce (combine/merge) multiple changes into a single {{GlobalEventHandlers/pointermove}} or {{GlobalEventHandlers/pointerrawupdate}} event. While this approach helps in reducing the amount of event handling the user agent must perform, it will naturally reduce the granularity and fidelity when tracking a pointer position, particularly for fast and large movements. Using the getCoalescedEvents() method it is possible for applications to access the raw, un-coalesced position changes. These allow for a more precise handling of pointer movement data. In the case of drawing applications, for instance, the un-coalesced events can be used to draw smoother curves that more closely match the actual movement of a pointer.

A PointerEvent has an associated coalesced events list (a list of zero or more PointerEvents). For trusted {{GlobalEventHandlers/pointermove}} and {{GlobalEventHandlers/pointerrawupdate}} events, the list is a sequence of all PointerEvents that were coalesced into this event. The "parent" trusted {{GlobalEventHandlers/pointermove}} and {{GlobalEventHandlers/pointerrawupdate}} event represents an accumulation of these coalesced events, but may have additional processing (for example to align with the display refresh rate). As a result, the coalesced events lists for these events always contain at least one event. For all other trusted event types, it is an empty list. Untrusted events have their coalesced events list initialized to the value passed to the constructor.

The events in the coalesced events list of a trusted event will have:

• Monotonically increasing {{Event/timeStamp}} values [[DOM]] — all coalesced events have a {{Event/timeStamp}} that is smaller than or equal to the {{Event/timeStamp}} of the dispatched pointer event that the getCoalescedEvents() method was called on. The coalesced events list MUST be chronologically sorted by {{Event/timeStamp}}, so the first event will have the smallest {{Event/timeStamp}}.
• The same pointerId, pointerType, and isPrimary as the dispatched "parent" pointer event.
• Empty coalesced events list and predicted events list of their own.

<style>
    /* Disable intrinsic user agent direct manipulation behaviors (such as panning or zooming)
    so that all events on the canvas element are given to the application instead. */

    canvas { touch-action: none; }
</style>

<canvas id="drawSurface" width="500px" height="500px" style="border:1px solid black;"></canvas>

<script>
    const canvas = document.getElementById("drawSurface"),
    context = canvas.getContext("2d");

    canvas.addEventListener("pointermove", (e)=> {

        if (e.getCoalescedEvents) {
            for (let coalesced_event of e.getCoalescedEvents()) {
                paint(coalesced_event); // Paint all raw/non-coalesced points
            }
        } else {
            paint(e); // Paint the final coalesced point
        }
    });

    function paint(event) {
        if (event.buttons>0) {
            context.fillRect(event.clientX, event.clientY, 5, 5);
        }
    }

</script>

The order of all these dispatched events MUST match the actual order of the original events. For example if a {{GlobalEventHandlers/pointerdown}} event causes the dispatch for the coalesced {{GlobalEventHandlers/pointermove}} events the user agent MUST first dispatch one {{GlobalEventHandlers/pointermove}} event with all those coalesced events of a pointerId followed by the {{GlobalEventHandlers/pointerdown}} event.

Predicted events

Some user agents have built-in algorithms which, after a series of confirmed pointer movements, can make a prediction (based on the preceding events for the current gesture, and the speed/trajectory of the movement) what the position of future pointer movements may be. Applications can use this information with the getPredictedEvents() method to speculatively "draw ahead" to a predicted position to reduce perceived latency, and then discarding these predicted points once the actual points are received.

A PointerEvent has an associated predicted events list (a list of zero or more PointerEvents). For trusted {{GlobalEventHandlers/pointermove}} events, it is a sequence of PointerEvents that the user agent predicts will follow the event in the future. For all other trusted event types, it is an empty list. Untrusted events have their predicted events list initialized to the value passed to the constructor.

The number of events in the list and how far they are from the current timestamp are determined by the user agent and the prediction algorithm it uses.

The events in the predicted events list of a trusted event will have:

• Monotonically increasing {{Event/timeStamp}} values [[DOM]] — all predicted events have a {{Event/timeStamp}} that is greater than or equal to the {{Event/timeStamp}} of the dispatched pointer event that the getPredictedEvents() method was called on. The predicted events list MUST be chronologically sorted by {{Event/timeStamp}}, so the first event will have the smallest {{Event/timeStamp}}.
• The same pointerId, pointerType, and isPrimary as the dispatched "parent" pointer event.
• Empty coalesced events list and predicted events list of their own.

let predicted_points = [];
window.addEventListener("pointermove", function(event) {
    // Clear the previously drawn predicted points.
    for (let e of predicted_points.reverse()) {
        clearPoint(e.pageX, e.pageY);
    }

    // Draw the actual movements that happened since the last received event.
    for (let e of event.getCoalescedEvents()) {
        drawPoint(e.pageX, e.pageY);
    }

    // Draw the current predicted points to reduce the perception of latency.
    predicted_points = event.getPredictedEvents();
    for (let e of predicted_points) {
        drawPoint(e.pageX, e.pageY);
    }
});

Populating and maintaining the coalesced and predicted events lists

When a trusted PointerEvent is created, user agents SHOULD run the following steps for each event in the coalesced events list and predicted events list:

1. Set the event's pointerId, pointerType, isPrimary and {{Event/isTrusted}} to match the respective properties of the "parent" pointer event.
2. Set the event's {{Event/cancelable}} and {{Event/bubbles}} to false (as these events will never be dispatched in isolation).
3. Set the event's coalesced events list and predicted events list to an empty list.
4. Initialize all other attributes to default {{PointerEvent}} values.

When a trusted PointerEvent's {{Event/target}} is changed, user agents SHOULD, for each event in the coalesced events list and predicted events list:

1. Set the event's {{Event/target}} to match the {{Event/target}} of the "parent" pointer event.

Tracking the effective position of the legacy mouse pointer

While only primary pointers can produce compatibility mouse events, multiple primary pointers can be active simultaneously, each producing its own compatibility mouse events. For compatibility with scripts relying on MouseEvents, the mouse transition events (mouseover, mouseout, mouseenter and mouseleave) SHOULD simulate the movement of a single legacy mouse input. This means that the entry/exit state for every event target is valid, in accordance with [[UIEVENTS]]. Users agents SHOULD guarantee this by maintaining the effective position of the legacy mouse pointer in the document as follows.

Right before firing a {{GlobalEventHandlers/pointerdown}}, {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointermove}} event, or a {{GlobalEventHandlers/pointerleave}} event at the window, the user agent SHOULD run the following steps:

1. Let |T| be the target of the {{GlobalEventHandlers/pointerdown}}, {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointermove}} event being dispatched. For the {{GlobalEventHandlers/pointerleave}} event, unset |T|.
2. If |T| and current effective legacy mouse pointer position are both unset or they are equal, terminate these steps.
3. Dispatch mouseover, mouseout, mouseenter and mouseleave events as per [[UIEVENTS]] for a mouse moving from the current effective legacy mouse pointer position to |T|. Consider an unset value of either current effective legacy mouse pointer position or |T| as an out-of-window mouse position.
4. Set effective legacy mouse pointer position to |T|.

Mapping for devices that support hover

Whenever the user agent is to dispatch a pointer event for a device that supports hover, it SHOULD run the following steps:

1. If the isPrimary property for the pointer event to be dispatched is false then dispatch the pointer event and terminate these steps.
2. If the pointer event to be dispatched is a {{GlobalEventHandlers/pointerdown}}, {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointermove}} event, or a {{GlobalEventHandlers/pointerleave}} event at the window, dispatch compatibility mouse transition events as described in Tracking the effective position of the legacy mouse pointer.
3. Dispatch the pointer event.
4. If the pointer event dispatched was {{GlobalEventHandlers/pointerdown}} and the event was canceled, then set the PREVENT MOUSE EVENT flag for this pointerType.
5. If the PREVENT MOUSE EVENT flag is not set for this pointerType and the pointer event dispatched was:
   • {{GlobalEventHandlers/pointerdown}}, then fire a mousedown event.
   • {{GlobalEventHandlers/pointermove}}, then fire a mousemove event.
   • {{GlobalEventHandlers/pointerup}}, then fire a mouseup event.
   • {{GlobalEventHandlers/pointercancel}}, then fire a mouseup event at the window.
6. If the pointer event dispatched was {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointercancel}}, clear the PREVENT MOUSE EVENT flag for this pointerType.

Mapping for devices that do not support hover

Some devices, such as most touchscreens, do not support hovering a coordinate (or set of coordinates) while not in the active state. Much existing content coded to mouse events assumes that a mouse is producing the events and thus certain qualities are generally true:

• The input can hover independently of activation (e.g. moving a mouse cursor without any buttons pressed).
• The input will likely produce the mousemove event on an element before clicking it.

This requires that user agents provide a different mapping for these types of input devices. Whenever the user agent is to dispatch a pointer event for a device that does not support hover, it SHOULD run the following steps:

1. If the isPrimary property for the pointer event to be dispatched is false then dispatch the pointer event and terminate these steps.
2. If the pointer event to be dispatched is {{GlobalEventHandlers/pointerover}} and the {{GlobalEventHandlers/pointerdown}} event has not yet been dispatched for this pointer, then fire a mousemove event (for compatibility with legacy mouse-specific code).
3. If the pointer event to be dispatched is a {{GlobalEventHandlers/pointerdown}}, {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointermove}} event, or a {{GlobalEventHandlers/pointerleave}} event at the window, dispatch compatibility mouse transition events as described in Tracking the effective position of the legacy mouse pointer.
4. Dispatch the pointer event.
5. If the pointer event dispatched was {{GlobalEventHandlers/pointerdown}} and the event was canceled, then set the PREVENT MOUSE EVENT flag for this pointerType.
6. If the PREVENT MOUSE EVENT flag is not set for this pointerType and the pointer event dispatched was:
   • {{GlobalEventHandlers/pointerdown}}, then fire a mousedown event.
   • {{GlobalEventHandlers/pointermove}}, then fire a mousemove event.
   • {{GlobalEventHandlers/pointerup}}, then fire a mouseup event.
   • {{GlobalEventHandlers/pointercancel}}, then fire a mouseup event at the window.
7. If the pointer event dispatched was {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointercancel}}, clear the PREVENT MOUSE EVENT flag for this pointerType.

If the user agent supports both Touch Events (as defined in [[TOUCH-EVENTS]]) and Pointer Events, the user agent MUST NOT generate both the compatibility mouse events as described in this section, and the fallback mouse events outlined in [[TOUCH-EVENTS]].