touchevents.html
branchv1
changeset 101 2d830a098494
parent 100 4bbe000815dd
child 104 01190a01b4cf
equal deleted inserted replaced
100:4bbe000815dd 101:2d830a098494
     1 <!DOCTYPE html>
     1 <!DOCTYPE html>
     2 <html lang="en">
     2 <html lang="en">
     3   <head>
     3   <head>
     4     <title>Touch Events Specification</title>
     4     <title>Touch Events version 1</title>
     5     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
     5     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
     6     <meta name="viewport" content="width=device-width">
     6     <meta name="viewport" content="width=device-width">
     7     <!--
     7     <!--
     8       === NOTA BENE ===
     8       === NOTA BENE ===
     9       For the three scripts below, if your spec resides on dev.w3 you can check them
     9       For the three scripts below, if your spec resides on dev.w3 you can check them
    21           // if your specification has a subtitle that goes below the main
    21           // if your specification has a subtitle that goes below the main
    22           // formal title, define it here
    22           // formal title, define it here
    23           // subtitle   :  "an excellent document",
    23           // subtitle   :  "an excellent document",
    24 
    24 
    25           // if you wish the publication date to be other than today, set this
    25           // if you wish the publication date to be other than today, set this
    26           publishDate:  "2011-07-19",
    26           publishDate:  "2011-08-11",
    27 
    27 
    28           // if the specification's copyright date is a range of years, specify
    28           // if the specification's copyright date is a range of years, specify
    29           // the start date here:
    29           // the start date here:
    30           // copyrightStart: "2005"
    30           // copyrightStart: "2005"
    31 
    31 
   196         <dt>readonly attribute long pageY</dt>
   196         <dt>readonly attribute long pageY</dt>
   197         <dd>
   197         <dd>
   198           y-coordinate of point relative to the viewport, including any scroll
   198           y-coordinate of point relative to the viewport, including any scroll
   199           offset
   199           offset
   200         </dd>
   200         </dd>
   201 
       
   202         <dt>readonly attribute long radiusX</dt>
       
   203         <dd>
       
   204           the radius of the ellipse which most closely circumscribes the
       
   205           touching area (e.g. finger, stylus) along the x-axis, in pixels of
       
   206           the same scale as <a>screenX</a>; <code>1</code> if no value is
       
   207           known.  The value must be positive.
       
   208           <p class="issue" id="issue-units"><strong>Issue:</strong> What are
       
   209           units of radiusX/radiusY?  CSS Pixels?</p>
       
   210         </dd>
       
   211         <dt>readonly attribute long radiusY</dt>
       
   212         <dd>
       
   213           the radius of the ellipse which most closely circumscribes the
       
   214           touching area (e.g. finger, stylus) along the y-axis, in pixels of
       
   215           the same scale as <a>screenY</a>; <code>1</code> if no value is
       
   216           known.  The value must be positive.
       
   217         </dd>
       
   218 
       
   219         <dt>readonly attribute float rotationAngle</dt>
       
   220         <dd>
       
   221           <p>
       
   222             the angle (in degrees) that the ellipse described by <a>radiusX</a>
       
   223             and <a>radiusY</a> is rotated clockwise about its center;
       
   224             <code>0</code> if no value is known.  The value must be greater
       
   225             than or equal to <code>0</code> and less than <code>90</code>.
       
   226           </p>
       
   227           <p>
       
   228             If the ellipse described by <a>radiusX</a> and <a>radiusY</a> is
       
   229             circular, then <a>rotationAngle</a> has no effect.  The user agent
       
   230             may use <code>0</code> as the value in this case, or it may use any
       
   231             other value in the allowed range.  (For example, the user agent may
       
   232             use the <a>rotationAngle</a> value from the previous touch event,
       
   233             to avoid sudden changes.)
       
   234           </p>
       
   235         </dd>
       
   236 
       
   237         <dt>readonly attribute float force</dt>
       
   238         <dd>
       
   239           a relative value of pressure applied, in the range <code>0</code> to
       
   240           <code>1</code>, where <code>0</code> is no pressure, and
       
   241           <code>1</code> is the highest level of pressure the touch device is
       
   242           capable of sensing; <code>0</code> if no value is known.  In
       
   243           environments where <a>force</a> is known, the absolute pressure
       
   244           represented by the <a>force</a> attribute, and the sensitivity in
       
   245           levels of pressure, may vary.
       
   246 
       
   247           <p class="issue" id="issue-inkml">
       
   248             <strong>Issue:</strong>
       
   249             Consider aligning with other "channels" and values from
       
   250             <a href="http://www.w3.org/TR/InkML/#channelContents">Ink Markup
       
   251             Language (InkML)</a>, in addition to <a>force</a>, e.g. adding
       
   252             <a>angle</a>, <a>clientZ</a>, <a>rotation</a>, etc.
       
   253           </p>
       
   254         </dd>
       
   255       </dl>
   201       </dl>
   256     </section>
   202     </section>
   257 
   203 
   258     <section>
   204     <section>
   259       <h2><a>TouchList</a> Interface</h2>
   205       <h2><a>TouchList</a> Interface</h2>
   282 
   228 
   283     <section>
   229     <section>
   284       <h2><a>TouchEvent</a> Interface</h2>
   230       <h2><a>TouchEvent</a> Interface</h2>
   285       <p>
   231       <p>
   286         This interface defines the <a>touchstart</a>, <a>touchend</a>,
   232         This interface defines the <a>touchstart</a>, <a>touchend</a>,
   287         <a>touchmove</a>, <a>touchenter</a>, <a>touchleave</a>, and
   233         <a>touchmove</a>, and <a>touchcancel</a> event types.
   288         <a>touchcancel</a> event types.
       
   289       </p>
   234       </p>
   290 
   235 
   291       <dl title='interface TouchEvent : UIEvent' class='idl'>
   236       <dl title='interface TouchEvent : UIEvent' class='idl'>
   292         <dt>readonly attribute <a>TouchList</a> touches</dt>
   237         <dt>readonly attribute <a>TouchList</a> touches</dt>
   293         <dd>
   238         <dd>
   310             For the <a>touchstart</a> event this must be a list of the touch
   255             For the <a>touchstart</a> event this must be a list of the touch
   311             points that just became active with the current event.  For the
   256             points that just became active with the current event.  For the
   312             <a>touchmove</a> event this must be a list of the touch points that
   257             <a>touchmove</a> event this must be a list of the touch points that
   313             have moved since the last event.  For the <a>touchend</a> event
   258             have moved since the last event.  For the <a>touchend</a> event
   314             this must be a list of the touch points that have just been removed
   259             this must be a list of the touch points that have just been removed
   315             from the surface.  For the <a>touchenter</a> and <a>touchleave</a>
   260             from the surface.
   316             events, this must be a list of the touch points that have just
       
   317             entered or left the target element.
       
   318           </p>
   261           </p>
   319         </dd>
   262         </dd>
   320 
   263 
   321         <dt>readonly attribute boolean altKey</dt>
   264         <dt>readonly attribute boolean altKey</dt>
   322         <dd>
   265         <dd>
   336         </dd>
   279         </dd>
   337         <dt>readonly attribute boolean shiftKey</dt>
   280         <dt>readonly attribute boolean shiftKey</dt>
   338         <dd>
   281         <dd>
   339           <code>true</code> if the shift (Shift) key modifier is activated;
   282           <code>true</code> if the shift (Shift) key modifier is activated;
   340           otherwise <code>false</code>
   283           otherwise <code>false</code>
   341         </dd>
       
   342         <dt>readonly attribute EventTarget relatedTarget</dt>
       
   343         <dd>
       
   344           identifies a secondary EventTarget related to a touch event.  This
       
   345           attribute is used with the <a>touchenter</a> event to indicate the
       
   346           <a>EventTarget</a> the touch point exited, and with the
       
   347           <a>touchleave</a> event to indicate the <a>EventTarget</a> the touch
       
   348           point entered.  For other event types, this attribute must be
       
   349           <code>null</code>.
       
   350         </dd>
   284         </dd>
   351 
   285 
   352         <!-- Methods -->
   286         <!-- Methods -->
   353         <dt>void initTouchEvent()</dt>
   287         <dt>void initTouchEvent()</dt>
   354         <dd>
   288         <dd>
   530           placed on the surface, even if the <a>touch point</a> has since moved
   464           placed on the surface, even if the <a>touch point</a> has since moved
   531           outside the interactive area of the <a>target</a> element.
   465           outside the interactive area of the <a>target</a> element.
   532         </p>
   466         </p>
   533 
   467 
   534         <p>
   468         <p>
   535           If the values of <a>radiusX</a>, <a>radiusY</a>,
       
   536           <a>rotationAngle</a>, or <a>force</a> are known, then the user agent
       
   537           also must dispatch this event type to indicate when any of these
       
   538           attributes of a <a>touch point</a> have changed.
       
   539         </p>
       
   540 
       
   541         <p>
       
   542           Note that the rate at which the user agent sends <a>touchmove</a>
   469           Note that the rate at which the user agent sends <a>touchmove</a>
   543           events is implementation-defined, and may depend on hardware
   470           events is implementation-defined, and may depend on hardware
   544           capabilities and other implementation details.
   471           capabilities and other implementation details.
   545         </p>
   472         </p>
   546 
   473 
   547         <p>
   474         <p>
   548           If the <a>preventDefault</a> method is called on the <em>first</em>
   475           If the <a>preventDefault</a> method is called on the <em>first</em>
   549           <a>touchmove</a> event of an <a>active touch point</a>, it should
   476           <a>touchmove</a> event of an <a>active touch point</a>, it should
   550           prevent any default action caused by any <a>touchmove</a> event
   477           prevent any default action caused by any <a>touchmove</a> event
   551           associated with the same <a>active touch point</a>, such as scrolling.
   478           associated with the same <a>active touch point</a>, such as scrolling.
   552         </p>
       
   553       </section>
       
   554 
       
   555       <section>
       
   556         <h3 id="event-touchenter">The <dfn class="event">touchenter</dfn> event</h3>
       
   557         <p>
       
   558           A user agent must dispatch this event type to indicate when a
       
   559           <a>touch point</a> moves onto the interactive area defined by a DOM
       
   560           element.  Events of this type must not bubble.
       
   561         </p>
       
   562       </section>
       
   563 
       
   564       <section>
       
   565         <h3 id="event-touchleave">The <dfn class="event">touchleave</dfn> event</h3>
       
   566         <p>
       
   567           A user agent must dispatch this event type to indicate when a
       
   568           <a>touch point</a> moves off the interactive area defined by a DOM
       
   569           element.  Events of this type must not bubble.
       
   570         </p>
   479         </p>
   571       </section>
   480       </section>
   572 
   481 
   573       <section>
   482       <section>
   574         <h3 id="event-touchcancel">The <dfn class="event">touchcancel</dfn> event</h3>
   483         <h3 id="event-touchcancel">The <dfn class="event">touchcancel</dfn> event</h3>
   606             <dt>long identifier</dt> <dd></dd>
   515             <dt>long identifier</dt> <dd></dd>
   607             <dt>long pageX</dt> <dd></dd>
   516             <dt>long pageX</dt> <dd></dd>
   608             <dt>long pageY</dt> <dd></dd>
   517             <dt>long pageY</dt> <dd></dd>
   609             <dt>long screenX</dt> <dd></dd>
   518             <dt>long screenX</dt> <dd></dd>
   610             <dt>long screenY</dt> <dd></dd>
   519             <dt>long screenY</dt> <dd></dd>
   611             <dt>optional long radiusX</dt> <dd></dd>
       
   612             <dt>optional long radiusY</dt> <dd></dd>
       
   613             <dt>optional float rotationAngle</dt> <dd></dd>
       
   614             <dt>optional float force</dt> <dd></dd>
       
   615           </dl>
   520           </dl>
   616         </dd>
   521         </dd>
   617 
   522 
   618         <dt>TouchList createTouchList()</dt>
   523         <dt>TouchList createTouchList()</dt>
   619         <dd>
   524         <dd>