touchevents.html
author shepazu <schepers@w3.org>
Tue, 25 Jan 2011 09:34:57 -0500
changeset 5 e4446bce8960
parent 4 dda9bf4072d0
child 6 83ce29dff849
permissions -rw-r--r--
First draft, using WebKit model
<!DOCTYPE html>
<html>
  <head>
    <title>Touch Events Specification</title>
    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
    <!-- 
      === NOTA BENE ===
      For the three scripts below, if your spec resides on dev.w3 you can check them
      out in the same tree and use relative links so that they'll work offline,
     -->
    <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' class='remove'></script>
    <script class='remove'>
      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "ED",
          
          // the specification's short name, as in http://www.w3.org/TR/short-name/
          shortName:            "touch-events",

          // if your specification has a subtitle that goes below the main
          // formal title, define it here
          // subtitle   :  "an excellent document",

          // if you wish the publication date to be other than today, set this
          // publishDate:  "2009-08-06",

          // if the specification's copyright date is a range of years, specify
          // the start date here:
          // copyrightStart: "2005"

          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
          // and its maturity status
          // previousPublishDate:  "1977-03-15",
          // previousMaturity:  "WD",

          // if there a publicly available Editor's Draft, this is the link
          edDraftURI:           "http://dvcs.w3.org/hg/webevents/raw-file/tip/touchevents.html",

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2009-08-05",

          // if you want to have extra CSS, append them to this list
          // it is recommended that the respec.css stylesheet be kept
          extraCSS:             ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],

          // editors, add as many as you like
          // only "name" is required
          editors:  [
              { name: "Doug Schepers", url: "http://schepers.cc/",
                company: "W3C", companyURL: "http://w3.org/" },
          ],

          // authors, add as many as you like. 
          // This is optional, uncomment if you have authors as well as editors.
          // only "name" is required. Same format as editors.

          //authors:  [
          //    { name: "Your Name", url: "http://example.org/",
          //      company: "Your Company", companyURL: "http://example.com/" },
          //],
          
          // name of the WG
          wg:           "Web Events Working Group",
          
          // URI of the public WG page
          wgURI:        "http://www.w3.org/2010/webevents/",
          
          // name (with the @w3c.org) of the public mailing to which comments are due
          wgPublicList: "public-webevents",
          
          // URI of the patent status for this WG, for Rec-track documents
          // !!!! IMPORTANT !!!!
          // This is important for Rec-track documents, do not copy a patent URI from a random
          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
          // Team Contact.
          wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/45559/status",
      };
    </script>
  </head>
  <body>
    <section id='abstract'>
      The Touch Interface specification defines a set of low-level events that represent one or more points of contact with a touch-sensitive surface, and changes of those points with respect to the surface and any DOM elements displayed upon it (e.g. for touch screens) or associated with it (e.g. for drawing tablets without displays).
    </section>

    
    <section>
      <h2><dfn>TouchPoint</dfn> Interface</h2>
      <p>This interface defines an individual point of contact for a touch event.</p>
       
      <dl title='interface TouchPoint' class='idl'>
        <dt>readonly attribute integer identifier</dt>
        <dd>
          an identification number unique to each touch point
        </dd>
        <dt>readonly attribute EventTarget target</dt>
        <dd>
          the original proximal event target for this touch point 
        </dd>

        <dt>readonly attribute float screenX</dt>
        <dd>
          x-coordinate of point relative to the screen
        </dd>
        <dt>readonly attribute float screenY</dt>
        <dd>
          y-coordinate of point relative to the screen
        </dd>

        <dt>readonly attribute float clientX</dt>
        <dd>
          x-coordinate of point relative to the viewport, excluding any scroll offset
        </dd>
        <dt>readonly attribute float clientY</dt>
        <dd>
          y-coordinate of point relative to the viewport, excluding any scroll offset
        </dd>

        <dt>readonly attribute float pageX</dt>
        <dd>
          x-coordinate of point relative to the viewport, including any scroll offset
        </dd>
        <dt>readonly attribute float pageY</dt>
        <dd>
          y-coordinate of point relative to the viewport, including any scroll offset
        </dd>

        <dt>readonly attribute float cx</dt>
        <dd>
          the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the x-axis
        </dd>
        <dt>readonly attribute float cy</dt>
        <dd>
          the radius of the ellipse which most closely circumscribes the touching area (e.g. finger, stylus) along the y-axis
        </dd>
      </dl>
    </section>

    
    <section>
      <h2><dfn>TouchList</dfn> Interface</h2>
      <p>This interface defines a list of individual points of contact for a touch event.</p>
       
      <dl title='interface TouchList' class='idl'>
        <dt>readonly attribute unsigned long length</dt>
        <dd>
          returns the number of touchpoints in the list
        </dd>
        <dt>caller getter TouchPoint item(in unsigned long <dfn>index</dfn>)</dt>
        <dd>
          returns the touchpoint with index <dfn>index</dfn> from the list, sorted in order from latest to earliest
        </dd>
        <dt>caller getter object identifiedPoint(in integer <dfn>identifier</dfn>)</dt>
        <dd>
          returns the first touchpoint with integer <dfn>identifier</dfn> from the list
        </dd>
      </dl>
    </section>

    
    <section>
      <h2>Touch Interface</h2>
      <p>This interface defines the <dfn>touchstart</dfn>, <dfn>touchend</dfn>, <dfn>touchmove</dfn>, <dfn>touchenter</dfn>, <dfn>touchleave</dfn>, and <dfn>touchcancel</dfn> event types.</p>

      <dl title='interface TouchEvent : Event' class='idl'>
        <!-- <dt>readonly attribute views::AbstractView view</dt>
        <dd>
          The <code>view</code> attribute identifies the <code>AbstractView</code> from which the event was generated.
        </dd> -->
        <dt>readonly attribute TouchList touches</dt>
        <dd>
          a list of <dfn>TouchPoint</dfn>s for every point of contact currently touching the surface
        </dd>
        <dt>readonly attribute TouchList targetTouches</dt>
        <dd>
          a list of <dfn>TouchPoint</dfn>s for every point of contact currently touching the surface, which started on the same target
        </dd>
        <dt>readonly attribute TouchList changedTouches</dt>
        <dd>
          a list of <dfn>TouchPoint</dfn>s for every point of contact which contributed to the event
        </dd>
      </dl>
      
      <section>
        <h3 id="event-touchstart">The <dfn>touchstart</dfn> event</h3>
        <p>A user agent must dispatch this event type when the user places a touch point on the touch surface.</p>
      </section>
      
      <section>
        <h3 id="event-touchstart">The <dfn>touchend</dfn> event</h3>
        <p>A user agent must dispatch this event type when the user removes a touch point from the touch surface.</p>
      </section>
      
      <section>
        <h3 id="event-touchstart">The <dfn>touchmove</dfn> event</h3>
        <p>A user agent must dispatch this event type when the user moves a touch point along the touch surface.</p>
      </section>
      
      <section>
        <h3 id="event-touchstart">The <dfn>touchenter</dfn> event</h3>
        <p>A user agent must dispatch this event type when a touch point moves onto the interactive area defined by a DOM element on which it did not originate.  Events of this type must not bubble.</p>
      </section>
      
      <section>
        <h3 id="event-touchstart">The <dfn>touchleave</dfn> event</h3>
        <p>A user agent must dispatch this event type when a touch point moves off the interactive area defined by a DOM element.  Events of this type must not bubble.</p>
      </section>
      
      <section>
        <h3 id="event-touchstart">The <dfn>touchcancel</dfn> event</h3>
        <p>A user agent must dispatch this event type when the user places a more touch points on the touch surface than the device or implementation is configured to store, in which case the earliest touch point in the list must be removed.</p>
      </section>
    </section>
    
    <section class='appendix'>
      <h2>Acknowledgements</h2>
      <p>
        Many thanks to Robin Berjon for making our lives so much easier with his cool tool, Neil Roberts (SitePen) for his summary of WebKit touch events, and Peter-Paul Koch (PPK) for his writeups and suggestions.
      </p>
    </section>
  </body>
</html>