Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://www.w3.org/TR/2015/REC-pointerevents-20150224/ below:

Pointer Events

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

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/.

By publishing this Recommendation, W3C expects that the functionality specified in this Pointer Events Recommendation will not be affected by changes to DOM Level 3 Events or DOM4 as those specifications proceed to Recommendation.

The Pointer Events Working Group has demonstrated implementability and interoperability with the Pointer Events test suite and implementation report. Feedback on the specification, test suite, or implementation report may be sent to public-pointer-events@w3.org (archives).

This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

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 contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 14 October 2005 W3C Process Document.

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, 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.

Note

While this specification defines a unified event model for a variety pointer inputs, this model does not cover other forms of input such as keyboards or keyboard-like interfaces (for instance, a screenreader or similar assistive technology running on a touchscreen-only device, which allows users sequential navigation through focusable controls and elements). While user agents might choose to also generate pointer events in response to these interfaces, this scenario is not covered in this specification.

In the first instance, authors are encouraged to provide equivalent functionality for all forms of input by responding to high-level events such as focus, blur and click. However, when using low-level events (such as Pointer Events), authors are encouraged to ensure that all types of input are supported. In the case of keyboards and keyboard-like interfaces, this might require the addition of explicit keyboard event handling. See WCAG 2.0 Guideline 2.1 for further details.

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.

Note

This specification does not provide any advice on the expected behavior of user agents that support both Pointer Events and

. For more information on the relationship between these two specifications, see the

.

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 MAY, MUST, MUST NOT, OPTIONAL, and SHOULD are to be interpreted as described in [RFC2119].

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

<style>
  /* Disable intrinsic user agent touch behaviors (such as panning or zooming) so
  that all events on the canvas element are given to the application instead. */

  canvas {
    touch-action: none;
  }
</style>

<canvas id="drawSurface" width="500px" height="500px" style="border:1px solid black;"></canvas>

<script type='text/javascript'>
    var canvas = document.getElementById("drawSurface"),
    context = canvas.getContext("2d");

    if (window.PointerEvent) {
        canvas.addEventListener("pointermove", paint, false);
        if(window.navigator.maxTouchPoints>1)
    	   /* User agent and hardware support multi-touch */
    }
    else {
        //Provide fallback for user agents that do not support Pointer Events
        canvas.addEventListener("mousemove", paint, false);
    }

    function paint(event) {
        if(event.buttons>0)
    	   context.fillRect(event.clientX, event.clientY, 5, 5);
    }
</script>

Example 2: Detecting the type of input from a user

window.addEventListener("pointerdown", detectInputType, false);

function detectInputType(event) {
    switch(event.pointerType) {
        case "mouse":
            /* mouse input detected */
            break;
        case "pen":
            /* pen/stylus input detected */
            break;
        case "touch":
            /* touch input detected */
            break;
        default:
            /* pointerType is empty (could not be detected)
            or UA-specific custom type */
    }
}

Example 3: Resizing an element to match the contact geometry

<div style="position:absolute; top:0px; left:0px; width:100px;height:100px;"></div>
<script>
window.addEventListener("pointerdown", checkPointerSize, false);

function checkPointerSize(event) {
    event.target.style.width = event.width + "px";
    event.target.style.height = event.height + "px";
}
</script>

Example 4: Firing an untrusted pointer event from script

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

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 within the document, then that pointer is still considered active. Examples:

• A mouse connected to the device is always active.
• A touch contact on the screen is considered active.
• If a touch contact or pen stylus is lifted beyond the range of the digitizer, then it is no longer considered active.

Note

On 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. those targeted at other applications).

canceled 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 senses input from the 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.

queue a task

Adding the task to events task queue of the relevant event loop, as defined in [HTML5].

dictionary PointerEventInit : MouseEventInit {
    long      pointerId = 0;
    double    width = 0;
    double    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 double    width;
    readonly    attribute double    height;
    readonly    attribute float     pressure;
    readonly    attribute long      tiltX;
    readonly    attribute long      tiltY;
    readonly    attribute DOMString pointerType;
    readonly    attribute boolean   isPrimary;
};

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 double, 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 double, 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.

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. 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 Example 2 for a basic demonstration of how the pointerType can be used. Also note that developers should include some form of default handling to cover user agents that may have implemented their own custom pointerType values and for situations where pointerType is simply an empty string.

isPrimary of type boolean, readonly

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

pointerId of type long, defaulting to 0

Initializes the pointerId property of the PointerEvent object.

width of type double, defaulting to 0

Initializes the width property of the PointerEvent object.

height of type double, 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

dictionary is used by the

interface's constructor to provide a mechanism by which to construct untrusted (synthetic) pointer events. It inherits from the

dictionary defined in [

]. The steps for constructing an event are defined in [

]. See the

for sample code demonstrating how to fire an untrusted pointer event.

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:

Note

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 (however, see the note below on multiple primary pointers).

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

• The pointer represents a mouse device.
• The pointer represents a primary touch input.
• The pointer represents a primary pen input.

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

Note

On 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.

Initialize the bubbles attribute for the event to true if the event name is

• pointerdown
• pointerup
• pointercancel
• pointermove
• pointerover
• pointerout
• gotpointercapture
• lostpointercapture

Initialize the cancelable attribute for the event to true if the event name is

• pointerdown
• pointerup
• pointermove
• pointerover
• pointerout

The target object at which the event is fired is determined as follows:

• If the pointer capture target override has been set for the pointer,
  • Set the relatedTarget attribute of the event to null.
  • Fire the event to the pointer capture target override object.
• Otherwise, fire the event to the object returned by normal hit test mechanisms (out of scope for this specification).

Whenever a user agent is to fire a Pointer Event that is not gotpointercapture or lostpointercapture, it must first run these steps:

1. If the pointer capture target override for this pointer is set and is not equal to the pending pointer capture target override, then fire a pointer event named lostpointercapture at the pointer capture target override node.
2. If the pending pointer capture target override for this pointer is set and is not equal to the pointer capture target override, then fire a pointer event named gotpointercapture at the pending pointer capture target override.
   • Further, if the pointer capture target override is not set and, the pending pointer capture target override is not equal to the hit test node for the pointer event which invoked this process, and the hit test node has received pointerover and pointerenter events, then fire a pointer event named pointerout and a pointer event named pointerleave at the hit test node.
3. Set the pointer capture target override to the pending pointer capture target override, if set. Otherwise, clear the pointer capture target override.

This section is non-normative.

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

In the case of the primary pointer, these events (with the exception of gotpointercapture, and lostpointercapture) may also fire compatibility mouse events.

A user agent

named

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

event from a device that

(see

). This event type is similar to

, but differs in that it does not bubble.

Note

There are similarities between this event type, the

event described in [

], and the CSS

pseudo-class described in [

]. See also the

event.

A user agent MUST fire a pointer event named pointerdown 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.

Note

For mouse (or other multi-button pointer devices), this means

and

are not fired for all of the same circumstances as

and

. See

for more information.

For input devices that do not support hover, a user agent MUST also fire a pointer event named pointerover followed by a pointer event named pointerenter prior to dispatching the pointerdown event.

Note

Authors can prevent the firing of certain

by canceling the

event (if the

property is

). This sets the PREVENT MOUSE EVENT FLAG on the pointer. Note, however, that this does not prevent the

,

,

, or

events from firing.

A user agent

named

when a pointer changes coordinates. Additionally, when a pointer changes button state, pressure, tilt, or contact geometry (e.g.

and

) and the circumstances produce no other pointer events defined in this specification then a user agent

named

.

A user agent

named

when a pointer leaves the

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

. 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 pointer event named pointerout followed by a pointer event named pointerleave after dispatching the pointerup event.

Note

For mouse (or other multi-button pointer devices), this means

and

are not fired for all of the same circumstances as

and

. See

for more information.

A user agent

named

in the following circumstances:

• The user agent has determined that a pointer is unlikely to continue to produce events (for example, because of a hardware event).
• After having fired the pointerdown event, if the pointer is subsequently used to manipulate the page viewport (e.g. panning or zooming).

After firing the pointercancel event, a user agent MUST also fire a pointer event named pointerout followed by firing a pointer event named pointerleave.

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:

• A device's screen orientation is changed while a pointer is active.
• The user inputs a greater number of simultaneous pointers than is supported by the device.
• The user agent interprets the input as accidental (for example, the hardware supports palm rejection).

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.

A user agent

named

when any of the following occurs:

• A pointing device is moved out of the hit test boundaries of an element.
• After firing the pointerup event for a device that does not support hover (see pointerup).
• After firing the pointercancel event (see pointercancel).
• When a pen stylus leaves the hover range detectable by the digitizer.

A user agent

named

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

and

events from a device that

(see

and

). User agents

also

named

when a pen stylus leaves hover range detectable by the digitizer. This event type is similar to

, but differs in that it does not bubble and that it

not be fired until the pointing device has left the boundaries of the element and the boundaries of all of its descendants.

Note

There are similarities between this event type, the

event described in [

], and the CSS

pseudo-class described in [

]. See also the

event.

A user agent

event named

after pointer capture is released for a pointer. This event

be fired prior to any subsequent events for the pointer after capture was released. This event is fired at 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 the

,

, and

sections.

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);
};

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.

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 until capture is released. The pointer MUST be in its active buttons state for this method to be effective, otherwise it fails silently. Throws a DOMException with the name InvalidPointerId when the provided 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

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;
};

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.

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 long maxTouchPoints;
};

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 should be 10.

Note

While a maxTouchPoints value of greater than 0 indicates the user's device is capable of supporting touch input, it does not necessarily mean the user will use touch input. Authors should be careful to also consider other input modalities that could be present on the system, such as mouse, pen, screen readers, etc.

Note

maxTouchPoints is often used to ensure that the interaction model of the content can be recognized by the current hardware. UI affordances can be provided to users with less capable hardware. On platforms where the precise number of touch points is not known, the minimum number guaranteed to be recognized is provided. Therefore, it is possible for the number of recognized touch points to exceed the value of maxTouchPoints.

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.

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.

manipulation

The user agent MAY consider touches that begin on the element only for the purposes of scrolling and continuous zooming. Any additional behaviors supported by auto are out of scope for this specification.

Note

Note

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.

Note

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

• The user agent has determined (via methods out of scope for this specification) that touch input is to be consumed for a touch behavior,
• a pointerdown event has been sent for the pointer, and
• a pointerup or pointercancel event (following the above mentioned pointerdown) has not yet been sent for the pointer.

Example 5: Disallowing all touch behaviors

<div style="touch-action: none;">
    This element receives pointer events for all touches.
</div>

Example 6: Allowing horizontal panning only

<div style="touch-action: pan-x;">
    This element receives pointer events when not panning in the horizontal direction.
</div>

Example 7: Child regions that disallow touch behaviors

<div style="overflow: auto;">
    <div style="touch-action: none;">
        This element receives pointer events for all touches.
    </div>
    <div>
        Touches on this element MAY be consumed for manipulating the parent.
    </div>
</div>	

Example 8: Intermediate parent that disallows touch behaviors

<div style="overflow: auto;">
    <div style="touch-action: pan-y;">
        <div style="touch-action: pan-x;">
            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.
        </div>
    </div>
</div>	

Pointer capture allows the events for a particular pointer (including any compatibility mouse events) 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.

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 Element on which this method is invoked does not participate in its ownerDocument's tree, throw an exception with the name InvalidStateError.
3. If the pointer is not in the active buttons state, then terminate these steps.
4. For the specified pointerId, set the pending pointer capture target override to the Element on which this method was invoked.

Note

When pointer capture is set, pointerover, pointerout, pointerenter, and pointerleave events are only generated when crossing the boundary of the element that has capture as other elements can no longer be targeted by the pointer. This has the effect of suppressing these events on all other elements.

1. If the pointerId provided as the method's argument does not match any of the active pointers and these steps are not being invoked as a result of the implicit release of pointer capture, 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. If the pointer capture target override for the specified pointerId is not the Element on which this method was invoked, then terminate these steps.
4. For the specified pointerId, clear the pending pointer capture target override, if set.

Note

Some user agents implement their own implicit pointer capture behavior - for instance, for touch interactions, a user agent could automatically capture the pointer as part of an interaction on a form control (such as a button) to improve user interaction (allowing some finger movement to stray outside of the form control itself during the interaction). As part of this behavior, user agents typically fire gotpointercapture and lostpointercapture events, even though no explicit pointer capture functions (setPointerCapture and releasePointerCapture) were called.

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 or pointercancel event just dispatched.

When the pointer capture target override is removed from its ownerDocument's tree, clear the pending pointer capture target override and pointer capture target override nodes and fire a PointerEvent named lostpointercapture at the document.

The 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.

Unless otherwise noted, the target of any mapped mouse event SHOULD be the same target as the respective pointer event unless the target is no longer participating in its ownerDocument's tree. In this case, the mouse event should be fired at the original target's nearest ancestor node (at the time it was removed from the tree) that still participates in its ownerDocument's tree, meaning that a new event path (based on the new target node) is built for the mouse event.

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

Note

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

Whenever a user agent is to dispatch a pointer event for a device that supports hover, it

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

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:

• The input can hover independently of activation (e.g. moving a mouse cursor without any buttons pressed).
• The input will likely produce the mousemove event on an element before clicking it.

Note

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

, it

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 fire a mousemove event (for compatibility with legacy mouse-specific code).
3. Dispatch the pointer event.
4. If the pointer event dispatched was pointerdown and the event was canceled, then set the PREVENT MOUSE EVENT flag for this pointerType.
5. If the pointer event dispatched was:
   • pointerover, then fire a mouseover event.
   • pointerout, then fire a mouseout event.
   • pointerenter, then fire a mouseenter event.
   • pointerleave, then fire a mouseleave event.
6. If the PREVENT MOUSE EVENT flag is not set for this pointerType and the pointer event dispatched was:
   • pointerdown, then fire a mousedown event.
   • pointermove, then fire a mousemove event.
   • pointerup, then fire a mouseup event.
   • pointercancel, then fire 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

The activation of an element (click) with a primary pointer that does not support hover (e.g. single finger on a touchscreen) would typically produce the following event sequence:

1. mousemove
2. pointerover
3. mouseover
4. pointerenter
5. mouseenter
6. pointerdown
7. mousedown
8. Zero or more pointermove and mousemove events, depending on movement of the pointer
9. pointerup
10. mouseup
11. click
12. pointerout
13. mouseout
14. mouseleave

If, however, the pointerdown event is canceled during this interaction then the sequence of events would be:

1. mousemove
2. pointerover
3. mouseover
4. pointerenter
5. mouseenter
6. pointerdown
7. Zero or more pointermove events, depending on movement of the pointer
8. pointerup
9. click
10. pointerout
11. mouseout
12. mouseleave

Many thanks to lots of people for their proposals and recommendations, some of which are incorporated into this document. The group's Chair acknowledges contributions from the following group members: Arthur Barstow, Matt Brubeck, Rick Byers, Cathy Chan, Scott González, Patrick H. Lauke, Sangwhan Moon, Olli Pettay, Jacob Rossi, Doug Schepers and Asir Vedamuthu.

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.

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.

• Mail - various editorial changes and clarification and added non-normative author guidance for maxTouchPoints

• Mail - Clarified pointerover/pointerout behavior with pointer capture
• Mail - Clarified maxTouchPoints behavior on platforms with less granular information

This section is non-normative.

• Mail - Examples moved to front of spec
• Mail - Clarified contextmenu is not a compatibility mouse event
• Mail - Added non-normative note about pointerId selection algorithm
• Mail - Add missing Document, Window definitions for pointer event handlers
• Mail - Clarified pointer capture events are asynchronous
• Mail - Clarified multiple primary pointers may be active at once
• Mail - Clarified spec positioning in introduction
• Mail - Moved constructor dictionary to be next to PointerEvent definition
• 21746 - Removed contradictory requirement for pointerId to be 1 for mouse
• Mail - Clarified block-level restriction for touch-action

• 20710 - Clarified the touch-action processing model.
• 20217 - Expanded touch-action property to include additional values: pan-x and pan-y.
• 20109 - Changed emulation value for devices that do not support pressure from 1 to 0.5, added emulation for width/height
• 20222 - Clarified that for hover menus the behavior is implementation-defined.
• 20872 - Clarified that multiple concurrent pointers can be primary.
• 21032 - Reworded introduction to clarify goals

• 20107 - Added a new set of button and buttons values to accommodate pen contact with eraser button pressed.
• 20108 - Added additional pointer capture details.
• 20109 - Added emulation (default values) for devices that do not support pressure.
• 20112 - Added pointerenter and pointerleave events using the same model as mouseenter and mouseleave.
• 20219 - Changed pointerType from long to DOMString.
• 20220 - Removed hwTimestamp in favor of a future DOM Event high-resolution timestamp.
• 20221 - Added constructor dictionary for PointerEvent.
• 20281 - Changed width and height to be CSS pixels instead of device pixels.

[DOM-LEVEL-3-EVENTS]

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

[DOM4]

Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. Last Call Working Draft. URL: http://www.w3.org/TR/dom/

[HTML5]

Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/

[RFC2119]

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

[CSS21]

Bert Bos; Tantek Çelik; Ian Hickson; Håkon Wium Lie et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/CSS2

[CSSOM-VIEW]

Simon Pieters; Glenn Adams. CSSOM View Module. 17 December 2013. W3C Working Draft. URL: http://www.w3.org/TR/cssom-view/

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4