setPointerCapture

Summary

Assigns a specified pointer to an element. This method is used to ensure that an element continues to receive pointer events even if the contact moves off the element.

Method of dom/Element dom/Element

Syntax

 element.setPointerCapture(pointerID);

Parameters

pointerID

Data-type: Number

The pointer to assign to the element.

Return Value

No return value

Usage

 Capturing the current pointer can improve usability by reducing the touch precision required when interacting with an element. For example, if a button is touched and held, and the user's finger slides off the button before raising it (breaking the contact), the button might not receive the pointerup event. This could cause the button to stay depressed forever. By assigning the pointer to the button element with setPointerCapture, the button receives pointer events, including the pointerup event that signals the button to return to its initial state.

The capture will be released when the pointer is removed (onpointerup) or explicitly released by calling the releasePointerCapture method. There are cases the element could lose the capture. For example, if the touch moves outside the window or some other element captures the touch, then the element that had the capture will lose the capture. The element that lost the capture will receive a lostpointercapture event.

Notes

When a pointer is captured to an element, the parent and ancestor elements receive a gotpointercapture event during capture and bubble phase.

If the specified pointerId does not match any existing pointers, a DOMException is thrown with the name InvalidPointerId.

Related specifications

Pointer Events: Working Draft

Attributions

Microsoft Developer Network: Article