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, including touchscreens, pen input, etc. Event types have been proposed for handling each of these forms of input individually. However, that approach often incurs unnecessary duplication of logic and event handling overhead 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.
+Today, most [[HTML5]] content is used with and/or designed for mouse input. Those that handle input in a custom manner typically code to [[!UIEVENTS]] Mouse Events. Newer computing devices today, however, incorporate other forms of input, including touchscreens, pen input, etc. Event types have been proposed for handling each of these forms of input individually. However, that approach often incurs unnecessary duplication of logic and event handling overhead 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 only when necessary for an augmented experience.
An additional key goal is to enable multi-threaded user agents to handle default touch actions, such as scrolling, without blocking on script execution.
@@ -228,7 +228,7 @@preventDefault(), returning false in an event handler, or other means as defined by [[!DOM-LEVEL-3-EVENTS]] and [[!HTML5]].preventDefault(), returning false in an event handler, or other means as defined by [[!UIEVENTS]] and [[!HTML5]].PointerEvent InterfaceThe 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 [[!DOM-LEVEL-3-EVENTS]]. The steps for constructing an event are defined in [[!DOM4]]. See the examples for sample code demonstrating how to fire an untrusted pointer event.
PointerEvent interface inherits from MouseEvent, defined in [[DOM-LEVEL-3-EVENTS]] and extended by [[CSSOM-VIEW]].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 [[!UIEVENTS]]. The steps for constructing an event are defined in [[!DOM4]]. See the examples for sample code demonstrating how to fire an untrusted pointer event.
PointerEvent interface inherits from MouseEvent, defined in [[UIEVENTS]] and extended by [[CSSOM-VIEW]].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, but with a change in semantics and values, as outlined in the following sections.
button and buttons properties apply only to pointer events. For any compatibility mouse events the value of button and buttons should follow [[!DOM-LEVEL-3-EVENTS]].Some pointer devices, such as mouse or pen, support multiple buttons. In the [[!UIEVENTS]] 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 [[!UIEVENTS]] MouseEvent interface, but with a change in semantics and values, as outlined in the following sections.
button and buttons properties apply only to pointer events. For any compatibility mouse events the value of button and buttons should follow [[!UIEVENTS]].button propertyFor all pointer events in the table above, composed ([[!DOM4]]) attribute SHOULD be true and detail [[!DOM-LEVEL-3-EVENTS]] attribute SHOULD be 0.
For all pointer events in the table above, composed ([[!DOM4]]) attribute SHOULD be true and detail [[!UIEVENTS]] attribute SHOULD be 0.
fromElement and toElement in MouseEvents to support legacy content. In those user agents, the values of those (inherited) attributes in PointerEvents must be null to encourage the use of the standardized alternates (i.e. target and relatedTarget).Similar to the MouseEvents [[!DOM-LEVEL-3-EVENTS]] the relatedTarget should be initialized to the element whose bounds the pointer just left (in the case of a pointerover or pointerenter event) or the element whose bounds the pointer is entering (in the case of a pointerout or pointerleave). For other pointer events, this value will default to null. Note that when an element receives the pointer capture all the following events for that pointer are considered to be inside the boundary of the capturing element.
Similar to the MouseEvents [[!UIEVENTS]] the relatedTarget should be initialized to the element whose bounds the pointer just left (in the case of a pointerover or pointerenter event) or the element whose bounds the pointer is entering (in the case of a pointerout or pointerleave). For other pointer events, this value will default to null. Note that when an element receives the pointer capture all the following events for that pointer are considered to be inside the boundary of the capturing element.
For gotpointercapture and lostpointercapture all the attributes except the ones defined in the table above should be the same as the Pointer Event that caused the user agent to run Process Pending Pointer Capture and fire the gotpointercapture and lostpointercapture events.
pointerover eventpointerenter eventA user agent MUST fire a pointer event named pointerenter 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 (see pointerdown). Note that setPointerCapture or releasePointerCapture might have changed the hit test target and while a pointer is captured it is considered to be always inside the boundaries of the capturing element for the purpose of firing boundary events. This event type is similar to pointerover, but differs in that it does not bubble.
mouseenter event described in [[DOM-LEVEL-3-EVENTS]], and the CSS :hover pseudo-class described in [[CSS21]]. See also the pointerleave event.mouseenter event described in [[UIEVENTS]], and the CSS :hover pseudo-class described in [[CSS21]]. See also the pointerleave event.pointerdown eventpointerout eventpointerleave eventA user agent MUST fire a pointer event named pointerleave when a pointing device is moved out of the hit test boundaries of an element and all of its descendants, including as a result of a pointerup and pointercancel events from a device that does not support hover (see pointerup and pointercancel). Note that setPointerCapture or releasePointerCapture might have changed the hit test target and while a pointer is captured it is considered to be always inside the boundaries of the capturing element for the purpose of firing boundary events. User agents MUST also fire a pointer event named pointerleave 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 fired until the pointing device has left the boundaries of the element and the boundaries of all of its descendants.
mouseleave event described in [[DOM-LEVEL-3-EVENTS]], and the CSS :hover pseudo-class described in [[CSS21]]. See also the pointerenter event.mouseleave event described in [[UIEVENTS]], and the CSS :hover pseudo-class described in [[CSS21]]. See also the pointerenter event.gotpointercapture eventThe vast majority of web content existing today codes only to Mouse Events. The following describes an algorithm for how a user agent MAY map generic pointer input to mouse events for compatibility with this content.
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).
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 fired from other input devices, like keyboards.
The click event, defined in [[UIEVENTS]], and the contextmenu event, defined in [[HTML5]], are not considered compatibility mouse events as they are typically tied to user interface activation and are fired from 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.
The relative ordering of these high-level events (click, contextmenu, focus, blur, etc.) with pointer events is undefined and varies between user agents. For example, in some user agents contextmenu will often follow a pointerup, in others it'll often precede a pointerup or pointercancel, and in some situations it may be fired without any corresponding pointer event (such as a keyboard shortcut).
mouseover, mouseout, mouseenter, and mouseleave events are never prevented (even if the pointer is down).While only the primary pointers can produce compatibility mouse events, multiple primary pointers can be active simultaneously, each producing its own compatibility mouse events. Since all these compatibility events would appear to MouseEvent code to be coming from a single mouse device, user agents are encouraged to guarantee that the compatibility mouse events are consistent from a single device perspective. For mouse transition events (i.e., mouseover, mouseout, mouseenter and mouseleave), this means the entry/exit state for every event target is valid as implied by [[!DOM-LEVEL-3-EVENTS]]. Users agents SHOULD guarantee this by maintaining the effective position of the legacy mouse pointer in the document as follows.
While only the primary pointers can produce compatibility mouse events, multiple primary pointers can be active simultaneously, each producing its own compatibility mouse events. Since all these compatibility events would appear to MouseEvent code to be coming from a single mouse device, user agents are encouraged to guarantee that the compatibility mouse events are consistent from a single device perspective. For mouse transition events (i.e., mouseover, mouseout, mouseenter and mouseleave), this means the entry/exit state for every event target is valid as implied by [[!UIEVENTS]]. Users agents SHOULD guarantee this by maintaining the effective position of the legacy mouse pointer in the document as follows.
Right before firing a pointerdown, pointerup or pointermove event, or a pointerleave event at the window, the user agent SHOULD run the following steps:
T be the target of the pointerdown, pointerup or pointermove event being dispatched. For the pointerleave event, unset T.T and current effective legacy mouse pointer position are both unset or they are uqual, terminate these steps.mouseover, mouseout, mouseenter and mouseleave events as per [[!DOM-LEVEL-3-EVENTS]] for a mouse moving from the current effective legacy mouse pointer position to T. Consider an unset value of either current effective legacy mouse pointer position or T as an out-of-window mouse position.mouseover, mouseout, mouseenter and mouseleave events as per [[!UIEVENTS]] for a mouse moving from the current effective legacy mouse pointer position to T. Consider an unset value of either current effective legacy mouse pointer position or T as an out-of-window mouse position.T.