recursal/MDN huggingface dataset:
PointerEvent: getCoalescedEvents() method
=========================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

 The **`getCoalescedEvents()`** method of the `PointerEvent` interface returns a sequence of `PointerEvent` instances that were coalesced (merged) into a single `pointermove` or `pointerrawupdate` event.
 Instead of a stream of many `pointermove` events, user agents coalesce multiple updates into a single event.
 This helps with performance as the user agent has less event handling to perform, but there is a reduction in the granularity and accuracy when tracking, especially with fast and large movements.

 The **`getCoalescedEvents()`** method lets applications access all un-coalesced position changes for precise handling of pointer movement data where necessary.
 Un-coalesced position changes are desirable in drawing applications, for instance, where having access to all events helps to build smoother curves that better match the movement of a pointer.

For an illustration of coalesced events, see Figure 7 in the specification.

Syntax
------


```js
getCoalescedEvents()
```

### Parameters

None.

### Return value

A sequence of `PointerEvent` instances.

Example
-------

### HTML


```html
<canvas id="target" width="600" height="300"></canvas>
```

### JavaScript


```js
const canvas = document.getElementById("target");
const ctx = canvas.getContext("2d");

const pointerEvents = [];

function drawCircle(x, y, color) {
  ctx.clearRect(0, 0, canvas.width, canvas.height);

  // draw the last 20 events
  if (pointerEvents.length > 20) {
    pointerEvents.shift();
  }
  pointerEvents.push({ x, y, color });

  for (const pointerEvent of pointerEvents) {
    ctx.beginPath();
    ctx.arc(pointerEvent.x, pointerEvent.y, 10, 0, 2 \* Math.PI);
    ctx.strokeStyle = pointerEvent.color;
    ctx.stroke();
  }
}

canvas.addEventListener("pointermove", (e) => {
  // draw a circle for the current event
  drawCircle(e.clientX, e.clientY, "black");

  const coalescedEvents = e.getCoalescedEvents();
  for (let coalescedEvent of coalescedEvents) {
    // give it an offset so we can see the difference and color it red
    drawCircle(coalescedEvent.clientX + 20, coalescedEvent.clientY + 20, "red");
  }
});
```

### Result

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-getcoalescedevents |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: isPrimary property
================================

 The **`isPrimary`** read-only property of the
 `PointerEvent` interface indicates whether or not the pointer device that
 created the event is the *primary* pointer. It returns `true` if the
 pointer that caused the event to be fired is the primary one and returns
 `false` otherwise.

 In a multi-pointer scenario (such as a touch screen that supports more than one touch
 point), this property is used to identify a *master pointer* among the set of
 active pointers for each pointer type. Only a primary pointer will produce
 *compatibility mouse events*. Authors who desire only single-pointer interaction
 can achieve that by ignoring non-primary pointers.

 A pointer is considered primary if the pointer represents a mouse device. A pointer
 representing pen input is considered the primary pen input if its
 `pointerdown` event was dispatched when no other active pointers representing
 pen input existed. A pointer representing touch input is considered the primary touch
 input if its `pointerdown` event was dispatched when no other active pointers
 representing touch input existed.

 When two or more pointer device types are being used concurrently, multiple pointers
 (one for each `pointerType`) are considered
 primary. For example, a touch contact and a mouse cursor moved simultaneously will
 produce pointers that are both considered primary. If there are multiple primary
 pointers, these pointers will all produce *compatibility mouse events* (see
 `Pointer_events` for more information about pointer, mouse and touch
 interaction).

Value
-----

A boolean, `true` if the pointer for this event is the primary pointer and returns `false` otherwise.

Examples
--------

 This example illustrates using the value of `isPrimary` to call the
 appropriate processing function.


```js
target.addEventListener(
  "pointerdown",
  (event) => {
    if (event.isPrimary) {
      process\_primary\_pointer(event);
    } else {
      process\_secondary\_pointer(event);
    }
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-isprimary |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: PointerEvent() constructor
========================================

 The **`PointerEvent()`** constructor creates a new synthetic
 and untrusted `PointerEvent` object instance.

Syntax
------


```js
new PointerEvent(type)
new PointerEvent(type, options)
```

### Parameters

`type`

 A string representing the name of the event
 (see PointerEvent event types).


`options` Optional

An object that, *in addition of the properties defined in `MouseEvent()`*, can have the following properties:

`pointerId`

A number, defaulting to `0`, that sets the value of the instance's `PointerEvent.pointerId`.

`width`

A number,, defaulting to `1`, that sets the value of the instance's `PointerEvent.width`.

`height`

A number,, defaulting to `1`, that sets the value of the instance's `PointerEvent.height`.

`pressure`

A number, defaulting to `0`, that sets the value of the instance's `PointerEvent.pressure`.

`tangentialPressure`

A number, defaulting to `0`, that sets the value of the instance's `PointerEvent.tangentialPressure`.

`tiltX`

A number, defaulting to `0`, that sets the value of the instance's `PointerEvent.tiltX`.

`tiltY`

A number, defaulting to `0`, that sets the value of the instance's `PointerEvent.tiltY`.

`twist`

A number, defaulting to `0`, that sets the value of the instance's `PointerEvent.twist`.

`pointerType`

A string, defaulting to `""` that sets the value of the instance's `PointerEvent.pointerType`.

`isPrimary`

A boolean value, defaulting to `false` that sets the value of the instance's `PointerEvent.isPrimary`.


### Return value

A new `PointerEvent` object.

Examples
--------


```js
const moveEvent = new PointerEvent("pointermove");

const downEvent = new PointerEvent("pointerdown", {
  pointerId: 1,
  bubbles: true,
  cancelable: true,
  pointerType: "touch",
  width: 100,
  height: 100,
  isPrimary: true,
});
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-constructor |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: twist property
============================

 The **`twist`** read-only property of the
 `PointerEvent` interface represents the clockwise rotation of the pointer
 (e.g., pen stylus) around its major axis, in degrees.

Value
-----

 A `long` value representing the amount of twist, in degrees, applied to the
 transducer (pointer). The value is in the range `0` to `359`,
 inclusive. For devices that do not report `twist`, the value is
 `0`.

Examples
--------

 When a `pointerdown` event is fired, different functions are called
 depending on the value of the event's `twist` property.


```js
someElement.addEventListener(
  "pointerdown",
  (event) => {
    if (event.twist === 0) {
      // No twist
      process\_no\_twist(event);
    } else {
      // Default
      process\_twist(event);
    }
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-twist |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Touch.force`
PointerEvent: height property
=============================

 The **`height`** read-only property of the
 `PointerEvent` interface represents the height of the pointer's contact
 geometry, along the y-axis (in CSS pixels). Depending on the source of the pointer
 device (for example a finger), for a given pointer, each event may produce a different
 value.

 If the input hardware cannot report the contact geometry to the browser, the height
 defaults to `1`.

Value
-----

The height of the event's contact area (in CSS pixels).

Examples
--------

An example of this property is included in the PointerEvent.width example.

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-height |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: altitudeAngle property
====================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`altitudeAngle`** read-only property of the `PointerEvent` interface represents the angle between a transducer (a pointer or stylus) axis and the X-Y plane of a device screen.
 The altitude angle describes whether the transducer is perpendicular to the screen, parallel, or at some angle in between.

Depending on the specific hardware and platform, user agents will likely only receive one set of values for the transducer orientation relative to the screen plane — either `tiltX` and `tiltY` or `altitudeAngle` and `azimuthAngle`.

![The azimuth angle of a pointer compared to the altitude angle](/en-US/docs/Web/API/PointerEvent/altitudeAngle/azimuth_altitude_angles.svg)

For an additional illustration of this property, see Figure 4 in the specification.

Value
-----

 An angle in radians between `0` and `π/2` where `0` is parallel to the device surface (X-Y plane), and `π/2` is perpendicular to the surface.
 Defaults to `π/2` (perpendicular to the surface) which differs from the `altitudeAngle` in touch events which defaults to `0` (parallel to the surface).
 For hardware and platforms that do not report tilt or angle, the value is `π/2`.

Example
-------


```js
someElement.addEventListener(
  "pointerdown",
  (event) => {
    process\_angles(event.altitudeAngle, event.azimuthAngle);
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-altitudeangle |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `PointerEvent.azimuthAngle`
* `PointerEvent.tiltX`
* `PointerEvent.tiltY`
PointerEvent: tiltX property
============================

 The **`tiltX`** read-only property of the
 `PointerEvent` interface is the angle (in degrees) between the *Y-Z
plane* of the pointer and the screen. This property is typically only useful for a
 pen/stylus pointer type.

For an illustration of this property see Figure 2 in the specification.

Value
-----

The angle in degrees between the Y-Z plane of the pointer (stylus) and the screen. The range of values is `-90` to `90`, inclusive, where a positive value is a tilt to the right. For devices that do not support this property, the value is `0`.

Examples
--------

 This example illustrates simple accessing of the `tiltX` and
 `tiltY` properties.


```js
someElement.addEventListener(
  "pointerdown",
  (event) => {
    process\_tilt(event.tiltX, event.tiltY);
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-tiltx |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: pointerType property
==================================

 The **`pointerType`** read-only property of the
 `PointerEvent` interface indicates the device type (mouse, pen, or touch)
 that caused a given pointer event.

Value
-----

The event's pointer type. The supported values are the following strings:

`"mouse"`

The event was generated by a mouse device.

`"pen"`

The event was generated by a pen or stylus device.

`"touch"`

The event was generated by a touch, such as a finger.


 If the device type cannot be detected by the browser, the value can be an empty string
 (`""`). If the browser supports pointer device types other than those listed
 above, the value should be *vendor-prefixed* to avoid conflicting names for
 different types of devices.

Examples
--------

 This example illustrates using the value of the `pointerType` property to
 call the appropriate pointer type processing function.


```js
targetElement.addEventListener(
  "pointerdown",
  (event) => {
    // Call the appropriate pointer type handler
    switch (event.pointerType) {
      case "mouse":
        process\_pointer\_mouse(event);
        break;
      case "pen":
        process\_pointer\_pen(event);
        break;
      case "touch":
        process\_pointer\_touch(event);
        break;
      default:
        console.log(`pointerType ${event.pointerType} is not supported`);
    }
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-pointertype |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: tiltY property
============================

 The **`tiltY`** read-only property of the
 `PointerEvent` interface is the angle (in degrees) between the *X-Z
plane* of the pointer and the screen. This property is typically only useful for a
 pen/stylus pointer type.

For an illustration of this property, see Figure 3 in the specification.

Value
-----

The angle in degrees between the X-Z plane of the pointer (stylus) and the screen. The range of values is `-90` to `90`, inclusive, where a positive value is a tilt towards the user. For devices that do not support this property, the value is `0`.

Examples
--------

 This example illustrates simple accessing of the
 `tiltX` and `tiltY` properties.


```js
someElement.addEventListener(
  "pointerdown",
  (event) => {
    process\_tilt(event.tiltX, event.tiltY);
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-tilty |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: azimuthAngle property
===================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`azimuthAngle`** read-only property of the `PointerEvent` interface represents the angle between the Y-Z plane and the plane containing both the transducer (pointer or stylus) axis and the Y axis.

Depending on the specific hardware and platform, user agents will likely only receive one set of values for the transducer orientation relative to the screen plane — either `tiltX` and `tiltY` or `altitudeAngle` and `azimuthAngle`.

![The azimuth angle of a pointer compared to the altitude angle](/en-US/docs/Web/API/PointerEvent/azimuthAngle/azimuth_altitude_angles.svg)

For an additional illustration of this property, see Figure 5 in the specification.

Value
-----

An angle in radians between `0` and `2π` where `0` represents a transducer whose cap is pointing in the direction of increasing X values (point to "3 o'clock" if looking straight down) on the X-Y plane, and the values progressively increase when going clockwise (`π/2` at "6 o'clock", `π` at "9 o'clock", `3π/2` at "12 o'clock").

 When the transducer is perpendicular to the surface (`altitudeAngle` of `π/2`), the value is 0.
 For hardware and platforms that do not report tilt or angle, the value is `0`.

Example
-------


```js
someElement.addEventListener(
  "pointerdown",
  (event) => {
    process\_angles(event.altitudeAngle, event.azimuthAngle);
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-azimuthangle |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `PointerEvent.altitudeAngle`
* `PointerEvent.tiltX`
* `PointerEvent.tiltY`
PointerEvent: pressure property
===============================

 The **`pressure`** read-only property of the
 `PointerEvent` interface indicates the normalized pressure of the pointer
 input.

Value
-----

The normalized pressure of the pointer input in the range of `0` to `1`, inclusive, where `0` and `1` represent the minimum and maximum pressure the hardware is capable of detecting, respectively. For hardware that does not support pressure, such as a mouse, the value is `0.5` when the pointer is active buttons state and `0` otherwise.

Examples
--------

 In this snippet, when a `pointerdown` event is fired, different functions
 are called depending on the value of the event's `pressure` property.


```js
someElement.addEventListener(
  "pointerdown",
  (event) => {
    if (event.pressure === 0) {
      // No pressure
      process\_no\_pressure(event);
    } else if (event.pressure === 1) {
      // Maximum pressure
      process\_max\_pressure(event);
    } else {
      // Default
      process\_pressure(event);
    }
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-pressure |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Touch.force`
PointerEvent: getPredictedEvents() method
=========================================

 The **`getPredictedEvents()`** method of the `PointerEvent` interface returns a sequence of `PointerEvent` instances that are estimated future pointer positions.
 How the predicted positions are calculated depends on the user agent, but they are based on past points, current velocity, and trajectory.

Applications can use the predicted events to "draw ahead" to a predicted position which may reduce perceived latency depending on the application's interpretation of the predicted events and the use case.

For an illustration of predicted events, see Figure 8 in the specification.

Syntax
------


```js
getPredictedEvents()
```

### Parameters

None.

### Return value

A sequence of `PointerEvent` instances.

Example
-------

### HTML


```html
<canvas id="target" width="600" height="300"></canvas>
```

### JavaScript


```js
const canvas = document.getElementById("target");
const ctx = canvas.getContext("2d");

const pointerEvents = [];

function drawCircle(x, y, color) {
  ctx.clearRect(0, 0, canvas.width, canvas.height);

  // draw the last 20 events
  if (pointerEvents.length > 20) {
    pointerEvents.shift();
  }
  pointerEvents.push({ x, y, color });

  for (const pointerEvent of pointerEvents) {
    ctx.beginPath();
    ctx.arc(pointerEvent.x, pointerEvent.y, 10, 0, 2 \* Math.PI);
    ctx.strokeStyle = pointerEvent.color;
    ctx.stroke();
  }
}

canvas.addEventListener("pointermove", (e) => {
  // draw a circle for the current event
  drawCircle(e.clientX, e.clientY, "black");

  const predictedEvents = e.getPredictedEvents();
  for (let predictedEvent of predictedEvents) {
    // give it an offset so we can see the difference and color it red
    drawCircle(predictedEvent.clientX + 20, predictedEvent.clientY + 20, "red");
  }
});
```

### Result

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-getpredictedevents |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: width property
============================

 The **`width`** read-only property of the
 `PointerEvent` interface represents the width of the pointer's contact
 geometry along the x-axis, measured in CSS pixels. Depending on the source of the
 pointer device (such as a finger), for a given pointer, each event may produce a
 different value.

 If the input hardware cannot report the contact geometry to the browser, the width
 defaults to `1`.

Value
-----

The width of the event's contact area (in CSS pixels).

Examples
--------

 This example illustrates using the `PointerEvent` interface's
 `width` and
 `height` properties to calculate the contact area.


```js
target.addEventListener(
  "pointerdown",
  (ev) => {
    // Calculate the contact area
    const area = ev.width \* ev.height;
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-width |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PointerEvent: tangentialPressure property
=========================================

 The **`tangentialPressure`** read-only property of the
 `PointerEvent` interface represents the normalized tangential pressure of
 the pointer input (also known as barrel pressure or cylinder stress).

Value
-----

 A `float` representing the normalized tangential pressure of the pointer
 input in the range `-1` to `1`, inclusive, where `0` is
 the neutral position of the control.

 Note that some hardware may only support positive values in the range `0` to
 `1`. For hardware that does not support tangential pressure, the value will
 be `0`.

Examples
--------

 In this snippet, when a `pointerdown` event is fired, different functions
 are called depending on the value of the event's `tangentialPressure`
 property.


```js
someElement.addEventListener(
  "pointerdown",
  (event) => {
    if (event.tangentialPressure === 0) {
      // No pressure
      process\_no\_tanPressure(event);
    } else if (event.tangentialPressure === 1) {
      // Maximum pressure
      process\_max\_tanPressure(event);
    } else {
      // Default
      process\_tanPressure(event);
    }
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-tangentialpressure |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Touch.force`
PointerEvent: pointerId property
================================

 The **`pointerId`** read-only property of the
 `PointerEvent` interface is an identifier assigned to a given pointer
 event. The identifier is unique, being different from the identifiers of all other
 active pointer events. Since the value may be randomly generated, it is not guaranteed
 to convey any particular meaning.

Value
-----

A number.

Examples
--------

 The following code snippet compares a previously saved `pointerId` with the
 one of the `pointerdown` event that was just fired.


```js
let id; // Let's assume that this is a previously saved pointerId

target.addEventListener(
  "pointerdown",
  (event) => {
    // Compare previous event's ID that was cached
    // to current event's ID and handle accordingly
    if (id === event.pointerId) process\_event(event);
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| Pointer Events # dom-pointerevent-pointerid |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.