Pointer Events

4.1 PointerEvent Interface

WebIDLdictionary 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;
    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;
    [SecureContext] sequence<PointerEvent> getCoalescedEvents();
    sequence<PointerEvent> getPredictedEvents();
};

4.2 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 gotpointercapture and lostpointercapture) may also fire compatibility mouse events.

8.1 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.

While panning and zooming, the user agent MUST NOT fire subsequent pointer events for the pointer. In order to end the stream of events for the pointer, the user agent MUST fire a pointer event named pointercancel (and subsequently a pointerout event and one or more pointerleave events) whenever all of the following 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 pointerdown event has been sent for the pointer, and
• a pointerup or pointercancel event (following the above mentioned pointerdown) has not yet been sent for the pointer.

8.2 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 to affect 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 and zooming is supported if it conforms to the touch-action property of each element between the hit tested element and its nearest ancestor with the default direct manipulation behavior (including both the hit tested element and the element with the default direct manipulation behavior).
• 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 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.

8.3 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 are 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).

9.2 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, a 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 throw a DOMException with the name NotFoundError.
2. Let the pointer be the active pointer specified by the given pointerId.
3. If the element is not connected ([DOM]), throw an exception with the name InvalidStateError.
4. If this method is invoked while the element's node document [DOM] has a locked element ([PointerLock]), throw an exception with the name InvalidStateError.
5. If the pointer is not in the active buttons state or the element's node document [DOM] 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.

9.3 Releasing Pointer Capture

Pointer capture is released on an element explicitly by calling the element.releasePointerCapture(pointerId) method. When this method is called, a 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 throw a DOMException with the name NotFoundError.
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.

9.4 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 pointerdown listeners. The hasPointerCapture API may be used (eg. within any 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 gotpointercapture event will be dispatched to the target (as normal) indicating that capture is active.

9.5 Implicit Release of Pointer Capture

Immediately after firing the pointerup or pointercancel events, a user agent MUST clear the pending pointer capture target override for the pointerId of the pointerup or pointercancel event that was just dispatched, and then run Process Pending Pointer Capture steps to fire 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.

If the user agent supports firing the click event (see compatibility mouse events), and if in an implicit release scenario both click and lostpointercapture events are fired, click SHOULD be fired before lostpointercapture.

When the pointer capture target override is no longer connected ([DOM]), the pending pointer capture target override and pointer capture target override nodes SHOULD be cleared and also a PointerEvent named lostpointercapture corresponding to the captured pointer SHOULD be fired at the document.

When a pointer lock ([PointerLock]) is successfully applied on an element, a 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.

10.1 Coalesced events

For performance reasons, user agents may choose not to send a pointermove event every time the position of a pointer is updated. Instead, they will coalesce (combine/merge) multiple position changes into a single move 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 event list (a list of zero or more PointerEvents). If this event is a pointermove or pointerrawupdate event, the list is a sequence of all PointerEvents that were coalesced into this event; otherwise it is an empty list.

The events in the coalesced event list will have increasing timeStamps ([WHATWG-DOM]), so the first event will have the smallest timeStamp.

<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>
    var 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>

10.2 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 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 event list (a list of zero or more PointerEvents). If this event is a pointermove event, it is a sequence of PointerEvents that the user agent predicts will follow the events in the coalesced event list in the future; otherwise it is an empty list.

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 event list will have increasing timeStamps([WHATWG-DOM]), so the first event will have the smallest timeStamp which should still be greater than the last event in the coalesced event list.

var 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);
    }
});

10.3 Populating and maintaining the coalesced and predicted event lists

When a PointerEvent is created, run the following steps for each event in the coalesced event list and predicted event list:

1. Set the event's pointerId, pointerType, isPrimary and isTrusted to the PointerEvent's pointerId, pointerType, isPrimary and isTrusted.
2. Set the event's cancelable and bubbles attributes to false.
3. Set the event's coalesced event list and predicted event list to an empty list.
4. Initialize the rest of the attributes the same way as PointerEvent.

A PointerEvent has an associated coalesced events targets dirty and an associated predicted events targets dirty flag. When an event is created they must be initialized to false.

When the PointerEvent's target is changed, set coalesced events targets dirty and predicted events targets dirty to true.

When the getCoalescedEvents method is called:

1. If the coalesced events targets dirty is true: for each event in the coalesced event list, set the event's target to this PointerEvent's target.
2. Set the coalesced events targets dirty to false.
3. Return the coalesced event list.

When the getPredictedEvents method is called:

1. If the predicted events targets dirty is true: for each event in the predicted event list, set the event's target to this PointerEvent's target.
2. Set the predicted events targets dirty to false.
3. Return the predicted event list.

11.1 Tracking the effective position of the legacy mouse pointer

While only the primary pointers can produce compatibility mouse events, multiple primary pointers can be active simultaneously, each producing its own compatibility mouse events. Since all these compatibility events would appear to MouseEvent code to be coming from a single mouse device, user agents are encouraged to guarantee that the compatibility mouse events are consistent from a single device perspective. For mouse transition events (i.e., mouseover, mouseout, mouseenter and mouseleave), this means the entry/exit state for every event target is valid as implied by [UI-EVENTS]. Users agents SHOULD guarantee this by maintaining the effective position of the legacy mouse pointer in the document as follows.

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

1. Let T be the target of the pointerdown, pointerup or pointermove event being dispatched. For the 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 [UI-EVENTS] 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.

11.2 Mapping for devices that support hover

Whenever a 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 pointerdown, pointerup or pointermove event, or a 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 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:
   • pointerdown, then fire a mousedown event.
   • pointermove, then fire a mousemove event.
   • pointerup, then fire a mouseup event.
   • pointercancel, then fire a mouseup event at the window.
6. If the pointer event dispatched was pointerup or pointercancel, clear the PREVENT MOUSE EVENT flag for this pointerType.

11.3 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 a 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 pointerover and the 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 is dispatched is a pointerdown, pointerup or pointermove event, or a 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 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:
   • pointerdown, then fire a mousedown event.
   • pointermove, then fire a mousemove event.
   • pointerup, then fire a mouseup event.
   • pointercancel, then fire a mouseup event at the window.
7. If the pointer event dispatched was pointerup or pointercancel, clear the PREVENT MOUSE EVENT flag for this pointerType.