setPointerCapture method

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.

Note  As of Internet Explorer 11, the Microsoft vendor prefixed version of this method (msSetPointerCapture) is no longer supported and may be removed in a future release. Instead, use the non-prefixed lowercase name, setPointerCapture, which is better for standards compliance and future compatibility.

Internet Explorer 10

 

Syntax

object.setPointerCapture(pointerId)

Parameters

pointerId [in]

Type: Integer

The pointer to assign to the element.

Return value

This method does not return a value.

Remarks

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 (pointerup) 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.

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.

See also

Element
PointerEvent
Pointer Events
releasePointerCapture

 

 

Show:
© 2014 Microsoft