Pointer Events

https://www.w3.org/TR/pointerevents3/
Admin
Pointer Events provides DOM events and interfaces for handling hardware-agnostic pointer input...
Tokens:28,527
Snippets:155
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Detecting input type with pointerType (Example 2)

Source: https://www.w3.org/TR/pointerevents3

Detects the input type by switching on event.pointerType. The default case covers an empty pointerType (unable to detect) or a UA-specific custom type.

```javascript
window.addEventListener("pointerdown", detectInputType);

function detectInputType(event) {
    switch(event.pointerType) {
        case "mouse":
            /* mouse input detected */
            break;
        case "pen":
            /* pen/stylus input detected */
            break;
        case "touch":
            /* touch input detected */
            break;
        default:
            /* pointerType is empty (could not be detected)
            or UA-specific custom type */
    }
}
```

--------------------------------

### Feature detection and event binding (Example 1)

Source: https://www.w3.org/TR/pointerevents3

Feature detection for Pointer Events. If window.PointerEvent exists, only pointer events are used; otherwise fallback to touch and mouse handlers. The comment notes that e.preventDefault() on touchstart prevents compatibility mouse events and click.

```javascript
/* Bind to either Pointer Events or traditional touch/mouse */

if (window.PointerEvent) {
    // if Pointer Events are supported, only listen to pointer events
    target.addEventListener("pointerdown", function(e) {
        // if necessary, apply separate logic based on e.pointerType
        // for different touch/pen/mouse behavior
        ...
    });
    ...
} else {
    // traditional touch/mouse event handlers
    target.addEventListener('touchstart', function(e) {
        // prevent compatibility mouse events and click
        e.preventDefault();
        ...
    });
    ...
    target.addEventListener('mousedown', ...);
    ...
}

// additional event listeners for keyboard handling
...
```

--------------------------------

### Firing untrusted pointer events (Example 4)

Source: https://www.w3.org/TR/pointerevents3

Fires untrusted pointer events from script using the PointerEvent constructor and dispatchEvent. Shows how to set pointerId, pointerType, clientX/clientY, and coalescedEvents for a pointermove event.

```javascript
const event1 = new PointerEvent("pointerover",
  { bubbles: true,
    cancelable: true,
    composed: true,
    pointerId: 42,
    pointerType: "pen",
    clientX: 300,
    clientY: 500
  });
eventTarget.dispatchEvent(event1);

let pointerEventInitDict =
{
  bubbles: true,
  cancelable: true,
  composed: true,
  pointerId: 42,
  pointerType: "pen",
  clientX: 300,
  clientY: 500,
};
const p1 = new PointerEvent("pointermove", pointerEventInitDict);
pointerEventInitDict.clientX += 10;
const p2 = new PointerEvent("pointermove", pointerEventInitDict);
pointerEventInitDict.coalescedEvents = [p1, p2];
const event2 = new PointerEvent("pointermove", pointerEventInitDict);
eventTarget.dispatchEvent(event2);
```

--------------------------------

### Resizing element to contact geometry (Example 3)

Source: https://www.w3.org/TR/pointerevents3

Resizes the target element to match the contact geometry (event.width and event.height) on pointerdown. The HTML includes a div with absolute positioning and a script that attaches the handler.

```html
<div style="position:absolute; top:0px; left:0px; width:100px;height:100px;"></div>
<script>
window.addEventListener("pointerdown", checkPointerSize);

function checkPointerSize(event) {
    event.target.style.width = event.width + "px";
    event.target.style.height = event.height + "px";
}
</script>
```

--------------------------------

### Basic canvas drawing application using coalesced events

Source: https://www.w3.org/TR/pointerevents3

Example 10 from section 10.1 Coalesced events. Uses the PointerEvent.getCoalescedEvents() method to paint all raw/non-coalesced pointer points on a canvas. The CSS touch-action: none disables user agent panning/zooming so events reach the application. Falls back to painting the final coalesced point when getCoalescedEvents is unavailable.

```html
<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>
```

--------------------------------

### Element Pointer Capture Methods

Source: https://www.w3.org/TR/pointerevents3

These methods are extensions to the Element interface for setting, releasing, and checking pointer capture.

```APIDOC
## setPointerCapture(pointerId)

### Description
Sets pointer capture for the pointer identified by the argument `pointerId` to the element on which this method is invoked. For subsequent events of the pointer, the capturing target will substitute the normal hit testing result as if the pointer is always over the capturing target, and they MUST always be targeted at this element until capture is released. The pointer MUST be in its active buttons state for this method to be effective, otherwise it fails silently. When the provided method's argument does not match any of the active pointers, throw a "NotFoundError" DOMException.

### Method
setPointerCapture

### Parameters
- **pointerId** (long) - Required - The identifier of the pointer for which to set pointer capture.

### Exceptions
- **NotFoundError** - Thrown when the provided method's argument does not match any of the active pointers.

```

```APIDOC
## releasePointerCapture(pointerId)

### Description
Releases pointer capture for the pointer identified by the argument `pointerId` from the element on which this method is invoked. Subsequent events for the pointer follow normal hit testing mechanisms (out of scope for this specification) for determining the event target. When the provided method's argument does not match any of the active pointers, throw a "NotFoundError" DOMException.

### Method
releasePointerCapture

### Parameters
- **pointerId** (long) - Required - The identifier of the pointer for which to release pointer capture.

### Exceptions
- **NotFoundError** - Thrown when the provided method's argument does not match any of the active pointers.

```

```APIDOC
## hasPointerCapture(pointerId)

### Description
Indicates whether the element on which this method is invoked has pointer capture for the pointer identified by the argument `pointerId`. In particular, returns `true` if the pending pointer capture target override for `pointerId` is set to the element on which this method is invoked, and `false` otherwise. This method will return true immediately after a call to `setPointerCapture()`, even though that element will not yet have received a `gotpointercapture` event. As a result it can be useful for detecting implicit pointer capture from inside of a `pointerdown` event listener.

### Method
hasPointerCapture

### Parameters
- **pointerId** (long) - Required - The identifier of the pointer to check for pointer capture.

### Returns
- **boolean** - `true` if the element has pointer capture for the pointer, `false` otherwise.

```

--------------------------------

### PointerEvent constructor

Source: https://www.w3.org/TR/pointerevents3

The PointerEvent constructor allows creating a new PointerEvent instance.

```APIDOC
## PointerEvent constructor

### Description
Creates a new PointerEvent object with the specified type and initialization dictionary.

### Method
constructor

### Parameters
- **type** (DOMString) - Required - The type of the event.
- **eventInitDict** (PointerEventInit) - Optional - Initialization options for the event.
```

--------------------------------

### getCoalescedEvents()

Source: https://www.w3.org/TR/pointerevents3

The getCoalescedEvents() method returns a sequence of PointerEvent objects that were coalesced into the current event, providing more detailed input data.

```APIDOC
## [Method] getCoalescedEvents

### Description
Returns a sequence of coalesced PointerEvent objects that were coalesced into the current event.

### Method
GET

### Endpoint
pointerEvent.getCoalescedEvents()

### Parameters
None.

### Response
#### Success Response
Returns a sequence of PointerEvent objects.

#### Response Example
```js
[PointerEvent, PointerEvent, ...]
```
```

--------------------------------

### PointerEvent.getCoalescedEvents()

Source: https://www.w3.org/TR/pointerevents3

The getCoalescedEvents() method returns the coalesced events associated with the pointer event.

```APIDOC
## PointerEvent.getCoalescedEvents()

### Description
Returns a sequence of coalesced PointerEvent objects that were not dispatched as separate events.

### Method
getCoalescedEvents

### Parameters
None.

### Return Value
sequence<PointerEvent> - A list of coalesced events.
```

--------------------------------

### Pointer Capture Methods

Source: https://www.w3.org/TR/pointerevents3

Pointer capture methods for retargeting pointer events to a specific element.

```APIDOC
## setPointerCapture(pointerId)

### Description
Sets pointer capture for the specified pointer on the element, retargeting all subsequent pointer events (including compatibility mouse events) to this element.

### Method
setPointerCapture

### Parameters
- **pointerId** (long) - Required - The identifier of the active pointer to capture.

### Exceptions
- **NotFoundError** - Thrown if the pointerId does not match any active pointer.
- **InvalidStateError** - Thrown if the element is not connected or if the document has a locked element.

### Behavior
- If the pointer is not in the active buttons state or the document is not active, the capture is not set.
- Sets the pending pointer capture target override for the specified pointerId.
```

```APIDOC
## releasePointerCapture(pointerId)

### Description
Releases pointer capture for the specified pointer on the element, allowing events to be retargeted according to normal hit testing.

### Method
releasePointerCapture

### Parameters
- **pointerId** (long) - Required - The identifier of the active pointer to release.

### Exceptions
- **NotFoundError** - Thrown if the pointerId does not match any active pointer and the call is not an implicit release.

### Behavior
- If hasPointerCapture is false for the element, the method does nothing.
- Clears the pending pointer capture target override for the specified pointerId.
```

--------------------------------

### PointerEvent Interface

Source: https://www.w3.org/TR/pointerevents3

Documentation for the PointerEvent interface properties and methods as defined in the Pointer Events Level 3 specification.

```APIDOC
## PointerEvent Interface

### Description
The PointerEvent interface extends the standard event interface to provide information about pointer input devices such as mouse, pen, touch, and other pointing devices. This documentation covers the properties and methods defined in the Pointer Events Level 3 specification.

### Properties

#### tangentialPressure
- **Type**: double
- **Range**: [-1, 1]
- **Default**: 0
- **Description**: The normalized tangential pressure (also known as barrel pressure), typically set by an additional control (e.g., a finger wheel on an airbrush stylus). Some hardware may only support positive values in [0, 1]. For hardware that does not support tangential pressure, the value MUST be 0.

#### tiltX
- **Type**: double
- **Range**: [-90, 90] degrees
- **Default**: 0
- **Description**: The plane angle between the Y-Z plane and the plane containing both the transducer axis and the Y axis. A positive tiltX is to the right. For hardware that does not report tilt, the value MUST be 0.

#### tiltY
- **Type**: double
- **Range**: [-90, 90] degrees
- **Default**: 0
- **Description**: The plane angle between the X-Z plane and the plane containing both the transducer axis and the X axis. A positive tiltY is towards the user. For hardware that does not report tilt, the value MUST be 0.

#### twist
- **Type**: double
- **Range**: [0, 359] degrees
- **Default**: 0
- **Description**: The clockwise rotation of a transducer around its own major axis. For hardware that does not report twist, the value MUST be 0.

#### altitudeAngle
- **Type**: double
- **Range**: [0, π/2] radians
- **Default**: π/2
- **Description**: The altitude of the transducer, where 0 is parallel to the surface and π/2 is perpendicular. For hardware that does not report tilt, the value MUST be π/2.

#### azimuthAngle
- **Type**: double
- **Range**: [0, 2π] radians
- **Default**: 0
- **Description**: The azimuth angle of the transducer, where 0 represents the cap pointing in the direction of increasing X values. When the transducer is perpendicular, the value MUST be 0. For hardware that does not report tilt, the value MUST be 0.

#### pointerType
- **Type**: string
- **Values**: "mouse", "pen", "touch", or empty string
- **Description**: Indicates the device type that caused the event. If the device type cannot be detected, the value MUST be an empty string. Vendor-prefixed values SHOULD be used for other device types.

#### isPrimary
- **Type**: boolean
- **Description**: Indicates if the pointer represents the primary pointer of this pointer type.

### Methods

#### getCoalescedEvents()
- **Returns**: Array of PointerEvent objects
- **Description**: Returns the list of coalesced events for the pointer event.
```

--------------------------------

### PointerEvent constructor

Source: https://www.w3.org/TR/pointerevents3

The PointerEvent constructor creates a new PointerEvent instance with the specified type and optional initialization dictionary.

```APIDOC
## [Constructor] PointerEvent

### Description
Creates a new PointerEvent object with the given type and optional initialization dictionary.

### Method
Constructor

### Endpoint
new PointerEvent(type, eventInitDict)

### Parameters
#### Constructor Parameters
- **type** (DOMString) - Required - The type of the pointer event.
- **eventInitDict** (PointerEventInit) - Optional - Initialization dictionary with default values.

### Request Example
```js
const event = new PointerEvent('pointerdown', { pointerId: 1, width: 10, height: 10 });
```

### Response
#### Success Response
Returns a new PointerEvent object.

#### Response Example
```js
PointerEvent { isTrusted: false, pointerId: 1, width: 10, height: 10, ... }
```
```

--------------------------------

### GlobalEventHandlers mixin extensions

Source: https://www.w3.org/TR/pointerevents3

This snippet documents the WebIDL extensions to the GlobalEventHandlers mixin, listing all the event handler attributes for pointer events.

```APIDOC
## [WebIDL] GlobalEventHandlers mixin extensions

### Description
Extensions to the GlobalEventHandlers mixin to facilitate event handler registration for pointer events.

### Interface
partial interface mixin GlobalEventHandlers

### Attributes
- **onpointerover** (EventHandler) - Event handler IDL attribute for the `pointerover` event type.
- **onpointerenter** (EventHandler) - Event handler IDL attribute for the `pointerenter` event type.
- **onpointerdown** (EventHandler) - Event handler IDL attribute for the `pointerdown` event type.
- **onpointermove** (EventHandler) - Event handler IDL attribute for the `pointermove` event type.
- **onpointerrawupdate** (EventHandler) - [SecureContext] Event handler IDL attribute for the `pointerrawupdate` event type.
- **onpointerup** (EventHandler) - Event handler IDL attribute for the `pointerup` event type.
- **onpointercancel** (EventHandler) - Event handler IDL attribute for the `pointercancel` event type.
- **onpointerout** (EventHandler) - Event handler IDL attribute for the `pointerout` event type.
- **onpointerleave** (EventHandler) - Event handler IDL attribute for the `pointerleave` event type.
- **ongotpointercapture** (EventHandler) - Event handler IDL attribute for the `gotpointercapture` event type.
- **onlostpointercapture** (EventHandler) - Event handler IDL attribute for the `lostpointercapture` event type.

### Example
```webidl
partial interface mixin GlobalEventHandlers {
    attribute EventHandler onpointerover;
    attribute EventHandler onpointerenter;
    attribute EventHandler onpointerdown;
    attribute EventHandler onpointermove;
    [SecureContext] attribute EventHandler onpointerrawupdate;
    attribute EventHandler onpointerup;
    attribute EventHandler onpointercancel;
    attribute EventHandler onpointerout;
    attribute EventHandler onpointerleave;
    attribute EventHandler ongotpointercapture;
    attribute EventHandler onlostpointercapture;
};
```
```

--------------------------------

### Intermediate parent disallowing direct manipulation with conflicting pan values

Source: https://www.w3.org/TR/pointerevents3

Demonstrates an intermediate parent with touch-action: pan-y and a child with touch-action: pan-x inside a scrollable container. Because the child allows only horizontal panning but an ancestor allows only vertical, no panning/zooming is handled by the user agent, so the child receives all pointer events.

```html
<div style="overflow: auto;">
    <div style="touch-action: pan-y;">
        <div style="touch-action: pan-x;">
            This element receives pointer events for all direct manipulation interactions because
            it allows only horizontal panning yet an intermediate ancestor
            (between it and the scrollable element) only allows vertical panning.
            Therefore, no direct manipulation behaviors for panning/zooming are
            handled by the user agent.
        </div>
    </div>
</div>
```

--------------------------------

### Convert between tiltX/tiltY and altitudeAngle/azimuthAngle

Source: https://www.w3.org/TR/pointerevents3

Provides two functions to convert between tiltX/tiltY and altitudeAngle/azimuthAngle. spherical2tilt converts from spherical coordinates to tilt values, handling boundary cases when altitudeAngle is 0. tilt2spherical converts from tilt values to spherical coordinates, handling boundary cases and returning azimuthAngle and altitudeAngle in radians.

```javascript
/* 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};
}
```

--------------------------------

### PointerEventInit dictionary

Source: https://www.w3.org/TR/pointerevents3

The PointerEventInit dictionary is used to configure a PointerEvent when it is constructed.

```APIDOC
## PointerEventInit dictionary

### Description
Defines the initialization options for a PointerEvent object.

### Members
- **pointerId** (long) - Optional - The unique identifier of the pointer.
- **width** (double) - Optional - The width of the pointer's contact geometry.
- **height** (double) - Optional - The height of the pointer's contact geometry.
- **pressure** (float) - Optional - The normalized pressure of the pointer.
- **tangentialPressure** (float) - Optional - The normalized tangential pressure.
- **tiltX** (long) - Optional - The plane angle between the Y-Z plane and the plane containing the pointer.
- **tiltY** (long) - Optional - The plane angle between the X-Z plane and the plane containing the pointer.
- **twist** (long) - Optional - The clockwise rotation of the pointer around its main axis.
- **altitudeAngle** (double) - Optional - The angle between the pointer's axis and the X-Y plane.
- **azimuthAngle** (double) - Optional - The angle between the pointer's projection on the X-Y plane and the X axis.
- **pointerType** (DOMString) - Optional - The type of pointer (e.g., mouse, pen, touch).
- **isPrimary** (boolean) - Optional - Indicates whether the pointer is the primary pointer.
- **coalescedEvents** (sequence<PointerEvent>) - Optional - A list of coalesced events.
- **predictedEvents** (sequence<PointerEvent>) - Optional - A list of predicted events.
```
Tokens:
Raw