98

      The Touch Interface specification defines a set of low-level events that

    99

      represent one or more points of contact with a touch-sensitive surface,

   100

      and changes of those points with respect to the surface and any DOM

   101

      elements displayed upon it (e.g. for touch screens) or associated with it

   102

      (e.g. for drawing tablets without displays).  It also addresses

   103

      pen-tablet devices, such as drawing tablets, with consideration toward

   104

      stylus capabilities.

   110

      <p>

   111

        User Agents that run on terminals which provide touch input to use web

   112

        applications typically use interpreted mouse events to allow the users

   113

        to access interactive web applications. However, these interpreted

   114

        events, being normalized data based on the physical touch input, tend

   115

        to have limitations on delivering the exact intended user experience.

   116

        Additionally, it is not possible to handle concurrent input regardless

   117

        of the device capability, due the constraints of mouse events: both

   118

        system level limitations, and legacy compatibility.

   119

      </p>

   121

      <p>

   122

        Meanwhile, native applications are capable of handling both cases with

   123

        the provided system APIs.

   124

      </p>

   125

   126

      <p>

   127

        The Touch Events specification provides a solution to this problem by

   128

        specifing interfaces to allow web applications to directly handle touch

   129

        events, and multiple touch points for capable devices.

   130

      </p>

   134

      <p>

   135

        This specification defines conformance criteria that apply to a single

   136

        product: the <dfn id="dfn-user-agent">user agent</dfn> that implements

   137

        the interfaces that it contains.

   138

      </p>

   140

      <p>

   141

        Implementations that use ECMAScript to implement the APIs defined in

   142

        this specification must implement them in a manner consistent with the

   143

        ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]] as

   144

        this specification uses that specification and terminology.

   145

      </p>

   147

      <p>

   148

        A conforming implementation is required to implement all fields

   149

        defined in this specification.

   150

      </p>

   155

      <p>

   156

        This interface defines an individual point of contact for a touch

   157

        event.

   158

      </p>

   163

          An identification number for each <a>touch point</a>, unique to that

   164

          <a>touch point</a> per session.

   166

          <p>

   167

            The algorithm for determining the <a>identifier</a> value is as

   168

            follows:

   169

          </p>

   171

            <li>

   172

              if there are no other <a>active touch event session</a>s, the

   173

              value of <a>identifier</a> must be <code>0</code>

   174

            </li>

   175

            <li>

   176

              if there is at least one <a>active touch event session</a>, the

   177

              value of <a>identifier</a> must be the lowest integer not

   178

              currently used by any active <a>Touch</a> object in any

   179

              <a>active touch event session</a>

   180

            </li>

   195

          x-coordinate of point relative to the viewport, excluding any scroll

   196

          offset

   200

          y-coordinate of point relative to the viewport, excluding any scroll

   201

          offset

   206

          x-coordinate of point relative to the viewport, including any scroll

   207

          offset

   211

          y-coordinate of point relative to the viewport, including any scroll

   212

          offset

   217

          the radius of the ellipse which most closely circumscribes the

   218

          touching area (e.g. finger, stylus) along the x-axis, in pixels of

   219

          the same scale as <a>screenX</a>; <code>1</code> if no value is

   220

          known.  The value must be positive.

   221

          <p class="issue" id="issue-units"><strong>Issue:</strong> What are

   222

          units of radiusX/radiusY?  CSS Pixels?</p>

   226

          the radius of the ellipse which most closely circumscribes the

   227

          touching area (e.g. finger, stylus) along the y-axis, in pixels of

   228

          the same scale as <a>screenY</a>; <code>1</code> if no value is

   229

          known.  The value must be positive.

   252

          a relative value of pressure applied, in the range <code>0</code> to

   253

          <code>1</code>, where <code>0</code> is no pressure, and

   254

          <code>1</code> is the highest level of pressure the touch device is

   255

          capable of sensing; <code>0</code> if no value is known.  In

   256

          environments where <a>force</a> is known, the absolute pressure

   257

          represented by the <a>force</a> attribute, and the sensitivity in

   258

          levels of pressure, may vary.

   260

          <p class="issue" id="issue-inkml">

   261

            <strong>Issue:</strong>

   262

            Consider aligning with other "channels" and values from

   263

            <a href="http://www.w3.org/TR/InkML/#channelContents">Ink Markup

   264

            Language (InkML)</a>, in addition to <a>force</a>, e.g. adding

   265

            <a>angle</a>, <a>clientZ</a>, <a>rotation</a>, etc.

   266

          </p>

   273

      <p>

   274

        This interface defines a list of individual points of contact for a

   275

        touch event.

   276

      </p>

   285

          returns the <a>Touch</a> with index <a>index</a> from the list,

   286

          sorted in order from latest to earliest

   290

          returns the first <a>Touch</a> with long <a>identifier</a> from the

   291

          list

   298

      <p>

   299

        This interface defines the <a>touchstart</a>, <a>touchend</a>,

   300

        <a>touchmove</a>, <a>touchenter</a>, <a>touchleave</a>, and

   301

        <a>touchcancel</a> event types.

   302

      </p>

   307

          a list of <a>Touch</a>es for every point of contact currently

   308

          touching the surface

   312

          a list of <a>Touch</a>es for every point of contact currently

   313

          touching the surface, which started on the same target

   317

          a list of <a>Touch</a>es for every point of contact which contributed

   318

          to the event

   323

          <code>true</code> if the alt (Alternate) key modifier is activated;

   324

          otherwise <code>false</code>

   328

          <code>true</code> if the meta (Meta) key modifier is activated;

   329

          otherwise <code>false</code>.  On some platforms this attribute may

   330

          map to a differently-named key modifier.

   334

          <code>true</code> if the ctrl (Control) key modifier is activated;

   335

          otherwise <code>false</code>

   339

          <code>true</code> if the shift (Shift) key modifier is activated;

   340

          otherwise <code>false</code>

   355

          initializes a TouchEvent created through the <a>DocumentEvent</a>

   356

          interface.

   375

        <h3 id="event-touchstart">The <dfn class="event">touchstart</dfn>

   376

        event</h3>

   377

        <p>

   378

          A user agent must dispatch this event type to indicate when the user

   379

          places a <a>touch point</a> on the touch surface.

   380

        </p>

   382

        <p>

   383

          The target of this event must be an <a>Element</a>.

   384

        </p>

   389

        <p>

   390

          A user agent must dispatch this event type to indicate when the user

   391

          removes a <a>touch point</a> from the touch surface, also including

   392

          cases where the touch point physically leaves the touch surface, such

   393

          as being dragged off of the screen.

   394

        </p>

   396

        <p>

   397

          The <a>target</a> of this event must be the same <a>Element</a> that

   398

          received the <a>touchstart</a> event when this <a>touch point</a> was

   399

          placed on the surface, even if the <a>touch point</a> has since moved

   400

          outside the interactive area of the <a>target</a> element.

   401

        </p>

   403

        <p>

   404

          The <a>touch point</a> or points that were removed must be included

   405

          in the <a>changedTouches</a> attribute of the <a>TouchEvent</a>, and

   406

          must not be included in the <a>touches</a> and <a>targetTouches</a>

   407

          attributes.

   408

        </p>

   413

        <p>

   414

          A user agent must dispatch this event type to indicate when the user

   415

          moves a <a>touch point</a> along the touch surface.

   416

        </p>

   418

        <p>

   419

          The <a>target</a> of this event must be the same <a>Element</a> that

   420

          received the <a>touchstart</a> event when this <a>touch point</a> was

   421

          placed on the surface, even if the <a>touch point</a> has since moved

   422

          outside the interactive area of the <a>target</a> element.

   423

        </p>

   425

        <p>

   426

          If the values of <a>radiusX</a>, <a>radiusY</a>,

   427

          <a>rotationAngle</a>, or <a>force</a> are known, then the user agent

   428

          also must dispatch this event type to indicate when any of these

   429

          attributes of a <a>touch point</a> have changed.

   430

        </p>

   431

   432

        <p>

   433

          Note that the rate at which the user agent sends <a>touchmove</a>

   434

          events is implementation-defined, and may depend on hardware

   435

          capabilities and other implementation details.

   436

        </p>

   441

        <p>

   442

          A user agent must dispatch this event type to indicate when a

   443

          <a>touch point</a> moves onto the interactive area defined by a DOM

   444

          element.  Events of this type must not bubble.

   445

        </p>

   450

        <p>

   451

          A user agent must dispatch this event type to indicate when a

   452

          <a>touch point</a> moves off the interactive area defined by a DOM

   453

          element.  Events of this type must not bubble.

   454

        </p>

   459

        <p>

   460

          A user agent must dispatch this event type to indicate when a touch

   461

          point has been disrupted in an implementation-specific manner, such as

   462

          a synchronous event or action originating from the UA canceling the

   463

          touch, or the touch point leaving the document window into a

   464

          non-document area which is capable of handling user interactions.

   465

          (e.g. The UA's native user interface, plug-ins)  A user agent may

   466

          also dispatch this event type when the user places more <a>touch

   467

          point</a>s on the touch surface than the device or implementation is

   468

          configured to store, in which case the earliest <a>Touch</a> object

   469

          in the <a>TouchList</a> should be removed.

   470

        </p>

   476

      <p>

   477

        The <a>DocumentTouch</a> interface provides a mechanism by which the

   478

        user can create <a>Touch</a> and <a>TouchList</a> objects. The

   479

        <a>DocumentTouch</a> interface must be implemented on the

   480

        <a>Document</a> object.

   481

      </p>