2Dapi; hixie: Make it easier to do hit testing on canvas (whatwg r7029)

2Dapi; hixie: Make it easier to do hit testing on canvas (whatwg r7029)

http://dev.w3.org/cvsweb/html5/2dcontext/Overview.html?r1=1.131&r2=1.132&f=h
http://html5.org/tools/web-apps-tracker?from=7028&to=7029

===================================================================
RCS file: /sources/public/html5/2dcontext/Overview.html,v
retrieving revision 1.131
retrieving revision 1.132
diff -u -d -r1.131 -r1.132
--- Overview.html 19 Mar 2012 22:29:43 -0000 1.131
+++ Overview.html 26 Mar 2012 05:11:26 -0000 1.132
@@ -606,12 +606,13 @@
  <li><a href="#drawing-text-to-the-canvas"><span class="secno">11 </span>Drawing text to the canvas</a></li>
  <li><a href="#drawing-paths-to-the-canvas"><span class="secno">12 </span>Drawing paths to the canvas</a></li>
  <li><a href="#drawing-images-to-the-canvas"><span class="secno">13 </span>Drawing images to the canvas</a></li>
- <li><a href="#pixel-manipulation"><span class="secno">14 </span>Pixel manipulation</a></li>
- <li><a href="#compositing"><span class="secno">15 </span>Compositing</a></li>
- <li><a href="#shadows"><span class="secno">16 </span>Shadows</a></li>
- <li><a href="#drawing-model"><span class="secno">17 </span>Drawing model</a></li>
- <li><a href="#best-practices"><span class="secno">18 </span>Best practices</a></li>
- <li><a href="#examples"><span class="secno">19 </span>Examples</a></li>
+ <li><a href="#hit-regions"><span class="secno">14 </span>Hit regions</a></li>
+ <li><a href="#pixel-manipulation"><span class="secno">15 </span>Pixel manipulation</a></li>
+ <li><a href="#compositing"><span class="secno">16 </span>Compositing</a></li>
+ <li><a href="#shadows"><span class="secno">17 </span>Shadows</a></li>
+ <li><a href="#drawing-model"><span class="secno">18 </span>Drawing model</a></li>
+ <li><a href="#best-practices"><span class="secno">19 </span>Best practices</a></li>
+ <li><a href="#examples"><span class="secno">20 </span>Examples</a></li>
  <li><a class="no-num" href="#references">References</a></li>
  <li><a class="no-num" href="#acknowledgements">Acknowledgements</a></ol>
 
@@ -708,6 +709,9 @@
   void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>((<span>HTMLImageElement</span> or <span>HTMLCanvasElement</span> or <span>HTMLVideoElement</span>) image, double dx, double dy, double dw, double dh);
   void <a href="#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>((<span>HTMLImageElement</span> or <span>HTMLCanvasElement</span> or <span>HTMLVideoElement</span>) image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);
 
+  // hit regions
+  void <a href="#dom-context-2d-addhitregion" title="dom-context-2d-addHitRegion">addHitRegion</a>(<a href="#hitregionoptions">HitRegionOptions</a> options);
+
   // pixel manipulation
   <a href="#imagedata">ImageData</a> <a href="#dom-context-2d-createimagedata" title="dom-context-2d-createImageData">createImageData</a>(double sw, double sh);
   <a href="#imagedata">ImageData</a> <a href="#dom-context-2d-createimagedata" title="dom-context-2d-createImageData">createImageData</a>(<a href="#imagedata">ImageData</a> imagedata);
@@ -765,6 +769,19 @@
   readonly attribute double <a href="#dom-textmetrics-width" title="dom-textmetrics-width">width</a>;
 };
 
+dictionary <dfn id="hitregionoptions">HitRegionOptions</dfn> {
+  <a href="#path">Path</a>? <span title="dom-HitRegionOptions-path">path</span> = null;
+  <span>SVGMatrix</span>? <span title="dom-HitRegionOptions-transform">transform</span> = null;
+  <span>DOMString</span> <span title="dom-HitRegionOptions-id">id</span> = '';
+  <span>DOMString</span>? <span title="dom-HitRegionOptions-parentID">parentID</span> = null;
+  <span>DOMString</span> <span title="dom-HitRegionOptions-cursor">cursor</span> = 'inherit';
+  // for control-backed regions:
+  <span>Element</span>? <span title="dom-HitRegionOptions-control">control</span> = null;
+  // for unbacked regions:
+  <span>DOMString</span>? <span title="dom-HitRegionOptions-label">label</span> = null;
+  <span>DOMString</span>? <span title="dom-HitRegionOptions-role">role</span> = null;
+};
+
 interface <dfn id="imagedata">ImageData</dfn> {
   readonly attribute unsigned long <a href="#dom-imagedata-width" title="dom-imagedata-width">width</a>;
   readonly attribute unsigned long <a href="#dom-imagedata-height" title="dom-imagedata-height">height</a>;
@@ -2695,9 +2712,10 @@
   generating the repeated pattern. When rendered, however, patterns
   must actually be painted only where the stroking or filling effect
   requires that they be drawn, and the repeated pattern must be
-  affected by the current transformation matrix. Pixels not covered by
-  the repeating pattern (if the <code>repeat</code> string was not
-  specified) must be transparent black.</p>
+  affected by the <a href="#transformations" title="dom-context-2d-transformation">current
+  transformation matrix</a>. Pixels not covered by the repeating
+  pattern (if the <code>repeat</code> string was not specified) must
+  be transparent black.</p>
 
   <p>If the original image data is a bitmap image, the value painted
   at a point in the area of the repetitions is computed by filtering
@@ -2794,10 +2812,19 @@
 
   </dl><div class="impl">
 
-  <p>The <dfn id="dom-context-2d-clearrect" title="dom-context-2d-clearRect"><code>clearRect(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</code></dfn> method must clear the pixels in the
-  specified rectangle that also intersect the current clipping region
-  to a fully transparent black, erasing any previous image. If either
-  height or width are zero, this method has no effect.</p>
+  <p>The <dfn id="dom-context-2d-clearrect" title="dom-context-2d-clearRect"><code>clearRect(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</code></dfn> method must run the following steps:</p>
+
+  <ol><li><p>Let <var title="">pixels</var> be the set of pixels in
+   the specified rectangle that also intersect the current clipping
+   region.</li>
+
+   <li><p>Clear the pixels in <var title="">pixels</var> to a fully
+   transparent black, erasing any previous image.</li>
+
+   <li><p><a href="#clear-regions-that-cover-the-pixels">Clear regions that cover the pixels</a> in <var title="">pixels</var> in the <code>canvas</code> element.</li>
+
+  </ol><p class="note">If either height or width are zero, this method has
+  no effect, since the set of pixels would be empty.</p>
 
   <p>The <dfn id="dom-context-2d-fillrect" title="dom-context-2d-fillRect"><code>fillRect(<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</code></dfn> method must paint the specified
   rectangular area using the <code title="dom-context-2d-fillStyle"><a href="#dom-context-2d-fillstyle">fillStyle</a></code>. If either height
@@ -3060,8 +3087,8 @@
   provided, or the <a href="#current-default-path">current default path</a> otherwise.</p>
 
   <p>When the intended path is a <code><a href="#path">Path</a></code> object, the
-  coordinates of its subpaths must be transformed according to the
-  <code><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#transformations" title="dom-context-2d-transformation">current transformation
+  coordinates and lines of its subpaths must be transformed according
+  to the <code><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object's <a href="#transformations" title="dom-context-2d-transformation">current transformation
   matrix</a> when used by these methods (without affecting the
   <code><a href="#path">Path</a></code> object itself). When the intended path is the
   <a href="#current-default-path">current default path</a>, it is not affected by the
@@ -3458,8 +3485,626 @@
   </div>
 
 
+  <h2 id="hit-regions"><span class="secno">14 </span>Hit regions</h2>
 
-  <h2 id="pixel-manipulation"><span class="secno">14 </span><dfn>Pixel manipulation</dfn></h2>
+  <p>Each <code>canvas</code> element whose <span>primary
+  context</span> is a <code><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object
+  must have a <dfn id="hit-region-list">hit region list</dfn> associated with its
+  bitmap.</p>
+
+  <p>The <a href="#hit-region-list">hit region list</a> is a list of <a href="#hit-region" title="hit
+  region">hit regions</a>.</p>
+
+  <p>Each <dfn id="hit-region">hit region</dfn> consists of the following
+  information:</p>
+
+  <ul><li><p>A <dfn id="hit-region-s-set-of-pixels" title="hit region's set of pixels">set of
+   pixels</dfn> on the <code>canvas</code> element's bitmap for which
+   this region is responsible.</li>
+
+   <li><p>A <dfn id="hit-region-s-bounding-circumference" title="hit region's bounding circumference">bounding
+   circumference</dfn> on the <code>canvas</code> element's bitmap
+   that surrounds the <a href="#hit-region-s-set-of-pixels">hit region's set of pixels</a> as they
+   stood when it was created.</li>
+
+   <li><p>Optionally, a non-empty string representing an <dfn id="hit-region-s-id" title="hit region's ID">ID</dfn> for distinguishing the region
+   from others.</li>
+
+   <li><p>Optionally, a reference to another region that acts as the
+   <dfn id="hit-region-s-parent" title="hit region's parent">parent</dfn> for this
+   one.</li>
+
+   <li><p>A count of regions that have this one as their <a href="#hit-region-s-parent" title="hit region's parent">parent</a>, known as the <dfn id="hit-region-s-child-count">hit
+   region's child count</dfn>.</li>
+
+   <li><p>A <dfn id="hit-region-s-cursor-specification" title="hit region's cursor specification">cursor
+   specification</dfn>, in the form of either a CSS cursor value, or
+   the string "<code title="">inherit</code>" meaning that the cursor
+   of the <a href="#hit-region-s-parent">hit region's parent</a>, if any, or of the
+   <code>canvas</code> element, if not, is to be used
+   instead.</li>
+
+   <li>
+
+    <p>Optionally, either a <a href="#hit-region-s-control" title="hit region's
+    control">control</a>, or an <a href="#hit-region-s-unbacked-region-description" title="hit region's unbacked
+    region description">unbacked region description</a>.</p>
+
+    <p>A <dfn id="hit-region-s-control" title="hit region's control">control</dfn> is just a
+    reference to an <code>Element</code> node, to which, in certain
+    conditions, the user agent will route events, and from which the
+    user agent will determine the state of the hit region for the
+    purposes of accessibility tools.</p>
+
+    <p>An <dfn id="hit-region-s-unbacked-region-description" title="hit region's unbacked region
+    description">unbacked region description</dfn> consists of the
+    following:</p>
+
+    <ul class="brief"><li><p>Optionally, a <dfn id="hit-region-s-label" title="hit region's
+     label">label</dfn>.</p>
+
+     <li><p>An <dfn id="hit-region-s-aria-role" title="hit region's ARIA role">ARIA role</dfn>,
+     which, if the <a href="#hit-region-s-unbacked-region-description" title="hit region's unbacked region
+     description">unbacked region description</a> also has a label,
+     could be the empty string.</li>
+
+    </ul></li>
+
+  </ul><dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-addHitRegion"><a href="#dom-context-2d-addhitregion">addHitRegion</a></code>(<var title="">options</var>)</dt>
+
+   <dd>
+
+    <p>Adds a hit region to the canvas bitmap. The argument is an
+    object with the following members:</p>
+
+    <dl><dt><code title="dom-HitRegionOptions-path">path</code> (default null)
+
+     <dd>A <code><a href="#path">Path</a></code> object that describes the pixels that
+     form part of the region. If this member is not provided or is set
+     to null, the <a href="#current-default-path">current default path</a> is used
+     instead.</dd>
+
+     <dt><code title="dom-HitRegionOptions-transform">transform</code> (default null)
+
+     <dd>An <code>SVGMatrix</code> object that describes a
+     transformation to apply to the path described by the <code title="dom-HitRegionOptions-path">path</code> member.</dd>
+
+     <dt><code title="dom-HitRegionOptions-id">id</code> (default empty string)
+
+     <dd>The ID to use for this region. This is used in
+     <code>MouseEvent</code> events on the <code>canvas</code> (<code title="dom-MouseEvent-region"><a href="#dom-mouseevent-region">event.region</a></code>) and as a way
+     to reference this region in later calls to <code title="dom-context-2d-addHitRegion"><a href="#dom-context-2d-addhitregion">addHitRegion()</a></code>.</dd>
+
+     <dt><code title="dom-HitRegionOptions-parentID">parentID</code> (default null)
+
+     <dd>The ID of the parent region, for purposes of navigation by
+     accessibility tools and for cursor fallback.</dd>
+
+     <dt><code title="dom-HitRegionOptions-cursor">cursor</code> (default "<code title="">inherit</code>")
+
+     <dd>The cursor to use when the mouse is over this region. The
+     value "<code title="">inherit</code>" means to use the cursor for
+     the parent region (as specified by the <code title="dom-HitRegionOptions-parentID">parentID</code> member), if
+     any, or to use the <code>canvas</code> element's cursor if the
+     region has no parent.</dd>
+
+     <dt><code title="dom-HitRegionOptions-control">control</code> (default null)
+
+     <dd>An element (that is a descendant of the <code>canvas</code>)
+     to which events are to be routed, and which accessibility tools
+     are to use as a surrogate for describing and interacting with
+     this region.</dd>
+
+     <dt><code title="dom-HitRegionOptions-label">label</code> (default null)
+
+     <dd>A text label for accessibility tools to use as a description
+     of this region, if there is no control.</dd>
+
+     <dt><code title="dom-HitRegionOptions-role">role</code> (default null)
+
+     <dd>An ARIA role for accessibility tools to use to determine how
+     to represent this region, if there is no control.</dd>
+
+    </dl><p>Hit regions can be used for a variety of purposes:</p>
+
+    <ul><li>With an ID, they can make hit detection easier by having the
+     user agent check which region the mouse is over and include the
+     ID in the mouse events.</li>
+
+     <li>With a control, they can make routing events to DOM elements
+     automatic, allowing e.g. clicks on a canvas to automatically
+     submit a form via a <code>button</code> element.</li>
+
+     <li>With a label, they can make it easier for users to explore a
+     canvas without seeing it, e.g. by touch on a mobile device.</li>
+
+     <li>With a cursor, they can make it easier for different regions
+     of the canvas to have different cursors, with the user agent
+     automatically switching between them.</li>
+
+    </ul></dd>
+
+  </dl><div class="impl">
+
+  <p>A <a href="#hit-region">hit region</a> <var title="">A</var> is an
+  <dfn id="ancestor-region">ancestor region</dfn> of a <a href="#hit-region">hit region</a> <var title="">B</var> if <var title="">B</var> has a <a href="#hit-region-s-parent" title="hit
+  region's parent">parent</a> and its <a href="#hit-region-s-parent" title="hit region's
+  parent">parent</a> is either <var title="">A</var> or another
+  <a href="#hit-region">hit region</a> for which <var title="">A</var> is an
+  <a href="#ancestor-region">ancestor region</a>.</p>
+
+  <p><dfn id="the-region-identified-by-the-id">The region identified by the ID</dfn> <var title="">ID</var> in a <code>canvas</code> element <var title="">ancestor</var> is the value returned by the following
+  algorithm (which can return a <a href="#hit-region">hit region</a> or
+  nothing):</p>
+
+  <ol><li><p>If <var title="">ID</var> is null, return nothing and abort
+   these steps.</li>
+
+   <li><p>Let <var title="">list</var> be the <a href="#hit-region-list">hit region
+   list</a> associated with <var title="">ancestor</var>'s
+   bitmap.</li>
+
+   <li><p>If there is a <a href="#hit-region">hit region</a> in <var title="">list</var> whose <a href="#hit-region-s-id" title="hit region's ID">ID</a>
+   is a <span>case-sensitive</span> match for <var title="">ID</var>,
+   then return that <a href="#hit-region">hit region</a> and abort these
+   steps.</li>
+
+   <li><p>Otherwise, return nothing.</li>
+
+  </ol><p><dfn id="the-region-representing-the-control">The region representing the control</dfn> <var title="">control</var> for a <code>canvas</code> element <var title="">ancestor</var> is the value returned by the following
+  algorithm (which can return a <a href="#hit-region">hit region</a> or
+  nothing):</p>
+
+  <ol><li><p>If <var title="">control</var> is not a descendant of <var title="">ancestor</var>, then return nothing and abort these
+   steps.</li>
+
+   <li><p>Let <var title="">list</var> be the <a href="#hit-region-list">hit region
+   list</a> associatd with <var title="">ancestor</var>'s
+   bitmap.</li>
+
+   <li><p>If there is a <a href="#hit-region">hit region</a> in <var title="">list</var> whose <a href="#hit-region-s-control" title="hit region's
+   control">control</a> is <var title="">control</var>, then
+   return that <a href="#hit-region">hit region</a> and abort these
+   steps.</li>
+
+   <li><p>Otherwise, return nothing.</li>
+
+  </ol><p><dfn id="the-control-represented-by-a-region">The control represented by a region</dfn> <var title="">region</var> for a <code>canvas</code> element <var title="">ancestor</var> is the value returned by the following
+  algorithm (which can return an element or nothing):</p>
+
+  <ol><li><p>If <var title="">region</var> has no <a href="#hit-region-s-control" title="hit
+   region's control">control</a>, return nothing and abort these
+   steps.</li>
+
+   <li><p>Let <var title="">control</var> be <var title="">region</var>'s <a href="#hit-region-s-control" title="hit region's
+   control">control</a>.</li>
+
+   <li><p>If <var title="">control</var> is not a descendant of <var title="">ancestor</var>, then return nothing and abort these
+   steps.</li>
+
+   <li><p>Otherwise, return <var title="">control</var>.</li>
+
+  </ol><p><dfn id="the-cursor-for-a-hit-region">The cursor for a hit region</dfn> <var title="">region</var> of a <code>canvas</code> element <var title="">ancestor</var> is the value returned by the following
+  algorithm:</p>
+
+  <ol><li><p><i>Loop</i>: If <var title="">region</var> has a <a href="#hit-region-s-cursor-specification" title="hit region's cursor specification">cursor
+   specification</a> other than "<code title="">inherit</code>",
+   then return that <a href="#hit-region-s-cursor-specification">hit region's cursor specification</a>
+   and abort these steps.</li>
+
+   <li><p>If <var title="">region</var> has a <a href="#hit-region-s-parent" title="hit
+   region's parent">parent</a>, then let <var title="">region</var> be that <a href="#hit-region-s-parent">hit region's parent</a>,
+   and return to the step labeled <i>loop</i>.</li>
+
+   <li><p>Otherwise, return the used value of the 'cursor' property
+   for the <code>canvas</code> element. <a href="#refsCSSUI">[CSSUI]</a></li>
+
+  </ol><p><dfn id="the-region-for-a-pixel">The region for a pixel</dfn> <var title="">pixel</var> on a
+  <code>canvas</code> element <var title="">ancestor</var> is the
+  value returned by the following algorithm (which can return a
+  <a href="#hit-region">hit region</a> or nothing):</p>
+
+  <ol><li><p>Let <var title="">list</var> be the <a href="#hit-region-list">hit region
+   list</a> associatd with <var title="">ancestor</var>'s
+   bitmap.</li>
+
+   <li><p>If there is a <a href="#hit-region">hit region</a> in <var title="">list</var> whose <a href="#hit-region-s-set-of-pixels" title="hit region's set of
+   pixels">set of pixels</a> contains <var title="">pixel</var>,
+   then return that <a href="#hit-region">hit region</a> and abort these
+   steps.</li>
+
+   <li><p>Otherwise, return nothing.</li>
+
+  </ol><p>To <dfn id="clear-regions-that-cover-the-pixels">clear regions that cover the pixels</dfn> <var title="">pixels</var> on a <code>canvas</code> element <var title="">ancestor</var>, the user agent must run the following
+  steps:</p>
+
+  <ol><li><p>Let <var title="">list</var> be the <a href="#hit-region-list">hit region
+   list</a> associatd with <var title="">ancestor</var>'s
+   bitmap.</li>
+
+   <li><p>Remove all pixels in <var title="">pixels</var> from the
+   <a href="#hit-region-s-set-of-pixels" title="hit region's set of pixels">set of pixels</a> of
+   each <a href="#hit-region">hit region</a> in <var title="">list</var>.</li>
+
+   <li><p><i>Loop</i>: Let <var title="">victim</var> be the first
+   <a href="#hit-region">hit region</a> in <var title="">list</var> to have an
+   empty <a href="#hit-region-s-set-of-pixels" title="hit region's set of pixels">set of
+   pixels</a> and a zero <a href="#hit-region-s-child-count" title="hit region's child
+   count">child count</a>, if any. If there is no such <a href="#hit-region">hit
+   region</a>, abort these steps.</li>
+
+   <li><p>If <var title="">victim</var> has a <a href="#hit-region-s-parent" title="hit
+   region's parent">parent</a>, then decrement that <a href="#hit-region-s-child-count">hit
+   region's child count</a> by one.</li>
+
+   <li><p>Remove <var title="">victim</var> from <var title="">list</var>.</li>
+
+   <li><p>Jump back to the step labeled <i>loop</i>.</li>
+
+  </ol><p class="note">Adding a new region and calling <code title="dom-context-2d-clearRect"><a href="#dom-context-2d-clearrect">clearRect()</a></code> are the three
+  ways this clearing algorithm can be invoked. Resizing the canvas
+  also clears the <a href="#hit-region-list">hit region list</a> (since it clears the
+  canvas back to its initial state).</p>
+
+  <hr><p>When the <dfn id="dom-context-2d-addhitregion" title="dom-context-2d-addHitRegion"><code>addHitRegion()</code></dfn>
+  method is invoked, the user agent must run the following steps:</p>
+
+  <ol><li><p>Let <var title="">arguments</var> be the dictionary object
+   provided as the method's argument.</li>
+
+   <li><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-path">path</code> member is not null,
+   let <var title="">source path</var> be the <code title="dom-HitRegionOptions-path">path</code> member's value.
+   Otherwise, let it be the <code><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>
+   object's <a href="#current-default-path">current default path</a>.</li>
+
+   <li><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-path">path</code> member is null, but
+   the <code title="dom-HitRegionOptions-transform">transform</code>
+   member is not, then throw a <code>NotSupportedError</code>
+   exception and abort these steps.</li>
+
+   <li><p>Transform all the coordinates and lines in <var title="">source path</var> by the transform matrix given by the
+   <var title="">arguments</var> object's <code title="dom-HitRegionOptions-transform">transform</code> member, if
+   it is not null.</li>
+
+   <li><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-id">id</code> member is the
+   empty string, let it be null instead.</li>
+
+   <li><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-id">id</code> member is not null, then
+   let <var title="">previous region for this ID</var> be <a href="#the-region-identified-by-the-id">the
+   region identified by the ID</a> given by the <code title="dom-HitRegionOptions-id">id</code> member's value in this
+   <code>canvas</code> element, if any. If the <code title="dom-HitRegionOptions-id">id</code> member is null or no such
+   region currently exists, let <var title="">previous region for this
+   ID</var> be null.</li>
+
+   <li><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-parent">parent</code> member is the
+   empty string, let it be null instead.</li>
+
+   <li><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-parent">parent</code> member is not
+   null, then let <var title="">parent region</var> be <a href="#the-region-identified-by-the-id">the
+   region identified by the ID</a> given by the <code title="dom-HitRegionOptions-parent">parent</code> member's value in
+   this <code>canvas</code> element, if any. If the <code title="dom-HitRegionOptions-parent">parent</code> member is null or
+   no such region currently exists, let <var title="">parent
+   region</var> be null.</li>
+
+   <li><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-label">label</code> member is the
+   empty string, let it be null instead.</li>
+
+   <li>
+
+    <p>If any of the following conditions are met, throw a
+    <code>NotSupportedError</code> exception and abort these
+    steps.</p>
+
+    <ul class="brief"><li>The <var title="">arguments</var> object's <code title="dom-HitRegionOptions-path">path</code> member is null, but
+     its <code title="dom-HitRegionOptions-transform">transform</code>
+     member is not.</li>
+
+     <li>The <var title="">arguments</var> object's <code title="dom-HitRegionOptions-control">control</code> and <code title="dom-HitRegionOptions-label">label</code> members are both
+     non-null.</li>
+
+     <li>The <var title="">arguments</var> object's <code title="dom-HitRegionOptions-control">control</code> and <code title="dom-HitRegionOptions-role">role</code> members are both
+     non-null.</li>
+
+     <li>The <var title="">arguments</var> object's <code title="dom-HitRegionOptions-role">role</code> member's value is
+     the empty string, and the <code title="dom-HitRegionOptions-label">label</code> member's value is
+     either null or the empty string.</li>
+
+     <li>The <a href="#path">path</a> <var title="">source path</var>
+     describes a shape with no pixels.</li>
+
+     <li>The <var title="">arguments</var> object's <code title="dom-HitRegionOptions-control">control</code> member is not
+     null but is neither an <code>a</code> element that
+     <span>represents</span> a <span>hyperlink</span>, a
+     <code>button</code> element, an <code>input</code> element whose
+     <code title="attr-input-type">type</code> attribute is in one of
+     the <span title="attr-input-type-checkbox">Checkbox</span> or
+     <span title="attr-input-type-radio">Radio Button</span> states,
+     nor an <code>input</code> element that is a <span title="concept-button">button</span>.</li>
+
+     <li>The <var title="">parent region</var> is not null but has a
+     <a href="#hit-region-s-control" title="hit region's control">control</a>.</li>
+
+     <li>The <var title="">previous region for this ID</var> is the
+     same <a href="#hit-region">hit region</a> as the <var title="">parent
+     region</var>.</li>
+
+     <li>The <var title="">previous region for this ID</var> is an
+     <a href="#ancestor-region">ancestor region</a> of the <var title="">parent
+     region</var>.</li>
+
+    </ul></li>
+
+   <li><p>If the <code title="dom-HitRegionOptions-parent">parent</code> member is not
+   null but <var title="">parent region</var> is null, then throw a
+   <code>NotFoundError</code> exception and abort these
+   steps.</li>
+
+   <li>
+
+    <p>If any of the following conditions are met, throw a
+    <code>SyntaxError</code> exception and abort these
+    steps.</p>
+
+    <ul class="brief"><li>The <var title="">arguments</var> object's <code title="dom-HitRegionOptions-cursor">cursor</code> member is not
+     null but is neither an <span>ASCII case-insensitive</span> match
+     for the string "<code title="">inherit</code>", nor a valid CSS
+     'cursor' property value. <a href="#refsCSSUI">[CSSUI]</a></li>
+
+     <li>The <var title="">arguments</var> object's <code title="dom-HitRegionOptions-role">role</code> member is not null
+     but its value is not an <span>ordered set of unique
+     space-separated tokens</span> whose tokens are all
+     <span>case-sensitive</span> matches for names of non-abstract
+     WAI-ARIA roles. <a href="#refsARIA">[ARIA]</a></li>
+
+    </ul></li>
+
+   <li>
+
+    <p>Let <var title="">region</var> be a newly created <a href="#hit-region">hit
+    region</a>, with its information configured as follows:</p>
+
+    <dl><dt><a href="#hit-region-s-set-of-pixels">Hit region's set of pixels</a>
+
+     <dd><p>The pixels contained in <var title="">source path</var>.
+
+
+     <dt><a href="#hit-region-s-bounding-circumference">Hit region's bounding circumference</a>
+
+     <dd><p>A user-agent-defined shape that wraps the pixels contained
+     in <var title="">source path</var>. (In the simplest case, this
+     can just be the bounding rectangle; this specification allows it
+     to be any shape in order to allow other interfaces.)
+
+
+     <dt><a href="#hit-region-s-id">Hit region's ID</a>
+
+     <dd><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-id">id</code> member is not null: the
+     value of the <code title="dom-HitRegionOptions-id">id</code>
+     member. Otherwise, <var title="">region</var> has no <a href="#hit-region-s-id" title="hit region's id">id</a>.
+
+
+     <dt><a href="#hit-region-s-parent">Hit region's parent</a>
+
+     <dd><p>If <var title="">parent region</var> is not null: <var title="">parent region</var>. Otherwise, <var title="">region</var> has no <a href="#hit-region-s-parent" title="hit region's
+     parent">parent</a>.
+
+
+     <dt><a href="#hit-region-s-child-count">Hit region's child count</a>
+
+     <dd><p>Initially zero.
+
+
+     <dt><a href="#hit-region-s-cursor-specification">Hit region's cursor specification</a>
+
+     <dd><p>If <var title="">parent region</var> is not null: <var title="">parent region</var>. Otherwise, <var title="">region</var> has no <a href="#hit-region-s-parent" title="hit region's
+     parent">parent</a>.
+
+
+     <dt><a href="#hit-region-s-control">Hit region's control</a>
+
+     <dd><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-control">control</code> member is not
+     null: the value of the <code title="dom-HitRegionOptions-control">control</code> member.
+     Otherwise, <var title="">region</var> has no <a href="#hit-region-s-control" title="hit
+     region's control">control</a>.
+
+
+     <dt><a href="#hit-region-s-label">Hit region's label</a>
+
+     <dd><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-label">label</code> member is not
+     null: the value of the <code title="dom-HitRegionOptions-label">label</code> member.
+     Otherwise, <var title="">region</var> has no <a href="#hit-region-s-label" title="hit
+     region's label">label</a>.
+
+
+     <dt><a href="#hit-region-s-aria-role">Hit region's ARIA role</a>
+
+     <dd><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-role">role</code> member is not null:
+     the value of the <code title="dom-HitRegionOptions-role">role</code> member (which might
+     be the empty string). Otherwise, if the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-label">label</code> member is not
+     null: the empty string. Otherwise, <var title="">region</var> has
+     no <a href="#hit-region-s-aria-role" title="hit region's ARIA role">ARIA role</a>.
+
+
+    </dl></li>
+
+   <li>
+
+    <p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-cursor">cursor</code> member is not
+    null, then act as if a CSS rule for the <code>canvas</code>
+    element setting its 'cursor' property had been seen, whose value
+    was the <a href="#hit-region-s-cursor-specification">hit region's cursor specification</a>.</p>
+
+    <p class="note">For example, if the user agent prefetches cursor
+    values, this would cause that to happen in response to an
+    appropriately-formed <code title="dom-context-2d-addHitRegion"><a href="#dom-context-2d-addhitregion">addHitRegion()</a></code>
+    call.</p>
+
+   </li>
+
+   <li><p>If the <var title="">arguments</var> object's <code title="dom-HitRegionOptions-control">control</code> member is not
+   null, then let <var title="">previous region for the control</var>
+   be <a href="#the-region-representing-the-control">the region representing the control</a> given by the
+   <code title="dom-HitRegionOptions-control">control</code> member's
+   value for this <code>canvas</code> element, if any. If the <code title="dom-HitRegionOptions-control">control</code> member is null
+   or no such region currently exists, let <var title="">previous
+   region for the control</var> be null.</li>
+
+   
+
+   <li><p>If there is a <var title="">previous region with this
+   control</var>, remove it from the <code>canvas</code> element's
+   <a href="#hit-region-list">hit region list</a>; then, if it had a <a href="#hit-region-s-parent" title="hit
+   region's parent">parent</a> region, decrement that <a href="#hit-region-s-child-count">hit
+   region's child count</a> by one.</li> 
+
+   <li><p>If there is a <var title="">previous region with this
+   ID</var>, remove it, and all <a href="#hit-region" title="hit region">hit
+   regions</a> for which it is an <a href="#ancestor-region">ancestor region</a>,
+   from the <code>canvas</code> element's <a href="#hit-region-list">hit region
+   list</a>; then, if it had a <a href="#hit-region-s-parent" title="hit region's
+   parent">parent</a> region, decrement that <a href="#hit-region-s-child-count">hit region's
+   child count</a> by one.</li> 
+
+   <li><p>If there is a <var title="">parent region</var>, increment
+   its <a href="#hit-region-s-child-count">hit region's child count</a> by one.</li>
+
+   <li><p><a href="#clear-regions-that-cover-the-pixels">Clear regions that cover the pixels</a> in <var title="">region</var>'s <a href="#hit-region-s-set-of-pixels" title="hit region's set of
+   pixels">set of pixels</a> on this <code>canvas</code>
+   element.</li> 
+
+   <li><p>Add <var title="">region</var> to the <code>canvas</code>
+   element's <a href="#hit-region-list">hit region list</a>.</li>
+
+  </ol></div>
+
+  <hr><p>The <code>MouseEvent</code> interface is extended to support hit
+  regions:</p>
+
+  <pre class="idl">partial interface <span>MouseEvent</span> {
+  readonly attribute DOMString? <a href="#dom-mouseevent-region" title="dom-MouseEvent-region">region</a>;
+};
+
+partial dictionary <span>MouseEventInit</span> {
+  DOMString? region;
+};</pre>
+
+  <dl class="domintro"><dt><var title="">event</var> . <code title="dom-MouseEvent-region"><a href="#dom-mouseevent-region">region</a></code></dt>
+
+   <dd>
+
+    <p>If the mouse was over a <a href="#hit-region">hit region</a>, then this returns the <a href="#hit-region-s-id">hit region's ID</a>, if it has one.</p>
+
+    <p>Otherwise, returns null.</p>
+
+   </dd>
+
+  </dl><div class="impl">
+
+  <p>The <dfn id="dom-mouseevent-region" title="dom-MouseEvent-region"><code>region</code></dfn>
+  attribute on <code>MouseEvent</code> objects must return the value
+  it was initialized to. When the object is created, this attribute
+  must be initialized to null. It represents the <a href="#hit-region-s-id">hit region's
+  ID</a> if the mouse was over a hit region when the event was
+  fired.</p>
+
+  <p>When a <code>MouseEvent</code> is to be fired at a
+  <code>canvas</code> element by the user agent in response to a
+  pointing device action, the user agent must instead follow these
+  steps. If these steps say to <i>act as normal</i>, that means that
+  the event must be fired as it would have had these requirements not
+  been applied.</p>
+
+  <ol><li><p>If the pointing device is not indicating a pixel on the
+   <code>canvas</code>, act as normal and abort these steps.</li>
+
+   <li><p>Let <var title="">pixel</var> be the pixel indicated by the
+   pointing device.</li>
+
+   <li><p>Let <var title="">region</var> be the <a href="#hit-region">hit
+   region</a> that is <a href="#the-region-for-a-pixel" title="the region for a pixel">the
+   region for the pixel</a> <var title="">pixel</var> on this
+   <code>canvas</code> element, if any.</li>
+
+   <li><p>If there is no <var title="">region</var>, then act as
+   normal and abort these steps.</li>
+
+   <li><p>Let <var title="">id</var> be the <var title="">region</var>'s <a href="#hit-region-s-id" title="hit region's ID">ID</a>, if
+   any.</li>
+
+   <li><p>If there is an <var title="">id</var>, then initialize the
+   event object's <code title="dom-MouseEvent-region"><a href="#dom-mouseevent-region">region</a></code>
+   attribute to <var title="">id</var>.</li>
+
+   <li><p>Let <var title="">control</var> be the <var title="">region</var>'s <a href="#hit-region-s-control" title="hit region's
+   control">control</a>, if any.</li>
+
+   <li><p>If there is a <var title="">control</var>, then target the
+   event object at <var title="">control</var> instead of the
+   <code>canvas</code> element.</li>
+
+   <li><p>Continue dispatching the event, but with the updated event
+   object and target as given in the above steps.</li>
+
+  </ol><hr><p>When a user's pointing device cursor is positioned over a
+  <code>canvas</code> element, user agents should render the pointing
+  device cursor according to the cursor specification described by
+  <a href="#the-cursor-for-a-hit-region" title="the cursor for a hit region">the cursor for the hit
+  region</a> that is <a href="#the-region-for-a-pixel" title="the region for a pixel">the
+  region for the pixel</a> that the pointing device designates.</p>
+
+  <hr><p>User agents are encouraged to make use of the information present
+  in a <code>canvas</code> element's <a href="#hit-region-list">hit region list</a> to
+  improve the accessibility of <code>canvas</code> elements.</p>
+
+  <p>Each <a href="#hit-region">hit region</a> should be handled in a fashion
+  equivalent to a node in a virtual DOM tree rooted at the
+  <code>canvas</code> element. The hierarchy of this virtual DOM tree
+  must match the hierarchy of the <a href="#hit-region" title="hit region">hit
+  regions</a>, as described by the <a href="#hit-region-s-parent" title="hit region's
+  parent">parent</a> of each region. Regions without a <a href="#hit-region-s-parent" title="hit region's parent">parent</a> must be treated as
+  children of the <code>canvas</code> element for the purpose of this
+  virtual DOM tree. For each node in such a DOM tree, the <a href="#hit-region-s-bounding-circumference">hit
+  region's bounding circumference</a> gives the region of the
+  screen to use when representing the node (if appropriate).</p>
+
+  <p>The semantics of a <a href="#hit-region">hit region</a> for the purposes of
+  this virtual DOM tree are those of the <a href="#hit-region-s-control">hit region's
+  control</a>, if it has one, or else of a non-interactive element
+  whose ARIA role, if any, is that given by the <a href="#hit-region-s-aria-role">hit region's
+  ARIA role</a>, and whose textual representation, if any, is given
+  by the <a href="#hit-region-s-label">hit region's label</a>.</p>
+
+  <p>For the purposes of accessibility tools, when an element <var title="">C</var> is a descendant of a <code>canvas</code> element
+  and there is <a href="#the-region-representing-the-control" title="the region representing the control">a
+  region representing the control</a> <var title="">C</var> for that
+  <code>canvas</code> element, then the element's position relative to
+  the document should be presented as if it was that region in the
+  <code>canvas</code> element's virtual DOM tree.</p>
+
+  <p>The semantics of a <a href="#hit-region">hit region</a> for the purposes of
+  this virtual DOM tree are those of the <a href="#hit-region-s-control">hit region's
+  control</a>, if it has one, or else of a non-interactive element
+  whose ARIA role, if any, is that given by the <a href="#hit-region-s-aria-role">hit region's
+  ARIA role</a>, and whose textual representation, if any, is given
+  by the <a href="#hit-region-s-label">hit region's label</a>.</p>
+
+  <p class="note">Thus, for instance, a user agent on a touch-screen
+  device could provide haptic feedback when the user croses over a
+  <a href="#hit-region-s-bounding-circumference">hit region's bounding circumference</a>, and then read the
+  <a href="#hit-region-s-label">hit region's label</a> to the user. Similarly, a desktop
+  user agent with a virtual accessibility focus separate from the
+  keyboard input focus could allow the user to navigate through the
+  hit regions, using the virtual DOM tree described above to enable
+  hierarchical navigation. When an interactive control inside the
+  <code>canvas</code> element is focused, if the control has a
+  corresponding region, then that <a href="#hit-region-s-bounding-circumference">hit region's bounding
+  circumference</a> could be used to determine what area of the
+  display to magnify.</p>
+
+  </div>
+
+
+  <h2 id="pixel-manipulation"><span class="secno">15 </span><dfn>Pixel manipulation</dfn></h2>
 
   <dl class="domintro"><dt><var title="">imagedata</var> = <var title="">context</var> . <code title="dom-context-2d-createImageData"><a href="#dom-context-2d-createimagedata">createImageData</a></code>(<var title="">sw</var>, <var title="">sh</var>)</dt>
 
@@ -3795,7 +4440,7 @@
 
 
 
-  <h2 id="compositing"><span class="secno">15 </span>Compositing</h2>
+  <h2 id="compositing"><span class="secno">16 </span>Compositing</h2>
 
   <dl class="domintro"><dt><var title="">context</var> . <code title="dom-context-2d-globalAlpha"><a href="#dom-context-2d-globalalpha">globalAlpha</a></code> [ = <var title="">value</var> ]</dt>
 
@@ -3951,7 +4596,7 @@
 
 
 
-  <h2 id="shadows"><span class="secno">16 </span><dfn>Shadows</dfn></h2>
+  <h2 id="shadows"><span class="secno">17 </span><dfn>Shadows</dfn></h2>
 
   <p>All drawing operations are affected by the four global shadow
   attributes.</p>
@@ -4092,7 +4737,7 @@
 
   <div class="impl">
 
-  <h2 id="drawing-model"><span class="secno">17 </span><dfn>Drawing model</dfn></h2>
+  <h2 id="drawing-model"><span class="secno">18 </span><dfn>Drawing model</dfn></h2>
 
   <p>When a shape or image is painted, user agents must follow these
   steps, in the order given (or act as if they do):</p>
@@ -4123,7 +4768,7 @@
   </ol></div>
 
 
-  <h2 id="best-practices"><span class="secno">18 </span>Best practices</h2>
+  <h2 id="best-practices"><span class="secno">19 </span>Best practices</h2>
 
   <p><i>This section is non-normative.</i></p>
 
@@ -4185,7 +4830,7 @@
   attribute.</p>
 
 
-  <h2 id="examples"><span class="secno">19 </span>Examples</h2>
+  <h2 id="examples"><span class="secno">20 </span>Examples</h2>
 
   <p><i>This section is non-normative.</i></p>
 
@@ -4246,7 +4891,12 @@
 
   
 
-  <dl><dt id="refsBEZIER">[BEZIER]</dt>
+  <dl><dt id="refsARIA">[ARIA]</dt>
+   <dd><cite><a href="http://www.w3.org/WAI/PF/aria/">Accessible Rich
+   Internet Applications (WAI-ARIA)</a></cite>, J. Craig, M. Cooper, L. Pappas,
+   R. Schwerdtfeger, L. Seeman. W3C.</dd>
+
+   <dt id="refsBEZIER">[BEZIER]</dt>
    <dd><cite>Courbes &agrave; poles</cite>, P. de Casteljau. INPI, 1959.</dd>
 
    <dt id="refsCSS">[CSS]</dt>
@@ -4273,6 +4923,10 @@
    <dd><cite><a href="http://dev.w3.org/csswg/cssom/">Cascading Style Sheets
    Object Model (CSSOM)</a></cite>, A. van Kesteren. W3C.</dd>
 
+   <dt id="refsCSSUI">[CSSUI]</dt>
+   <dd><cite><a href="http://dev.w3.org/csswg/css3-ui/">CSS3 Basic User
+   Interface Module</a></cite>, T. &Ccedil;elik. W3C.</dd>
+
    <dt id="refsHTML5">[HTML5]</dt>
    <dd>
    <cite><a href="http://dev.w3.org/html5/spec/">HTML5</a></cite>,

Received on Monday, 26 March 2012 05:11:46 UTC