- From: poot <cvsmail@w3.org>
- Date: Mon, 26 Mar 2012 01:11:42 -0400
- To: public-html-diffs@w3.org
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 à 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. Ç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