Pointer Events (original) (raw)

Abstract

This document defines events and related interfaces for handling hardware agnostic pointer input from devices like a mouse, pen, or touchscreen. For compatibility with existing mouse-based content, this specification also describes a mapping to fire [DOM-LEVEL-3-EVENTS] Mouse Events for pointer device types other than mouse.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Current bugs and issues are managed in Bugzilla. Action items to be completed are tracked in Tracker. Feature requests for the next version of this specification are kept in thePointer Events Use Cases and Requirements wiki.

A Last Call Working Draft (LCWD) of the specification was published on19 February 2013. A comment tracking document for this LCWD is available. Changes to this specification since the LCWD was published are summarized and enumerated in this document's Revision History Appendix.

During the Candidate Recommendation period, which ends 09 August 2013, the WG will complete its test suite. Before this specification exits Candidate Recommendation, two or more independent implementations must pass each test, although no single implementation must pass each test. The group will also create an Implementation Report.

This document was published by the Pointer Events Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-pointer-events@w3.org (subscribe,archives).W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. All comments are welcome.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy.W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes containsEssential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

Today, most [HTML5] content is used with and/or designed for mouse input. Those that handle input in a custom manner typically code to [DOM-LEVEL-3-EVENTS] Mouse Events. Newer computing devices today, however, incorporate other forms of input, like touchscreens or pen input. Event types have been proposed for handling each of these forms of input individually. However, that approach requires a step function in opportunity cost to authors when adding support for a new input type. This often creates a compatibility problem when content is written with only one device type in mind. Additionally, for compatibility with existing mouse-based content, most user agents fire Mouse Events for all input types. This makes it ambiguous whether a Mouse Event represents an actual mouse device or is being produced from another input type for compatibility, which makes it hard to code to both device types simultaneously.

To reduce the cost of coding to multiple input types and also to help with the above described ambiguity with Mouse Events, this specifications defines a more abstract form of input, called a pointer. A pointer can be any point of contact on the screen made by a mouse cursor, pen, touch (including multi-touch), or other pointing input device. This model makes it easier to write sites and applications that work well no matter what hardware the user has. For scenarios when device-specific handling is desired, this specification also defines properties for inspecting the device type which produced the event. The primary goal is to provide a single set of events and interfaces that allow for easier authoring for cross-device pointer input while still allowing for device-specific handling when necessary. An additional key goal is to enable multi-threaded user agents to handle default touch actions, such as scrolling, without blocking on script execution.

Pointer input combines input from mouse, pen, touch, etc.

Fig. 1 A pointer is a hardware agnostic representation of input devices that can target a specific coordinate (or set of coordinates) on a screen.

The events for handling generic pointer input look a lot like those for mouse: pointerdown, pointermove, pointerup, pointerover, pointerout, etc. This facilitates easy content migration from Mouse Events to Pointer Events. Pointer Events provide all the usual properties present in Mouse Events (client coordinates, target element, button states, etc.) in addition to new properties for other forms of input: pressure, contact geometry, tilt, etc. So authors can easily code to Pointer Events to share logic between different input types where it makes sense, and customize for a particular type of input only where necessary to get the best experience.

While Pointer Events are sourced from a variety of input devices, they are not defined as being generated from some other set of device-specific events. While possible and encouraged for compatibility, this spec does not require other device-specific events be supported (e.g. mouse events, touch events, etc.). A user agent could support pointer events without supporting any other device events. For compatibility with content written to mouse-specific events, this specification does provide an optional section describing how to generate compatibility mouse events based on pointer input from devices other than a mouse.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

3. Examples

This section is non-normative.

The following are example author code that demonstrates how the APIs in this specification might be used.

Example 1: Basic HTML5 Canvas painting application

Example 2: Detecting the type of input from a user

window.addEventListener("pointerdown", detectInputType, false); function detectInputType(event) { switch(event.pointerType) { case "mouse": alert("You used a mouse!"); break; case "pen": alert("You used a pen stylus!"); break; case "touch": alert("You used touch!"); break; default: alert("Not sure what device was used!"); } }

Example 3: Resizing an element to match the contact geometry

Example 4: Dispatching an untrusted pointer event

var event = new PointerEvent("pointerover", {bubbles: true, cancelable: true, pointerId: 42, pointerType: "pen", clientX: 300, clientY: 500 }); eventTarget.dispatchEvent(event);

4. Glossary

This section is non-normative.

active buttons state

The condition when a pointer has a non-zero value for the buttons property. For mouse, this is when the device has at least one button depressed. For touch, this is when there is physical contact with the digitizer. For pen, this is when the pen has physical contact with the digitizer.

active pointer

Any touch contact, pen stylus, mouse cursor, or other pointer that can produce events. If it is possible for a given pointer (identified by a unique pointerId) to produce additional events, then that pointer is still considered active. Examples:

Note

In some platforms, the set of active pointers includes all pointer input to the device, including any that are not targeted at the user agent (e.g. another application).

cancelled event

An event whose default action was prevented by means of preventDefault(), returning false in an event handler, or other means as defined by [DOM-LEVEL-3-EVENTS] and [HTML5].

contact geometry

The bounding box of an input (most commonly, touch) on a digitizer. This typically refers to devices with coarser pointer input resolution than a single pixel. Some devices do not report this data at all.

digitizer

A type of input sensing device in which a surface can detect input which is in contact and/or in close proximity. Most commonly, this is the surface that sense input from touch contact or a pen stylus.

hit test

The process by which a user agent determines a target element for a pointer event. Typically, this is determined by considering the pointer's location and also the visual layout of elements in a document on screen media.

pointer

A hardware agnostic representation of input devices that can target a specific coordinate (or set of coordinates) on a screen, such as a mouse, pen, or touch contact.

user agent

A program, such as a browser or content authoring tool, normally running on a client machine, which acts on a user's behalf in retrieving, interpreting, executing, presenting, or creating content.

5. Pointer Events and Interfaces

5.1 PointerEvent Interface

dictionary PointerEventInit : MouseEventInit { long pointerId = 0; long width = 0; long height = 0; float pressure = 0; long tiltX = 0; long tiltY = 0; DOMString pointerType = ""; boolean isPrimary = false; };

[Constructor(DOMString type, optional PointerEventInit eventInitDict)] interface PointerEvent : MouseEvent { readonly attribute long pointerId; readonly attribute long width; readonly attribute long height; readonly attribute float pressure; readonly attribute long tiltX; readonly attribute long tiltY; readonly attribute DOMString pointerType; readonly attribute boolean isPrimary; };

Attributes

pointerId of type long, readonly

A unique identifier for the pointer causing the event. This identifier MUST be unique from all other active pointers at the time. A user agent MAY recycle previously retired values for pointerId from previous active pointers, if necessary.

Note

The pointerId selection algorithm is implementation specific. Therefore authors cannot assume values convey any particular meaning other than an identifier for the pointer that is unique from all other active pointers. As an example, values are not guaranteed to be monotonically increasing.

width of type long, readonly

The width (magnitude on the X axis), in CSS pixels (see [CSS21]), of the contact geometry of the pointer. This value MAY be updated on each event for a given pointer. For devices which have a contact geometry but the actual geometry is not reported by the hardware, a default value SHOULD be provided by the user agent to approximate the geometry typical of that pointer type. Otherwise, the value MUST be 0.

height of type long, readonly

The height (magnitude on the Y axis), in CSS pixels (see [CSS21]), of the contact geometry of the pointer. This value MAY be updated on each event for a given pointer. For devices which have a contact geometry but the actual geometry is not reported by the hardware, a default value SHOULD be provided by the user agent to approximate the geometry typical of that pointer type. Otherwise, the value MUST be 0.

pressure of type float, readonly

The normalized pressure of the pointer input in the range of [0,1], where 0 and 1 represent the minimum and maximum pressure the hardware is capable of detecting, respectively. For hardware that does not support pressure, including but not limited to mouse, the value MUST be 0.5 when in the active buttons state and 0 otherwise.

tiltX of type long, readonly

The plane angle (in degrees, in the range of [-90,90]) between the Y-Z plane and the plane containing both the transducer (e.g. pen stylus) axis and the Y axis. A positive tiltX is to the right. tiltX can be used along with tiltY to represent the tilt away from the normal of a transducer with the digitizer. For devices that do not report tilt, the value MUST be 0.

tiltX explanation diagram

Fig. 2 Positive tiltX.

tiltY of type long, readonly

The plane angle (in degrees, in the range of [-90,90]) between the X-Z plane and the plane containing both the transducer (e.g. pen stylus) axis and the X axis. A positive tiltY is towards the user. tiltY can be used along with tiltX to represent the tilt away from the normal of a transducer with the digitizer. For devices that do not report tilt, the value MUST be 0.

tiltY explanation diagram

Fig. 3 Negative tiltY.

pointerType of type DOMString, readonly

Indicates the device type that caused the event (mouse, pen, touch, etc.). If a user agent is to fire a pointer event for a mouse, pen stylus, or touch input device, then the value of pointerType MUST be according to the following table:

Pointer Device Type pointerType Value
Mouse mouse
Pen Stylus pen
Touch Contact touch

If the device type cannot be detected by the user agent, then the value MUST be an empty string. If a user agent supports pointer device types other than those listed above, the value of pointerType SHOULD be vendor prefixed to avoid conflicting names for different types of devices. Future specifications MAY provide additional normative values for other device types.

Note

See the examples in the appendix for sample code.

isPrimary of type boolean, readonly

Indicates if the pointer represents the primary pointer of this pointer type.

Dictionary PointerEventInit Members

pointerId of type long, defaulting to 0

Initializes the pointerId property of the PointerEvent object.

width of type long, defaulting to 0

Initializes the width property of the PointerEvent object.

height of type long, defaulting to 0

Initializes the height property of the PointerEvent object.

pressure of type float, defaulting to 0

Initializes the pressure property of the PointerEvent object.

tiltX of type long, defaulting to 0

Initializes the tiltX property of the PointerEvent object.

tiltY of type long, defaulting to 0

Initializes the tiltY property of the PointerEvent object.

pointerType of type DOMString, defaulting to ""

Initializes the pointerType property of the PointerEvent object.

isPrimary of type boolean, defaulting to false

Initializes the isPrimary property of the PointerEvent object.

The PointerEventInit dictionary is used by the PointerEvent interface's constructor to provide a mechanism by which to construct untrusted (synthetic) pointer events. It inherits from the MouseEventInit dictionary defined in [UI-EVENTS]. See the examples for sample code demonstrating how to dispatch an untrusted pointer event.

5.1.1 Button States

5.1.1.1 Chorded Button Interactions

Some pointer devices, such as mouse or pen, support multiple buttons. In the [DOM-LEVEL-3-EVENTS] Mouse Event model, each button press produces a mousedown and mouseup event. To better abstract this hardware difference and simplify cross-device input authoring, Pointer Events do not fire overlapping pointerdown and pointerup events for chorded button presses (depressing an additional button while another button on the pointer device is already depressed).

Instead, chorded button presses can be detected by inspecting changes to the button and buttons properties. The button and buttons properties are inherited from the [DOM-LEVEL-3-EVENTS] MouseEvent interface. In order to facilitate differentiating button state transitions in any pointer event (and not just pointerdown and pointerup), the button property takes on a new value when no mouse buttons are depressed:

Device Button State button buttons
Mouse move with no buttons pressed -1 0
Left Mouse,Touch Contact,Pen contact (with no modifier buttons pressed) 0 1
Middle Mouse 1 4
Right Mouse,Pen contact with barrel button pressed 2 2
X1 (back) Mouse 3 8
X2 (forward) Mouse 4 16
Pen contact with eraser button pressed 5 32

Note

These values only apply when firing pointer events. This specification does not alter the values of button or buttons used when firing mouse events. See [DOM-LEVEL-3-EVENTS] for the values when firing mouse events.

5.1.2 The Primary Pointer

In a multi-pointer (e.g. multi-touch) scenario, the isPrimary property is used to identify a master pointer amongst the set of active pointers for each pointer type. Only a primary pointer will produce compatibility mouse events. Authors who desire single-pointer interaction can achieve this by ignoring non-primary pointers.

Determining the primary pointer

When dispatching a pointer event, a pointer is considered primary if:

primary touch input

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.

primary pen input

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.

Note

When two or more pointer device types are being used concurrently, multiple pointers are considered primary. For example, a touch contact and a mouse cursor moved simultaneously will produce pointers that are both considered primary.

Note

In some platforms, the primary pointer is determined using all active pointers on the device, including those not targeted at the user agent (e.g. in another application). This means it is possible for the user agent to fire pointer events in which no pointer is marked as a primary pointer. For example, if the first touch interaction is targeted outside the user agent and a secondary (multi-touch) touch interaction is targeted inside the user agent, then the user agent may fire pointer events for the second contact with a value of false for isPrimary.

5.2 Pointer Event Types

5.2.1 List of Pointer Events

This section is non-normative.

The following table provides a summary of the event types defined in this specification.

Event Type Sync/Async Bubbles Cancellable Trusted proximal event target types Event object interface Default Action
pointerdown Sync Yes Yes Document, Element PointerEvent Varies: when the pointer is primary, all default actions of the mousedown event plus dispatch of compatibility mouse events
pointerup Sync Yes Yes Document, Element PointerEvent Varies: when the pointer is primary, all default actions of mouseup
pointercancel Sync Yes Yes Document, Element PointerEvent None
pointermove Sync Yes Yes Document, Element PointerEvent Varies: when the pointer is primary, all default actions of mousemove
pointerover Sync Yes Yes Document, Element PointerEvent Varies: when the pointer is primary, all default actions of mouseover
pointerout Sync Yes Yes Document, Element PointerEvent Varies: when the pointer is primary, all default actions of mouseout
pointerenter Sync No Yes Document, Element PointerEvent Varies: when the pointer is primary, all default actions of mouseenter
pointerleave Sync No Yes Document, Element PointerEvent Varies: when the pointer is primary, all default actions of mouseleave
gotpointercapture Async Yes No Element PointerEvent None
lostpointercapture Async Yes No Element PointerEvent None

5.2.2 The pointerdown event

A user agent MUST dispatch this event when a pointer enters the active buttons state. For mouse, this is when the device transitions from no buttons depressed to at least one button depressed. For touch, this is when physical contact is made with the digitizer. For pen, this is when the stylus makes physical contact with the digitizer.

For input devices that do not support hover, a user agent MUST also fire a pointerover event preceding the pointerdown event.

Authors can prevent the production of compatibility mouse events by cancelling the pointerdown event (if the isPrimary property is true).

Note

For mouse (or other multi-button pointer devices), this means pointerdown and pointerup are dispatched differently than mousedown and mouseup. See chorded buttons for more information.

5.2.3 The pointerup event

A user agent MUST dispatch this event when a pointer leaves the active buttons state. For mouse, this is when the device transitions from at least one button depressed to no buttons depressed. For touch, this is when physical contact is removed from the digitizer. For pen, this is when the pen is removed from physical contact with the digitizer.

For input devices that do not support hover, a user agent MUST also fire a pointerout event after firing the pointerup event.

Note

For mouse (or other multi-button pointer devices), this means pointerdown and pointerup are dispatched differently than mousedown and mouseup. See chorded buttons for more information.

5.2.4 The pointercancel event

A user agent MUST dispatch this event in the following circumstances:

A user agent MUST also fire a pointerout event after firing the pointercancel event.

Note

This section is non-normative.

Examples of scenarios in which a user agent might determine that a pointer is unlikely to continue to produce events include:

Methods for changing the device's screen orientation, recognizing accidental input, or using a pointer to manipulate the viewport (e.g. panning or zooming) are out of scope for this specification.

5.2.5 The pointermove event

A user agent MUST dispatch this event when a pointer changes coordinates, button state, pressure, tilt, or contact geometry (e.g. width and height).

5.2.6 The pointerover event

A user agent MUST dispatch this event when a pointing device is moved into the hit test boundaries of an element. A user agent MUST also dispatch this event prior to a pointerdown event for devices that do not support hover.

5.2.7 The pointerout event

A user agent MUST dispatch this event when any of the following occurs:

5.2.8 The pointerenter event

A user agent MUST dispatch this event when a pointing device is moved into the hit test boundaries of an element or one of its descendants, including as a result of a pointerdown event from a device that does not support hover. This event type is similar to pointerover, but differs in that it does not bubble.

Note

There are similarities between this event type, the mouseenter event described in [DOM-LEVEL-3-EVENTS], and the CSS :hover pseudo-class described in [CSS21]. See also the pointerleave event.

5.2.9 The pointerleave event

A user agent MUST dispatch this event when a pointing device is moved off of the hit test boundaries of an element and all of its descendants, including as a result of a pointerup event from a device that does not support hover. This event MUST also dispatch when a pen stylus leaves hover range detectable by the digitizer. This event type is similar to pointerout, but differs in that it does not bubble and that it MUST not be dispatched until the pointing device has left the boundaries of the element and the boundaries of all of its children.

Note

There are similarities between this event type, the mouseleave event described in [DOM-LEVEL-3-EVENTS], and the CSS :hover pseudo-class described in [CSS21]. See also the pointerenter event.

5.2.10 The gotpointercapture event

A user agent MUST asynchronously dispatch this event prior to dispatching the first event after pointer capture is set for a pointer. This event is dispatched to the element that is receiving pointer capture. Subsequent events for that pointer will be dispatched to this element. See setPointerCapture().

5.2.11 The lostpointercapture event

A user agent MUST asynchronously dispatch this event after pointer capture is released for a pointer. This event MUST be dispatched prior to any subsequent events for the pointer after capture was released. This event is dispatched to the element from which pointer capture was removed. Subsequent events for the pointer follow normal hit testing mechanisms (out of scope for this specification) for determining the event target. See releasePointerCapture().

6. Extensions to the Element interface

The following section describes extensions to the existing Element interface, defined in [HTML5], to facilitate the setting and releasing of pointer capture.

partial interface Element { attribute EventHandler ongotpointercapture; attribute EventHandler onlostpointercapture; void setPointerCapture (long pointerId); void releasePointerCapture (long pointerId); };

Attributes

ongotpointercapture of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the gotpointercapture event type.

onlostpointercapture of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the lostpointercapture event type.

Methods

setPointerCapture

Sets pointer capture for the pointer identified by the argument pointerId to the element on which this method is invoked. Subsequent events for the pointer MUST always be targeted at this element. Throws a DOMException with the name InvalidPointerId when the provided the method's argument does not match any of the active pointers.

Parameter Type Nullable Optional Description
pointerId long ✘ ✘

Return type: void

releasePointerCapture

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. Throws a DOMException with the name InvalidPointerId when the provided the method's argument does not match any of the active pointers.

Parameter Type Nullable Optional Description
pointerId long ✘ ✘

Return type: void

7. Extensions to the GlobalEventHandlers interface

The following section describes extensions to the existing GlobalEventHandlers interface, defined in [HTML5], to facilitate the event handler registration.

partial interface GlobalEventHandlers { attribute EventHandler onpointerdown; attribute EventHandler onpointermove; attribute EventHandler onpointerup; attribute EventHandler onpointercancel; attribute EventHandler onpointerover; attribute EventHandler onpointerout; attribute EventHandler onpointerenter; attribute EventHandler onpointerleave; };

7.1 Attributes

onpointerdown of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the pointerdown event type.

onpointermove of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the pointermove event type.

onpointerup of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the pointerup event type.

onpointercancel of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the pointercancel event type.

onpointerover of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the pointerover event type.

onpointerout of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the pointerout event type.

onpointerenter of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the pointerenter event type.

onpointerleave of type EventHandler,

The event handler IDL attribute (see [HTML5]) for the pointerleave event type.

8. Extensions to the Navigator interface

The Navigator interface is defined in [HTML5]. This specification extends the Navigator interface to provide device and feature detection support.

partial interface Navigator { readonly attribute boolean pointerEnabled; readonly attribute long maxTouchPoints; };

Attributes

pointerEnabled of type boolean, readonly

Indicates if the browser will fire pointer events for pointing input.

maxTouchPoints of type long, readonly

The maximum number of simultaneous touch contacts supported by the device. In the case of devices with multiple digitizers (e.g. multiple touchscreens), the value MUST be the maximum of the set of maximum supported contacts by each individual digitizer.

For example, suppose a device has 3 touchscreens, which support 2, 5, and 10 simultaneous touch contacts, respectively. The value of maxTouchPoints is 10.

9. Declaring candidate regions for default touch behaviors

For touch input, the default action of any and all pointer events MUST NOT be a manipulation of the viewport (e.g. panning or zooming).

Note

Touch manipulations are intentionally not a default action of pointer events. Removing this dependency on the cancellation of events facilitates performance optimizations by the user agent.

9.1 The touch-action CSS property

Name: touch-action
Value: auto | none [pan-x
Initial: auto
Applies to: block-level elements, SVG elements
Inherited: no
Percentages: N/A
Media: visual
Computed value: Same as specified value.

The touch-action CSS property determines whether touch input MAY trigger default behavior supplied by user agent. This includes, but is not limited to, behaviors such as panning or zooming.

Values have the following meanings:

auto

The user agent MAY determine any permitted touch behaviors, such as panning and zooming manipulations of the viewport, for touches that begin on the element.

none

Touches that begin on the element MUST NOT trigger default touch behaviors.

pan-x

The user agent MAY consider touches that begin on the element only for the purposes of horizontally scrolling the element's nearest ancestor with horizontally scrollable content.

pan-y

The user agent MAY consider touches that begin on the element only for the purposes of vertically scrolling the element's nearest ancestor with vertically scrollable content.

Note

The terms "pan" and "scroll" are considered synonymous. Defining an interaction or gesture for triggering panning or scrolling, or for triggering behavior for the auto or none values are out of scope for this specification.

Note

The touch-action property is restricted to block-level elements and SVG elements to facilitate low-latency touch actions. Future specifications could extend this API to all elements. Authors can use the display CSS property to make other elements generate a block box for use with touch-action.

When a user touches an element, the effect of that touch is determined by the value of the touch-action property and the default touch behaviors on the element and its ancestors. To determine the effect of a touch, find the nearest ancestor (starting from the element itself) that has a default touch behavior. Then examine the touch-action property of each element between the hit tested element and the element with the default touch behavior (including both the hit tested element and the element with the default touch behavior). If the touch-action property of any of those elements disallows the default touch behavior, do nothing. Otherwise allow the element to start considering the touch for the purposes of executing a default touch behavior.

During the execution of a behavior, the user agent MUST NOT dispatch subsequent pointer events for the pointer. The user agent MUST dispatch a pointercancel (and subsequently a pointerout event) whenever all of the following are true, in order to end the stream of events for the pointer:

Example 5: Disallowing all touch behaviors

This element receives pointer events for all touches.

Example 6: Allowing horizontal panning only

This element receives pointer events when not panning in the horizontal direction.

Example 7: Child regions that disallow touch behaviors

This element receives pointer events for all touches.
Touches on this element MAY be consumed for manipulating the parent.

Example 8: Intermediate parent that disallows touch behaviors

This element receives pointer events for all touches because it allows only horizontal panning yet an intermediate ancestor (between it and the pannable element) only allows vertical panning. Therefore, no touch behaviors are allowed.

10. Pointer Capture

Pointer capture allows the events for a particular pointer to be retargeted to a particular element other than the normal hit-test result of the pointer's location. This is useful in scenarios like a custom slider control (e.g. similar to the [HTML5] <input type="range"> control). Pointer capture can be set on the slider thumb element, allowing the user to slide the control back and forth even if the pointer slides off of the thumb.

Custom Volume Slider

Fig. 4 Example of a custom slider control that chooses a value by sliding the thumb element back and forth. After pointerdown on the thumb, pointer capture can be used to allow the user to slide the thumb even if the pointer drifts off of it.

10.1 Setting Pointer Capture

Pointer capture is set on an element by calling the element.setPointerCapture(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, then throw a DOMException with the name InvalidPointerId.
  2. If the pointer is not in the active buttons state, then terminate these steps.
  3. Until pointer capture is released, set the target property of all future pointer and compatibility mouse events for the specified pointerId to the Element on which this method was invoked.
  4. Until pointer capture is released, set the relatedTarget property of all future pointer and compatibility mouse events for the specified pointerId to null.
  5. Fire a gotpointercapture event at the Element on which this method was invoked.

10.2 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, then throw a DOMException with the name InvalidPointerId.
  2. If pointer capture is not currently set for the specified pointer, then terminate these steps.
  3. For all future pointer and compatibility mouse events for the specified pointerId, resume setting the target property to the hit-test results (out of scope for this specification) for the pointer.
  4. Fire a lostpointercapture event at the Element on which this method was invoked.

10.3 Implicit Release of Pointer Capture

Immediately after firing the pointerup or pointercancel events, a user agent MUST run the steps as if the releasePointerCapture() method has been called with an argument equal to the pointerId property of the pointerup orpointercancel event just dispatched.

11. Compatibility Mapping with Mouse Events

The vast majority of web content existing today codes only to Mouse Events. The following describes the algorithm for how a user agent MAY map generic pointer input to mouse events for compatibility with this content. Unless otherwise noted, the target of any mapped mouse event MAY be the same as the target for the pointer event from which it was mapped.

Authors can prevent the production of compatibility mouse events by cancelling the pointerdown event.

The compatibility mapping with mouse events are an OPTIONAL feature of this specification. User agents are encouraged to support the feature for best compatibility with existing legacy content. User agents that do not support compatibility mouse events are still encouraged to support the click and contextmenu events (see the note below).

Note

The click event, defined in [DOM-LEVEL-3-EVENTS], and the contextmenu event, defined in [HTML5], are not considered compatibility mouse events as they are typically tied to user interface activation and are dispatched by other input devices, like keyboards.

In user agents that support firing click and/or contextmenu, calling preventDefault during a pointer event typically does not have an effect on whether click and/or contextmenu are fired or not. Because they are not compatibility mouse events, user agents typically fire click and contextmenu for all pointing devices, including pointers that are not primary pointers.

11.1 Mapping for devices that support hover

Whenever a user agent is to dispatch a pointer event for a device that supports hover, it MAY 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. Dispatch the pointer event.
  3. If the pointer event dispatched was pointerdown and the event was cancelled, then set the PREVENT MOUSE EVENT flag for this pointerType.
  4. If the pointer event dispatched was:
    • pointerover, then dispatch a mouseover event.
    • pointerout, then dispatch a mouseout event.
    • pointerenter, then dispatch a mouseenter event.
    • pointerleave, then dispatch a mouseleave event.
  5. If the PREVENT MOUSE EVENT flag is not set for this pointerType and the pointer event dispatched was:
    • pointerdown, then dispatch a mousedown event.
    • pointermove, then dispatch a mousemove event.
    • pointerup, then dispatch a mouseup event.
    • pointercancel, then dispatch 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.

Note

Mouse events can only be prevented when the pointer is down. Hovering pointers (e.g. a mouse with no buttons pressed) cannot have their mouse events prevented. And, the mouseover and mouseout events are never prevented (even if the pointer is down).

11.2 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:

Note

Hover is sometimes used to toggle the visibility of UI elements in content designed for mouse (e.g. "hover menus"). This content is often incompatible with devices that do not support hover. This specification does not define a mapping or behavior for compatibility with this scenario. It will be considered in a future version of the specification.

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 MAY 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 dispatch a mousemove event.
  3. Dispatch the pointer event.
  4. If the pointer event dispatched was pointerdown and the event was cancelled, then set the PREVENT MOUSE EVENT flag for this pointerType.
  5. If the pointer event dispatched was:
    • pointerover, then dispatch a mouseover event.
    • pointerout, then dispatch a mouseout event.
    • pointerenter, then dispatch a mouseenter event.
    • pointerleave, then dispatch a mouseleave event.
  6. If the PREVENT MOUSE EVENT flag is not set for this pointerType and the pointer event dispatched was:
    • pointerdown, then dispatch a mousedown event.
    • pointermove, then dispatch a mousemove event.
    • pointerup, then dispatch a mouseup event.
    • pointercancel, then dispatch 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.

Note

Mouse events can only be prevented when the pointer is down. Hovering pointers (e.g. a mouse with no buttons pressed) cannot have their mouse events prevented. And, the mouseover and mouseout events are never prevented (even if the pointer is down).

A. Acknowledgements

Many thanks to lots of people for their proposals and recommendations, some of which are incorporated into this document.

Special thanks to those that helped pioneer the first edition of this model, including especially: Charu Chandiram, Peter Freiling, Nathan Furtwangler, Thomas Olsen, Matt Rakow, Ramu Ramanathan, Justin Rogers, Jacob Rossi, Reed Townsend, Steve Wright.

B. Revision History

This section is non-normative.

The following is an informative summary of substantial and major editorial changes between publications of this specification. A complete revision history of the Editor's Drafts of this specification can be found here.

Changes Since the 19 February 2013 Last Call Draft

Last Call Draft dated 19 February 2013

Second Working Draft dated 15 January 2013

This section is non-normative.

C. References

C.1 Normative references

[DOM-LEVEL-3-EVENTS]

Travis Leithead; Jacob Rossi; Doug Schepers; Björn Höhrmann; Philippe Le Hégaret; Tom Pixley. Document Object Model (DOM) Level 3 Events Specification. 06 September 2012. W3C Working Draft. URL: http://www.w3.org/TR/2012/WD-DOM-Level-3-Events-20120906

[HTML5]

Robin Berjon et al. HTML5. 17 December 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/

[RFC2119]

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt

[UI-EVENTS]

Travis Leithead; Gary Kacmarcik. UI Events. 7 January 2013. W3C Editor's Draft. URL: http://dvcs.w3.org/hg/d4e/raw-file/tip/source_respec.htm

C.2 Informative references

[CSS21]

Bert Bos et al. Cascading Style Sheets, level 2 (CSS2) Specification. 07 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/CSS21/