PointerEventinterface

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 theprimary pointer,these events (with the exception of {{GlobalEventHandlers/gotpointercapture}} and {{GlobalEventHandlers/lostpointercapture}}) may also firecompatibility mouse events.

Thetouch-actionCSS property

Thetouch-actionCSS property determines whetherdirect manipulationinteractions (which are not limited to touch, despite the property's name) MAY trigger the user agent's panning and zooming behavior. See the section ontouch-actionvalues.

Right before starting to pan or zoom, the user agent MUSTsuppress a pointer event streamif 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 adirect manipulationpointer (such as touch or stylus on a touchscreen), the effect of that input is determined by the value of thetouch-actionproperty, and the default direct manipulation behaviors of the element and its ancestors, as follows:

• A direct manipulation interaction for panning and zoomingconforms to an element'stouch-actionif 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 itconformsto thetouch-actionproperty 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 itconformsto thetouch-actionproperty of each element between the hit tested element and thedocumentelement 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 relevanttouch-actionvalue will be ignored for the duration of the action. For instance, programmatically changing thetouch-actionvalue for an element fromautotononeas 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 varioustouch-actionvalues ofpan-*,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 totouch-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 oftouch-actionvalues

Thetouch-actionproperty 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 andcontinuouszooming (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 theelement.setPointerCapture(pointerId)method. When this method is invoked, the user agent MUST run the following steps:

1. If thepointerIdprovided as the method's argument does not match any of theactive pointers,then [=exception/throw=] a {{ "NotFoundError" }} {{DOMException}}.
2. Let the |pointer| be theactive pointerspecified by the givenpointerId.
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 theactive buttons stateor the |element|'s [=Node/node document=] is not theactive documentof the |pointer|, then terminate these steps.
6. For the specifiedpointerId,set thepending pointer capture target overrideto the {{Element}} on which this method was invoked.

Releasing pointer capture

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

1. If thepointerIdprovided as the method's argument does not match any of theactive pointersand these steps are not being invoked as a result of theimplicit release of pointer capture,then [=exception/throw=] a {{ "NotFoundError" }} {{DOMException}}.
2. IfhasPointerCaptureis false for the {{Element}} with the specifiedpointerId,then terminate these steps.
3. For the specifiedpointerId,clear thepending pointer capture target override,if set.

Implicit pointer capture

Inputs that implementdirect manipulationinteractions for panning and zooming (such as touch or stylus on a touchscreen) SHOULD behave exactly as ifsetPointerCapture()was called on the target element just before the invocation of any {{GlobalEventHandlers/pointerdown}} listeners. ThehasPointerCaptureAPI may be used (eg. within any {{GlobalEventHandlers/pointerdown}} listener) to determine whether this has occurred. IfreleasePointerCapture()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 thepending pointer capture target override for thepointerIdof the {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointercancel}} event that was just dispatched, and then runprocess pending pointer capturesteps to fire {{GlobalEventHandlers/lostpointercapture}} if necessary. After runningprocess pending pointer capturesteps, 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 thepointer capture target overrideis no longer [=connected=] [[DOM]], thepointer capture target overrideSHOULD be set to the document.

When thepending pointer capture target overrideis no longer [=connected=] [[DOM]], thepending pointer capture target overridenode SHOULD be cleared.

When a pointer lock [[PointerLock]] is successfully applied on an element, the user agent MUST run the steps as if thereleasePointerCapture()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 ameasurable 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.

APointerEventhas an associatedcoalesced events list(a list of zero or morePointerEvents). For trusted {{GlobalEventHandlers/pointermove}} and {{GlobalEventHandlers/pointerrawupdate}} events, the list is a sequence of allPointerEvents 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 listinitialized 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 samepointerId,pointerType,andisPrimaryas the dispatched "parent" pointer event.
• Emptycoalesced events listandpredicted events listof 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 apointerIdfollowed 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 past points, and the speed/trajectory of the movement) what the position of future pointer movements may be. Applications can use this information with thegetPredictedEvents()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.

APointerEventhas an associatedpredicted 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 theirpredicted events listinitialized 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 samepointerId,pointerType,andisPrimaryas the dispatched "parent" pointer event.
• Emptycoalesced events listandpredicted events listof 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 trustedPointerEventis created, user agents SHOULD run the following steps for each event in the coalesced events listandpredicted events list:

1. Set the event'spointerId,pointerType, isPrimaryand {{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'scoalesced events listandpredicted events listto an empty list.
4. Initialize all other attributes to default {{PointerEvent}} values.

When a trustedPointerEvent's {{Event/target}} is changed, user agents SHOULD, for each event in the coalesced events listandpredicted 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 onlyprimary pointerscan produce compatibility mouse events,multiple primary pointerscan be active simultaneously, each producing its own compatibility mouse events. For compatibility with scripts relying on MouseEvents, the mouse transition events (mouseover,mouseout,mouseenterandmouseleave) SHOULD simulate the movement of asinglelegacy 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 theeffective position of the legacy mouse pointerin the document as follows.

Right before firing a {{GlobalEventHandlers/pointerdown}}, {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointermove}} event, or a {{GlobalEventHandlers/pointerleave}} event at thewindow,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 currenteffective legacy mouse pointer positionare both unset or they are equal, terminate these steps.
3. Dispatchmouseover,mouseout,mouseenterandmouseleaveevents as per [[UIEVENTS]] for a mouse moving from the currenteffective legacy mouse pointer positionto |T|. Consider an unset value of either currenteffective legacy mouse pointer positionor |T| as an out-of-window mouse position.
4. Seteffective legacy mouse pointer positionto |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 theisPrimaryproperty for the pointer event to be dispatched isfalsethen 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 thewindow,dispatch compatibility mouse transition events as described inTracking 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 wascanceled,then set thePREVENT MOUSE EVENTflag for thispointerType.
5. If thePREVENT MOUSE EVENTflag isnotset for thispointerTypeand the pointer event dispatched was:
   • {{GlobalEventHandlers/pointerdown}}, then fire amousedownevent.
   • {{GlobalEventHandlers/pointermove}}, then fire amousemoveevent.
   • {{GlobalEventHandlers/pointerup}}, then fire amouseupevent.
   • {{GlobalEventHandlers/pointercancel}}, then fire amouseupevent at thewindow.
6. If the pointer event dispatched was {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointercancel}}, clear thePREVENT MOUSE EVENTflag for thispointerType.

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 themousemoveevent 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 thatdoes not support hover,it SHOULD run the following steps:

1. If theisPrimaryproperty for the pointer event to be dispatched isfalsethen 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 amousemoveevent (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 thewindow,dispatch compatibility mouse transition events as described inTracking 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 wascanceled,then set thePREVENT MOUSE EVENTflag for thispointerType.
6. If thePREVENT MOUSE EVENTflag isnotset for thispointerTypeand the pointer event dispatched was:
   • {{GlobalEventHandlers/pointerdown}}, then fire amousedownevent.
   • {{GlobalEventHandlers/pointermove}}, then fire amousemoveevent.
   • {{GlobalEventHandlers/pointerup}}, then fire amouseupevent.
   • {{GlobalEventHandlers/pointercancel}}, then fire amouseupevent at thewindow.
7. If the pointer event dispatched was {{GlobalEventHandlers/pointerup}} or {{GlobalEventHandlers/pointercancel}}, clear thePREVENT MOUSE EVENTflag for thispointerType.

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