Touch Events - Level 2

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 word MUST in this document is to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

WindowProxy is defined in [ HTML5 ].

WebIDL Conformance

The IDL blocks in this specification are conforming IDL fragments as defined by the WebIDL specification [ WEBIDL ].

A conforming user agent must also be a conforming ECMAScript implementation of this IDL fragments in this specification, with the following exception:

• section 4.4.6 of Web IDL requires that IDL attributes are reflected as accessor properties on interface prototype objects. Instead of this, the user agent may reflect IDL attributes as data properties on the platform objects that implement the relevant interface. These data properties must have the same behavior when getting and setting as would be exhibited when invoking the getter and setter of the accessor properties on the platform object.

Note: Both ways of reflecting IDL attributes allow for simply getting and setting the property on the platform object to work. For example, given a Touch object aTouch , evaluating aTouch.target would return the EventTarget for the Touch object. If the user agent implements IDL attributes as accessor properties, then the property access invokes the getter which returns the EventTarget . If the user agent implements IDL attributes as data properties on the platform object with the same behavior as would be found with the accessor properties, then the object would appear to have an own property named target whose value is an EventTarget object, and the property access would return this value.

3. Touch Interface

This interface describes an individual touch point for a touch event. Touch objects are immutable; after one is created, its attributes must not change.

WebIDLenum TouchType {
    "direct",
    "stylus"
};
dictionary TouchInit {
    required long        identifier;
    required EventTarget target;
             double      clientX = 0;
             double      clientY = 0;
             double      screenX = 0;
             double      screenY = 0;
             double      pageX = 0;
             double      pageY = 0;
             float       radiusX = 0;
             float       radiusY = 0;
             float       rotationAngle = 0;
             float       force = 0;
             double      altitudeAngle = 0;
             double      azimuthAngle = 0;
             TouchType   touchType = "direct";
};
[Exposed=Window]
interface Touch {
    constructor(TouchInit touchInitDict);
    readonly        attribute long        identifier;
    readonly        attribute EventTarget target;
    readonly        attribute double      screenX;
    readonly        attribute double      screenY;
    readonly        attribute double      clientX;
    readonly        attribute double      clientY;
    readonly        attribute double      pageX;
    readonly        attribute double      pageY;
    readonly        attribute float       radiusX;
    readonly        attribute float       radiusY;
    readonly        attribute float       rotationAngle;
    readonly        attribute float       force;
    readonly        attribute float       altitudeAngle;
    readonly        attribute float       azimuthAngle;
    readonly        attribute TouchType   touchType;
};

identifier

An identification number for each touch point .

When a touch point becomes active, it must be assigned an identifier that is distinct from any other active touch point . While the touch point remains active, all events that refer to it must assign it the same identifier .

target

The EventTarget on which the touch point started when it was first placed on the surface, even if the touch point has since moved outside the interactive area of that element.

Note

Some implementations alter the target element to correct for the imprecision of coarse input. Therefore, the target element may not necessarily be the element directly at the coordinates of the event. The methods used to target/disambiguate coarse input are out of scope for this specification.

screenX

The horizontal coordinate of point relative to the screen in pixels

screenY

The vertical coordinate of point relative to the screen in pixels

clientX

The horizontal coordinate of point relative to the viewport in pixels, excluding any scroll offset

clientY

The vertical coordinate of point relative to the viewport in pixels, excluding any scroll offset

pageX

The horizontal coordinate of point relative to the viewport in pixels, including any scroll offset

pageY

The vertical coordinate of point relative to the viewport in pixels, including any scroll offset

radiusX

The radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the axis indicated by rotationAngle, in CSS pixels (as defined by [ CSS-VALUES ]) of the same scale as screenX; 0 if no value is known. The value must not be negative.

radiusY

The radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the axis perpendicular to that indicated by rotationAngle, in CSS pixels (as defined by [ CSS-VALUES ]) of the same scale as screenY; 0 if no value is known. The value must not be negative.

rotationAngle

The angle (in degrees) that the ellipse described by radiusX and radiusY is rotated clockwise about its center; 0 if no value is known. The value must be greater than or equal to 0 and less than 90 .

If the ellipse described by radiusX and radiusY is circular, then rotationAngle has no effect. The user agent may use 0 as the value in this case, or it may use any other value in the allowed range. (For example, the user agent may use the rotationAngle value from the previous touch event, to avoid sudden changes.)

force

A relative value of pressure applied, in the range 0 to 1 , where 0 is no pressure, and 1 is the highest level of pressure the touch device is capable of sensing; 0 if no value is known. In environments where force is known, the absolute pressure represented by the force attribute, and the sensitivity in levels of pressure, may vary.

altitudeAngle

The altitude (in radians) of a stylus, the transducer (e.g. pen/stylus), in the range [0,π/2] — where 0 (parallel is parallel to the surface) to surface (X-Y plane), and π/2 (perpendicular is perpendicular to the surface). surface. For hardware and platforms that do not report tilt or angle, the value MUST be 0.

Note

The default value defined here for 0 altitudeAngle should be used is 0. This differs from the Pointer Events - Level 3 [ POINTEREVENTS ] specification's definition for devices the altitudeAngle property, which do not support this property. has a default value of π/2, which positions the transducer as being perpendicular to the surface.

azimuthAngle

The azimuth angle (in radians) of a stylus, the transducer (e.g. pen/stylus), in the range 0 to 2π . [0, 2π] — where 0 represents a stylus transducer whose cap is pointing in the direction of increasing screenX values. π/2 represents a stylus whose cap X values (point to "3 o'clock" if looking straight down) on the X-Y plane, and the values progressively increase when going clockwise (π/2 at "6 o'clock", π at "9 o'clock", 3π/2 at "12 o'clock"). When the transducer is pointing in perfectly perpendicular to the direction of increasing screenY values. The value surface ( 0 altitudeAngle should of π/2), the value MUST be used for devices which 0. For hardware and platforms that do not support this property. report tilt or angle, the value should be 0.

touchType

The type of device used to trigger the touch.

TouchType

An enumeration representing the different types of possible touch input.

direct

A direct touch from a finger on the screen.

stylus

A touch from a stylus or pen device.

4. TouchList Interface

This interface defines a list of individual points of contact for a touch event. TouchList objects are immutable; after one is created, its contents must not change.

A TouchList object's supported property indices ([ WEBIDL ]) are the numbers in the range 0 to one less than the length of the list.

WebIDL[Exposed=Window]
interface TouchList {
    readonly        attribute unsigned long length;
    getter Touch? item (unsigned long index);
};

length

Returns the number of Touch objects in the list

item

Returns the Touch at the specified index in the list or null if the index is not less than the length of the list.

5. TouchEvent Interface

This interface defines the touchstart , touchend , touchmove , and touchcancel event types. TouchEvent objects are immutable; after one is created and initialized, its attributes must not change. TouchEvent inherits from the UIEvent interface defined in [ DOM-LEVEL-3-EVENTS ].

The TouchEventInit dictionary is used by the TouchEvent interface's constructor to provide a mechanism by which to construct untrusted (synthetic) touch events. It inherits from the EventModifierInit dictionary defined in [ DOM-LEVEL-3-EVENTS ]. The steps for constructing an event are defined in [ DOM4 ]. See the example for sample code demonstrating how to fire an untrusted touch event.

WebIDLdictionary TouchEventInit : EventModifierInit {
             sequence<Touch> touches = [];
             sequence<Touch> targetTouches = [];
             sequence<Touch> changedTouches = [];
};
[Exposed=Window]
interface TouchEvent : UIEvent {
    constructor(DOMString type, optional TouchEventInit eventInitDict = {});
    readonly        attribute TouchList touches;
    readonly        attribute TouchList targetTouches;
    readonly        attribute TouchList changedTouches;
    readonly        attribute boolean   altKey;
    readonly        attribute boolean   metaKey;
    readonly        attribute boolean   ctrlKey;
    readonly        attribute boolean   shiftKey;
    getter boolean getModifierState (DOMString keyArg);
};

touches

A list of Touch objects for every point of contact currently touching the surface.

targetTouches

A list of Touch objects for every point of contact that is touching the surface and started on the element that is the target of the current event.

changedTouches

A list of Touch objects for every point of contact which contributed to the event.

For the touchstart event this must be a list of the touch points that just became active with the current event. For the touchmove event this must be a list of the touch points that have moved since the last event. For the touchend and touchcancel events this must be a list of the touch points that have just been removed from the surface, with the last known coordinates of the touch points before they were removed.

altKey

true if the alt (Alternate) key modifier is activated; otherwise false

metaKey

true if the meta (Meta) key modifier is activated; otherwise false . On some platforms this attribute may map to a differently-named key modifier.

ctrlKey

true if the ctrl (Control) key modifier is activated; otherwise false

shiftKey

true if the shift (Shift) key modifier is activated; otherwise false

getModifierState (keyArg)

Queries the state of a modifier using a key value. Returns true if it is a modifier key and the modifier is activated, false otherwise.

<div id='touchable'>This element is touchable.</div>
<script>
document.getElementById('touchable').addEventListener('touchstart', function(ev) {
    if (ev.touches.item(0) == ev.targetTouches.item(0))
    {
        /**
         * If the first touch on the surface is also targeting the
         * "touchable" element, the code below should execute.
         * Since targetTouches is a subset of touches which covers the
         * entire surface, TouchEvent.touches >= TouchEvents.targetTouches
         * is always true.
         */
        document.write('Hello Touch Events!');
    }
    if (ev.touches.length == ev.targetTouches.length)
    {
        /**
         * If all of the active touch points are on the "touchable"
         * element, the length properties should be the same.
         */
        document.write('All points are on target element')
    }
    if (ev.touches.length > 1)
    {
        /**
         * On a single touch input device, there can only be one point
         * of contact on the surface, so the following code can only
         * execute when the terminal supports multiple touches.
         */
        document.write('Hello Multiple Touch!');
    }
}, false);


</

script

>

<div id='touchable'>This element is touchable.</div>
<script>
document.getElementById('touchable').addEventListener('touchend', function(ev) {
    /**
     * Example output when three touch points are on the surface,
     * two of them being on the "touchable" element and one point
     * in the "touchable" element is lifted from the surface:
     *
     * Touch points removed: 1
     * Touch points left on element: 1
     * Touch points left on document: 2
     */
    document.write('Touch points removed: ' + ev.changedTouches.length);
    document.write('Touch points left on element: ' + ev.targetTouches.length);
    document.write('Touch points left on document: ' + ev.touches.length);
}, false);


</

script

>

if (Touch.length < 1 || TouchEvent.length < 1)
  throw "TouchEvent constructors not supported";
var touch = new Touch({
    identifier: 42,
    target: document.body,
    clientX: 200,
    clientY: 200,
    screenX: 300,
    screenY: 300,
    pageX: 200,
    pageY: 200,
    radiusX: 5,
    radiusY: 5
});
var touchEvent = new TouchEvent("touchstart", {
    cancelable: true,
    bubbles: true,
    composed: true,
    touches: [touch],
    targetTouches: [touch],
    changedTouches: [touch]
});

document
.body.dispatchEvent(touchEvent);

6. Retargeting

The following section describes retargeting steps , defined in [ WHATWG-DOM ].

Touch object has an associated unadjustedTarget (null or EventTarget ). Unless stated otherwise it is null.

TouchEvent 's retargeting steps , given a touchEvent , must run these steps:

1. For each Touch touch in touchEvent 's touches , targetTouches , and changedTouches members:

   1. Set touch 's unadjustedTarget to touch 's target if touch 's unadjustedTarget is null.
   2. Set touch 's target to the result of invoking retargeting touch 's unadjustedTarget against touchEvent 's target .

7. Conditionally exposing legacy touch event APIs

User agents have an associated boolean expose legacy touch event APIs whose value is implementation-defined .

8. Extensions to the GlobalEventHandlers mixin

The following section describes extensions to the existing GlobalEventHandlers mixin, defined in [ HTML5 ], to facilitate the event handler registration. For user agents where expose legacy touch event APIs is false, this mixin must not be implemented.

WebIDLpartial interface mixin GlobalEventHandlers {
                    attribute EventHandler ontouchstart;
                    attribute EventHandler ontouchend;
                    attribute EventHandler ontouchmove;
                    attribute EventHandler ontouchcancel;
};

ontouchstart

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

ontouchend

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

ontouchmove

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

ontouchcancel

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

9. Interaction with Mouse Events and click

The user agent may dispatch both touch events and (for compatibility with web content not designed for touch) mouse events [ DOM-LEVEL-2-EVENTS ] in response to the same user input. If the user agent dispatches both touch events and mouse events in response to a single user action, then the touchstart event type must be dispatched before any mouse event types for that action. If touchstart , touchmove , or touchend are canceled , the user agent should not dispatch any mouse event that would be a consequential result of the prevented touch event.

If the user agent interprets a sequence of touch events as a tap gesture, then it should dispatch mousemove , mousedown , mouseup , and click events (in that order) at the location of the touchend event for the corresponding touch input. If the contents of the document have changed during processing of the touch events, then the user agent may dispatch the mouse events to a different target than the touch events.

The default actions and ordering of any further touch and mouse events are implementation-defined, except as specified elsewhere.

// conditional "touch OR mouse/keyboard" event binding
// DON'T DO THIS, as it makes interactions touch-exclusive
// on devices that have both touch and mouse/keyboard
if ('ontouchstart' in window) {
  // set up event listeners for touch
  target.addEventListener('touchend', ...);
  ...
} else {
  // set up event listeners for mouse/keyboard
  target.addEventListener('click', ...);
  ...
}

// concurrent "touch AND mouse/keyboard" event binding
// set up event listeners for touch
target.addEventListener('touchend', function(e) {
  // prevent compatibility mouse events and click
  e.preventDefault();
  ...
});
...
// set up event listeners for mouse/keyboard
target.addEventListener('click', ...);
...

10. Glossary

active touch point

A touch point which is currently on the screen and is being tracked by the user agent. The touch point becomes active when the user agent first dispatches a touchstart event indicating its appearance. It ceases to be active after the user agent dispatches a touchend or touchcancel event indicating that the touch point is removed from the surface or no longer tracked.

touch point

The coordinate point at which a pointer (e.g finger or stylus) intersects the target surface of an interface. This may apply to a finger touching a touch-screen, or an digital pen writing on a piece of paper.

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