[html5] r6125 - [giow] (0) updated drawFocusRing to take recent feedback into account

whatwg at whatwg.org whatwg at whatwg.org
Tue May 10 17:08:46 PDT 2011


Author: ianh
Date: 2011-05-10 17:08:45 -0700 (Tue, 10 May 2011)
New Revision: 6125

Modified:
   complete.html
   index
   source
Log:
[giow] (0) updated drawFocusRing to take recent feedback into account

Modified: complete.html
===================================================================
--- complete.html	2011-05-09 22:22:16 UTC (rev 6124)
+++ complete.html	2011-05-11 00:08:45 UTC (rev 6125)
@@ -239,7 +239,7 @@
 
   <header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
    <hgroup><h1>Web Applications 1.0</h1>
-    <h2 class="no-num no-toc">Living Standard — Last Updated 9 May 2011</h2>
+    <h2 class="no-num no-toc">Living Standard — Last Updated 10 May 2011</h2>
    </hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
    <p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
    <!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
@@ -634,11 +634,11 @@
          <li><a href=#shadows><span class=secno>4.8.11.1.6 </span>Shadows</a></li>
          <li><a href=#simple-shapes-(rectangles)><span class=secno>4.8.11.1.7 </span>Simple shapes (rectangles)</a></li>
          <li><a href=#complex-shapes-(paths)><span class=secno>4.8.11.1.8 </span>Complex shapes (paths)</a></li>
-         <li><a href=#focus-management-0><span class=secno>4.8.11.1.9 </span>Focus management</a></li>
-         <li><a href=#text-0><span class=secno>4.8.11.1.10 </span>Text</a></li>
-         <li><a href=#images><span class=secno>4.8.11.1.11 </span>Images</a></li>
-         <li><a href=#pixel-manipulation><span class=secno>4.8.11.1.12 </span>Pixel manipulation</a></li>
-         <li><a href=#drawing-model><span class=secno>4.8.11.1.13 </span>Drawing model</a></li>
+         <li><a href=#text-0><span class=secno>4.8.11.1.9 </span>Text</a></li>
+         <li><a href=#images><span class=secno>4.8.11.1.10 </span>Images</a></li>
+         <li><a href=#pixel-manipulation><span class=secno>4.8.11.1.11 </span>Pixel manipulation</a></li>
+         <li><a href=#drawing-model><span class=secno>4.8.11.1.12 </span>Drawing model</a></li>
+         <li><a href=#best-practices><span class=secno>4.8.11.1.13 </span>Best practices</a></li>
          <li><a href=#examples><span class=secno>4.8.11.1.14 </span>Examples</a></ol></li>
        <li><a href=#color-spaces-and-color-correction><span class=secno>4.8.11.2 </span>Color spaces and color correction</a></li>
        <li><a href=#security-with-canvas-elements><span class=secno>4.8.11.3 </span>Security with <code>canvas</code> elements</a></ol></li>
@@ -34134,7 +34134,7 @@
 
   <h5 id=2dcontext><span class=secno>4.8.11.1 </span>The 2D context</h5>
 
-  <!-- v2: we're on v4. suggestions for next version are marked v5. -->
+  <!-- v2: we're on v4.1. suggestions for next version are marked v5. -->
 
   
 
@@ -34230,12 +34230,12 @@
   void <a href=#dom-context-2d-arc title=dom-context-2d-arc>arc</a>(in double x, in double y, in double radius, in double startAngle, in double endAngle, in optional boolean anticlockwise);
   void <a href=#dom-context-2d-fill title=dom-context-2d-fill>fill</a>();
   void <a href=#dom-context-2d-stroke title=dom-context-2d-stroke>stroke</a>();
+  void <a href=#dom-context-2d-drawosfocusring title=dom-context-2d-drawOSFocusRing>drawOSFocusRing</a>(in <a href=#element>Element</a> element);
+  boolean <a href=#dom-context-2d-drawcustomfocusring title=dom-context-2d-drawCustomFocusRing>drawCustomFocusRing</a>(in <a href=#element>Element</a> element);
+  void <a href=#dom-context-2d-scrollpathintoview title=dom-context-2d-scrollPathIntoView>scrollPathIntoView</a>();
   void <a href=#dom-context-2d-clip title=dom-context-2d-clip>clip</a>();
   boolean <a href=#dom-context-2d-ispointinpath title=dom-context-2d-isPointInPath>isPointInPath</a>(in double x, in double y);
 
-  // focus management
-  boolean <a href=#dom-context-2d-drawfocusring title=dom-context-2d-drawFocusRing>drawFocusRing</a>(in <a href=#element>Element</a> element, in double xCaret, in double yCaret, in optional boolean canDrawCustom);
-
   // text
            attribute DOMString <a href=#dom-context-2d-font title=dom-context-2d-font>font</a>; // (default 10px sans-serif)
            attribute DOMString <a href=#dom-context-2d-textalign title=dom-context-2d-textAlign>textAlign</a>; // "start", "end", "left", "right", "center" (default: "start")
@@ -35550,6 +35550,42 @@
 
    </dd>
 
+   <dt><var title="">context</var> . <code title=dom-context-2d-drawOSFocusRing><a href=#dom-context-2d-drawosfocusring>drawOSFocusRing</a></code>(<var title="">element</var>)</dt>
+
+   <dd>
+
+    <p>If the given element is focused, draws a focus ring around the
+    current path, following the platform conventions for focus
+    rings.</p>
+
+   </dd>
+
+   <dt><var title="">shouldDraw</var> = <var title="">context</var> . <code title=dom-context-2d-drawCustomFocusRing><a href=#dom-context-2d-drawcustomfocusring>drawCustomFocusRing</a></code>(<var title="">element</var>)</dt>
+
+   <dd>
+
+    <p>If the given element is focused, and the user has configured
+    his system to draw focus rings in a particular manner (for
+    example, high contrast focus rings), draws a focus ring around the
+    current path and returns false.</p>
+
+    <p>Otherwise, returns true if the given element is focused, and
+    false otherwise. This can thus be used to determine when to draw a
+    focus ring (see <a href=#drawCustomFocusRingExample>the
+    example</a> below).</p>
+
+   </dd>
+
+   <dt><var title="">context</var> . <code title=dom-context-2d-scrollPathIntoView><a href=#dom-context-2d-scrollpathintoview>scrollPathIntoView</a></code>()</dt>
+
+   <dd>
+
+    <p>Scrolls the current path into view. This is especially useful
+    on devices with small screens, where the whole canvas might not be
+    visible at once.</p>
+
+   </dd>
+
    <dt><var title="">context</var> . <code title=dom-context-2d-clip><a href=#dom-context-2d-clip>clip</a></code>()</dt>
 
    <dd>
@@ -35752,8 +35788,100 @@
   <p>Zero-length line segments must be pruned before stroking a
   path. Empty subpaths must be ignored.</p>
 
+  <hr><p>The <dfn id=dom-context-2d-drawosfocusring title=dom-context-2d-drawOSFocusRing><code>drawOSFocusRing(<var title="">element</var>)</code></dfn> method, when invoked,
+  must run the following steps:</p>
 
-  <p>The <dfn id=dom-context-2d-clip title=dom-context-2d-clip><code>clip()</code></dfn>
+  <ol><li><p>If <var title="">element</var> is not focused or is not a
+   descendant of the element with whose context the method is
+   associated, then abort these steps.</li>
+
+   <li>
+
+    <p>If the user has requested the use of particular focus rings
+    (e.g. high-contrast focus rings), or if the <var title="">element</var> would have a focus ring drawn around it,
+    then draw a focus ring of the appropriate style along the path,
+    following platform conventions, and abort these steps.</p>
+
+    <p class=note>Some platforms only draw focus rings around
+    elements that have been focused from the keyboard, and not those
+    focused from the mouse. Other platforms simply don't draw focus
+    rings around some elements at all unless relevant accessibility
+    features are enabled. This API is intended to follow these
+    conventions.</p>
+
+    <p>The focus ring should not be subject to the <a href=#shadows title=shadows>shadow effects</a>, the <a href=#dom-context-2d-globalalpha title=dom-context-2d-globalAlpha>global alpha</a>, or the <a href=#dom-context-2d-globalcompositeoperation title=dom-context-2d-globalCompositeOperation>global composition
+    operators</a>, but <em>should</em> be subject to the <a href=#clipping-region title="clipping region">clipping region</a>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Optionally, <a href=#inform>inform the user</a> that the
+    focus is at the location given by the path. User agents may wait
+    until the next time the <a href=#event-loop>event loop</a> reaches its
+    "update the rendering" step to optionally inform the user.</p>
+
+   </li>
+
+  </ol><p>The <dfn id=dom-context-2d-drawcustomfocusring title=dom-context-2d-drawCustomFocusRing><code>drawCustomFocusRing(<var title="">element</var>)</code></dfn> method, when invoked, must run
+  the following steps:</p>
+
+  <ol><li><p>If <var title="">element</var> is not focused or is not a
+   descendant of the element with whose context the method is
+   associated, then return false and abort these steps.</li>
+
+   <li>
+
+    <p>If the user has requested the use of particular focus rings
+    (e.g. high-contrast focus rings), then draw a focus ring of the
+    appropriate style along the path, return false, and abort these
+    steps.</p>
+
+    <p>The focus ring should not be subject to the <a href=#shadows title=shadows>shadow effects</a>, the <a href=#dom-context-2d-globalalpha title=dom-context-2d-globalAlpha>global alpha</a>, or the <a href=#dom-context-2d-globalcompositeoperation title=dom-context-2d-globalCompositeOperation>global composition
+    operators</a>, but <em>should</em> be subject to the <a href=#clipping-region title="clipping region">clipping region</a>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Optionally, <a href=#inform>inform the user</a> that the
+    focus is at the location given by the path. User agents may wait
+    until the next time the <a href=#event-loop>event loop</a> reaches its
+    "update the rendering" step to optionally inform the user.</p>
+
+   </li>
+
+   <li><p>Return true.</li>
+
+  </ol><p>The <dfn id=dom-context-2d-scrollpathintoview title=dom-context-2d-scrollPathIntoView><code>scrollPathIntoView()</code></dfn>
+  method, when invoked, must run the following steps:</p>
+
+  <ol><li><p>Let <var title="">notional child</var> be a hypothetical
+   element that is a rendered child of the <code><a href=#the-canvas-element>canvas</a></code> element
+   whose dimensions are exactly the rectangle of the bounding box of
+   the current path.</li>
+
+   <li><p><span title="scroll an element into view">Scroll <var title="">notional child</var> into view</span> with the <var title="">align to top flag</var> set.</p>
+
+   <li><p>Optionally, <a href=#inform>inform the user</a> that the
+   caret and/or selection cover <var title="">the specified
+   rectangle</var> of the canvas. User agents may wait until the next
+   time the <a href=#event-loop>event loop</a> reaches its "update the rendering"
+   step to optionally inform the user.</li>
+
+  </ol><p class=note id=inform>"Inform the user", as used in this
+  section, could mean calling a system accessibility API, which would
+  notify assistive technologies such as magnification tools. To
+  properly drive magnification based on a focus change, a system
+  accessibility API driving a screen magnifier needs the bounds for
+  the newly focused object. The methods above are intended to enable
+  this by allowing the user agent to report the bounding box of the
+  path used to render the focus ring as the bounds of the <var title="">element</var> element passed as an argument, if that
+  element is focused, and the bounding box of the area to which the
+  user agent is scrolling as the bounding box of the current
+  selection.</p>
+
+  <hr><p>The <dfn id=dom-context-2d-clip title=dom-context-2d-clip><code>clip()</code></dfn>
   method must create a new <dfn id=clipping-region>clipping region</dfn> by calculating
   the intersection of the current clipping region and the area
   described by the current path, using the non-zero winding number
@@ -35772,8 +35900,7 @@
     * support ways of resetting the clipping region without save/restore
   -->
 
-
-  <p>The <dfn id=dom-context-2d-ispointinpath title=dom-context-2d-isPointInPath><code>isPointInPath(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must
+  <hr><p>The <dfn id=dom-context-2d-ispointinpath title=dom-context-2d-isPointInPath><code>isPointInPath(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must
   return true if the point given by the <var title="">x</var> and <var title="">y</var> coordinates passed to the method, when treated as
   coordinates in the canvas coordinate space unaffected by the current
   transformation, is inside the current path as determined by the
@@ -35785,110 +35912,41 @@
   </div>
 
 
-  <h6 id=focus-management-0><span class=secno>4.8.11.1.9 </span>Focus management</h6> <!-- a v4 feature -->
+  <div class=example id=drawCustomFocusRingExample>
 
-  <p>When a canvas is interactive, authors should include focusable
-  elements in the element's fallback content corresponding to each
-  focusable part of the canvas.</p>
+   <p>This <code><a href=#the-canvas-element>canvas</a></code> element has a couple of checkboxes. The
+   path-related commands are highlighted:</p>
 
-  <p>To indicate which focusable part of the canvas is currently
-  focused, authors should use the <code title=dom-context-2d-drawFocusRing><a href=#dom-context-2d-drawfocusring>drawFocusRing()</a></code> method,
-  passing it the element for which a ring is being drawn. This method
-  only draws the focus ring if the element is focused, so that it can
-  simply be called whenever drawing the element, without checking
-  whether the element is focused or not first. The position of the
-  center of the control, or of the editing caret if the control has
-  one, should be given in the <var title="">x</var> and <var title="">y</var> arguments.</p>
-
-  <dl class=domintro><dt><var title="">shouldDraw</var> = <var title="">context</var> . <code title=dom-context-2d-drawFocusRing><a href=#dom-context-2d-drawfocusring>drawFocusRing</a></code>(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>, [ <var title="">canDrawCustom</var> ])</dt>
-
-   <dd>
-
-    <p>If the given element is focused, draws a focus ring around the
-    current path, following the platform conventions for focus
-    rings. The given coordinate is used if the user's attention needs
-    to be brought to a particular position (e.g. if a magnifier is
-    following the editing caret in a text field).</p>
-
-    <p>If the <var title="">canDrawCustom</var> argument is true, then
-    the focus ring is only drawn if the user has configured his system
-    to draw focus rings in a particular manner. (For example, high
-    contrast focus rings.)</p>
-
-    <p>Returns true if the given element is focused, the <var title="">canDrawCustom</var> argument is true, and the user has
-    not configured his system to draw focus rings in a particular
-    manner. Otherwise, returns false.</p>
-
-    <p>When the method returns true, the author is expected to
-    manually draw a focus ring.</p>
-
-   </dd>
-
-  </dl><div class=impl>
-
-  <p>The <dfn id=dom-context-2d-drawfocusring title=dom-context-2d-drawFocusRing><code>drawFocusRing(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>, [<var title="">canDrawCustom</var>])</code></dfn>
-  method, when invoked, must run the following steps:</p>
-
-  <ol><li><p>If <var title="">element</var> is not focused or is not a
-   descendant of the element with whose context the method is
-   associated, then return false and abort these steps.</li>
-
-   <li><p>Transform the given point (<var title="">x</var>, <var title="">y</var>) according to the <a href=#transformations title=dom-context-2d-transformation>current transformation
-   matrix</a>.</li>
-
-   <li><p>Optionally, inform the user that the focus is at the given
-   (transformed) coordinate on the canvas. (For example, this could
-   involve moving the user's magnification tool.)</li>
-
-   <li>
-
-    <p>If the user has requested the use of particular focus rings
-    (e.g. high-contrast focus rings), or if the <var title="">canDrawCustom</var> argument is absent or false, then
-    draw a focus ring of the appropriate style along the path,
-    following platform conventions, return false, and abort these
-    steps.</p>
-
-    <p>The focus ring should not be subject to the <a href=#shadows title=shadows>shadow effects</a>, the <a href=#dom-context-2d-globalalpha title=dom-context-2d-globalAlpha>global alpha</a>, or the <a href=#dom-context-2d-globalcompositeoperation title=dom-context-2d-globalCompositeOperation>global composition
-    operators</a>, but <em>should</em> be subject to the <a href=#clipping-region title="clipping region">clipping region</a>.</p>
-
-   </li>
-
-   <li><p>Return true.</li>
-
-  </ol></div>
-
-  <div class=example>
-
-   <p>This <code><a href=#the-canvas-element>canvas</a></code> element has a couple of checkboxes:</p>
-
    <pre><canvas height=400 width=750>
  <label><input type=checkbox id=showA> Show As</label>
  <label><input type=checkbox id=showB> Show Bs</label>
  <!-- ... -->
 </canvas>
 <script>
- function drawCheckbox(context, element, x, y) {
+ function drawCheckbox(context, element, x, y, paint) {
    context.save();
    context.font = '10px sans-serif';
    context.textAlign = 'left';
    context.textBaseline = 'middle';
    var metrics = context.measureText(element.labels[0].textContent);
-   context.beginPath();
-   context.strokeStyle = 'black';
-   context.rect(x-5, y-5, 10, 10);
-   context.stroke();
-   if (element.checked) {
-     context.fillStyle = 'black';
-     context.fill();
+   if (paint) {
+<strong>     context.beginPath();
+     context.strokeStyle = 'black';
+     context.rect(x-5, y-5, 10, 10);
+     context.stroke();
+</strong>     if (element.checked) {
+<strong>       context.fillStyle = 'black';
+       context.fill();
+</strong>     }
+     context.fillText(element.labels[0].textContent, x+5, y);
    }
-   context.fillText(element.labels[0].textContent, x+5, y);
-   context.beginPath();
+<strong>   context.beginPath();
    context.rect(x-7, y-7, 12 + metrics.width+2, 14);
-   if (context.drawFocusRing(element, x, y, true)) {
+   if (paint && context.drawCustomFocusRing(element)) {
      context.strokeStyle = 'silver';
      context.stroke();
    }
-   context.restore();
+</strong>   context.restore();
  }
  function drawBase() { /* ... */ }
  function drawAs() { /* ... */ }
@@ -35897,8 +35955,8 @@
    var canvas = document.getElementsByTagName('canvas')[0];
    var context = canvas.getContext('2d');
    context.clearRect(0, 0, canvas.width, canvas.height);
-   drawCheckbox(context, document.getElementById('showA'), 20, 40);
-   drawCheckbox(context, document.getElementById('showB'), 20, 60);
+   drawCheckbox(context, document.getElementById('showA'), 20, 40, true);
+   drawCheckbox(context, document.getElementById('showB'), 20, 60, true);
    drawBase();
    if (document.getElementById('showA').checked)
      drawAs();
@@ -35908,12 +35966,17 @@
  function processClick(event) {
    var canvas = document.getElementsByTagName('canvas')[0];
    var context = canvas.getContext('2d');
-   var x = event.clientX - canvas.offsetLeft;
-   var y = event.clientY - canvas.offsetTop;
-   drawCheckbox(context, document.getElementById('showA'), 20, 40);
+   var x = event.clientX;
+   var y = event.clientY;
+   while (node) {
+     x -= node.offsetLeft - node.scrollLeft;
+     y -= node.offsetTop - node.scrollTop;
+     node = node.offsetParent;
+   }
+   drawCheckbox(context, document.getElementById('showA'), 20, 40, false);
    if (context.isPointInPath(x, y))
      document.getElementById('showA').checked = !(document.getElementById('showA').checked);
-   drawCheckbox(context, document.getElementById('showB'), 20, 60);
+   drawCheckbox(context, document.getElementById('showB'), 20, 60, false);
    if (context.isPointInPath(x, y))
      document.getElementById('showB').checked = !(document.getElementById('showB').checked);
    redraw();
@@ -35929,8 +35992,10 @@
   </div>
 
 
-  <h6 id=text-0><span class=secno>4.8.11.1.10 </span>Text</h6> <!-- a v3 feature -->
 
+
+  <h6 id=text-0><span class=secno>4.8.11.1.9 </span>Text</h6> <!-- a v3 feature -->
+
   <dl class=domintro><dt><var title="">context</var> . <code title=dom-context-2d-font><a href=#dom-context-2d-font>font</a></code> [ = <var title="">value</var> ]</dt>
 
    <dd>
@@ -36437,7 +36502,7 @@
 
 
 
-  <h6 id=images><span class=secno>4.8.11.1.11 </span>Images</h6>
+  <h6 id=images><span class=secno>4.8.11.1.10 </span>Images</h6>
 
   <p>To draw images onto the canvas, the <dfn id=dom-context-2d-drawimage title=dom-context-2d-drawImage><code>drawImage</code></dfn> method
   can be used.</p>
@@ -36578,7 +36643,7 @@
 
 
 
-  <h6 id=pixel-manipulation><span class=secno>4.8.11.1.12 </span><dfn>Pixel manipulation</dfn></h6>
+  <h6 id=pixel-manipulation><span class=secno>4.8.11.1.11 </span><dfn>Pixel manipulation</dfn></h6>
 
   <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>
 
@@ -36937,7 +37002,7 @@
 
   <div class=impl>
 
-  <h6 id=drawing-model><span class=secno>4.8.11.1.13 </span><dfn>Drawing model</dfn></h6>
+  <h6 id=drawing-model><span class=secno>4.8.11.1.12 </span><dfn>Drawing model</dfn></h6>
 
   <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>
@@ -36968,6 +37033,68 @@
   </ol></div>
 
 
+  <h6 id=best-practices><span class=secno>4.8.11.1.13 </span>Best practices</h6>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>When a canvas is interactive, authors should include focusable
+  elements in the element's fallback content corresponding to each
+  focusable part of the canvas, as in the <a href=#drawCustomFocusRingExample>example above</a>.</p>
+
+  <p>To indicate which focusable part of the canvas is currently
+  focused, authors should use the <code title=dom-context-2d-drawOSFocusRing><a href=#dom-context-2d-drawosfocusring>drawOSFocusRing()</a></code> method,
+  passing it the element for which a ring is being drawn. This method
+  only draws the focus ring if the element is focused, so that it can
+  simply be called whenever drawing the element, without checking
+  whether the element is focused or not first.</p>
+
+  <p>Authors should avoid implementing text editing controls using the
+  <code><a href=#the-canvas-element>canvas</a></code> element. Doing so has a large number of
+  disadvantages:</p>
+
+  <ul><li>Mouse placement of the caret has to be reimplemented.</li>
+
+   <li>Keyboard movement of the caret has to be reimplemented (possibly across lines, for multiline text input).</li>
+
+   <li>Scrolling of the text field has to be implemented (horizontally for long lines, vertically for multiline input).</li>
+
+   <li>Native features such as copy-and-paste have to be reimplemented.</li>
+
+   <li>Native features such as spell-checking have to be reimplemented.</li>
+
+   <li>Native features such as drag-and-drop have to be reimplemented.</li>
+
+   <li>Native features such as page-wide text search have to be reimplemented.</li>
+
+   <li>Native features specific to the user, for example custom text
+   services, have to be reimplemented. This is close to impossible
+   since each user might have different services installed, and there
+   is an unbounded set of possible such services.</li>
+
+   <li>Bidirectional text editing has to be reimplemented.</li>
+
+   <li>For multiline text editing, line wrapping has to be implemented for all relevant languages.</li>
+
+   <li>Text selection has to be reimplemented.</li>
+
+   <li>Dragging of bidirectional text selections has to be reimplemented.</li>
+
+   <li>Platform-native keyboard shortcuts have to be reimplemented.</li>
+
+   <li>Platform-native input method editors (IMEs) have to be reimplemented.</li>
+
+   <li>Undo and redo functionality has to be reimplemented.</li>
+
+   <li>Accessibility features such as magnification following the
+   caret or selection have to be reimplemented.</li>
+
+  </ul><p>This is a huge amount of work, and authors are most strongly
+  encouraged to avoid doing any of it by instead using the
+  <code><a href=#the-input-element>input</a></code> element, the <code><a href=#the-textarea-element>textarea</a></code> element, or
+  the <code title=attr-contenteditable><a href=#attr-contenteditable>contenteditable</a></code>
+  attribute.</p>
+
+
   <h6 id=examples><span class=secno>4.8.11.1.14 </span>Examples</h6>
 
   <p><i>This section is non-normative.</i></p>

Modified: index
===================================================================
--- index	2011-05-09 22:22:16 UTC (rev 6124)
+++ index	2011-05-11 00:08:45 UTC (rev 6125)
@@ -243,7 +243,7 @@
 
   <header class=head id=head><p><a class=logo href=http://www.whatwg.org/ rel=home><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
    <hgroup><h1 class=allcaps>HTML</h1>
-    <h2 class="no-num no-toc">Living Standard — Last Updated 9 May 2011</h2>
+    <h2 class="no-num no-toc">Living Standard — Last Updated 10 May 2011</h2>
    </hgroup><p>You can take part in this work. <a href=http://www.whatwg.org/mailing-list>Join the working group's discussion list.</a></p>
    <p><strong>Web designers!</strong> We have a <a href=http://blog.whatwg.org/faq/>FAQ</a>, a <a href=http://forums.whatwg.org/>forum</a>, and a <a href=http://www.whatwg.org/mailing-list#help>help mailing list</a> for you!</p>
    <!--<p class="impl"><strong>Implementors!</strong> We have a <a href="http://www.whatwg.org/mailing-list#implementors">mailing list</a> for you too!</p>-->
@@ -642,11 +642,11 @@
          <li><a href=#shadows><span class=secno>4.8.11.1.6 </span>Shadows</a></li>
          <li><a href=#simple-shapes-(rectangles)><span class=secno>4.8.11.1.7 </span>Simple shapes (rectangles)</a></li>
          <li><a href=#complex-shapes-(paths)><span class=secno>4.8.11.1.8 </span>Complex shapes (paths)</a></li>
-         <li><a href=#focus-management-0><span class=secno>4.8.11.1.9 </span>Focus management</a></li>
-         <li><a href=#text-0><span class=secno>4.8.11.1.10 </span>Text</a></li>
-         <li><a href=#images><span class=secno>4.8.11.1.11 </span>Images</a></li>
-         <li><a href=#pixel-manipulation><span class=secno>4.8.11.1.12 </span>Pixel manipulation</a></li>
-         <li><a href=#drawing-model><span class=secno>4.8.11.1.13 </span>Drawing model</a></li>
+         <li><a href=#text-0><span class=secno>4.8.11.1.9 </span>Text</a></li>
+         <li><a href=#images><span class=secno>4.8.11.1.10 </span>Images</a></li>
+         <li><a href=#pixel-manipulation><span class=secno>4.8.11.1.11 </span>Pixel manipulation</a></li>
+         <li><a href=#drawing-model><span class=secno>4.8.11.1.12 </span>Drawing model</a></li>
+         <li><a href=#best-practices><span class=secno>4.8.11.1.13 </span>Best practices</a></li>
          <li><a href=#examples><span class=secno>4.8.11.1.14 </span>Examples</a></ol></li>
        <li><a href=#color-spaces-and-color-correction><span class=secno>4.8.11.2 </span>Color spaces and color correction</a></li>
        <li><a href=#security-with-canvas-elements><span class=secno>4.8.11.3 </span>Security with <code>canvas</code> elements</a></ol></li>
@@ -1424,7 +1424,13 @@
    <li><a href=#mdvocabs>Microdata vocabularies</a>
    <li><a href=#crossDocumentMessages>Cross-document messaging</a> (also known as Communications)<!--POSTMSG-->
    <li><a href=#channel-messaging>Channel messaging</a> (also known as Communications)<!--POSTMSG-->
-  </ul><p>The <a href=#forms>forms</a> part of this specification was
+  </ul><p>The specification that covers the Canvas 2D Graphics Context at
+  the W3C does not include all the advice included in the equivalent
+  section in this document, because of <a href=http://lists.w3.org/Archives/Public/public-html/2011Apr/0712.html>the
+  discussion</a> that followed <a href=http://lists.w3.org/Archives/Public/public-html/2011Apr/0271.html>a
+  working gorup decision from April 2011</a>.</p>
+
+  <p>The <a href=#forms>forms</a> part of this specification was
   previously published separately in a specification known as Web
   Forms 2.</p>
 
@@ -34162,7 +34168,7 @@
 
   <h5 id=2dcontext><span class=secno>4.8.11.1 </span>The 2D context</h5>
 
-  <!-- v2: we're on v4. suggestions for next version are marked v5. -->
+  <!-- v2: we're on v4.1. suggestions for next version are marked v5. -->
 
   
 
@@ -34258,12 +34264,12 @@
   void <a href=#dom-context-2d-arc title=dom-context-2d-arc>arc</a>(in double x, in double y, in double radius, in double startAngle, in double endAngle, in optional boolean anticlockwise);
   void <a href=#dom-context-2d-fill title=dom-context-2d-fill>fill</a>();
   void <a href=#dom-context-2d-stroke title=dom-context-2d-stroke>stroke</a>();
+  void <a href=#dom-context-2d-drawosfocusring title=dom-context-2d-drawOSFocusRing>drawOSFocusRing</a>(in <a href=#element>Element</a> element);
+  boolean <a href=#dom-context-2d-drawcustomfocusring title=dom-context-2d-drawCustomFocusRing>drawCustomFocusRing</a>(in <a href=#element>Element</a> element);
+  void <a href=#dom-context-2d-scrollpathintoview title=dom-context-2d-scrollPathIntoView>scrollPathIntoView</a>();
   void <a href=#dom-context-2d-clip title=dom-context-2d-clip>clip</a>();
   boolean <a href=#dom-context-2d-ispointinpath title=dom-context-2d-isPointInPath>isPointInPath</a>(in double x, in double y);
 
-  // focus management
-  boolean <a href=#dom-context-2d-drawfocusring title=dom-context-2d-drawFocusRing>drawFocusRing</a>(in <a href=#element>Element</a> element, in double xCaret, in double yCaret, in optional boolean canDrawCustom);
-
   // text
            attribute DOMString <a href=#dom-context-2d-font title=dom-context-2d-font>font</a>; // (default 10px sans-serif)
            attribute DOMString <a href=#dom-context-2d-textalign title=dom-context-2d-textAlign>textAlign</a>; // "start", "end", "left", "right", "center" (default: "start")
@@ -35578,6 +35584,42 @@
 
    </dd>
 
+   <dt><var title="">context</var> . <code title=dom-context-2d-drawOSFocusRing><a href=#dom-context-2d-drawosfocusring>drawOSFocusRing</a></code>(<var title="">element</var>)</dt>
+
+   <dd>
+
+    <p>If the given element is focused, draws a focus ring around the
+    current path, following the platform conventions for focus
+    rings.</p>
+
+   </dd>
+
+   <dt><var title="">shouldDraw</var> = <var title="">context</var> . <code title=dom-context-2d-drawCustomFocusRing><a href=#dom-context-2d-drawcustomfocusring>drawCustomFocusRing</a></code>(<var title="">element</var>)</dt>
+
+   <dd>
+
+    <p>If the given element is focused, and the user has configured
+    his system to draw focus rings in a particular manner (for
+    example, high contrast focus rings), draws a focus ring around the
+    current path and returns false.</p>
+
+    <p>Otherwise, returns true if the given element is focused, and
+    false otherwise. This can thus be used to determine when to draw a
+    focus ring (see <a href=#drawCustomFocusRingExample>the
+    example</a> below).</p>
+
+   </dd>
+
+   <dt><var title="">context</var> . <code title=dom-context-2d-scrollPathIntoView><a href=#dom-context-2d-scrollpathintoview>scrollPathIntoView</a></code>()</dt>
+
+   <dd>
+
+    <p>Scrolls the current path into view. This is especially useful
+    on devices with small screens, where the whole canvas might not be
+    visible at once.</p>
+
+   </dd>
+
    <dt><var title="">context</var> . <code title=dom-context-2d-clip><a href=#dom-context-2d-clip>clip</a></code>()</dt>
 
    <dd>
@@ -35780,8 +35822,100 @@
   <p>Zero-length line segments must be pruned before stroking a
   path. Empty subpaths must be ignored.</p>
 
+  <hr><p>The <dfn id=dom-context-2d-drawosfocusring title=dom-context-2d-drawOSFocusRing><code>drawOSFocusRing(<var title="">element</var>)</code></dfn> method, when invoked,
+  must run the following steps:</p>
 
-  <p>The <dfn id=dom-context-2d-clip title=dom-context-2d-clip><code>clip()</code></dfn>
+  <ol><li><p>If <var title="">element</var> is not focused or is not a
+   descendant of the element with whose context the method is
+   associated, then abort these steps.</li>
+
+   <li>
+
+    <p>If the user has requested the use of particular focus rings
+    (e.g. high-contrast focus rings), or if the <var title="">element</var> would have a focus ring drawn around it,
+    then draw a focus ring of the appropriate style along the path,
+    following platform conventions, and abort these steps.</p>
+
+    <p class=note>Some platforms only draw focus rings around
+    elements that have been focused from the keyboard, and not those
+    focused from the mouse. Other platforms simply don't draw focus
+    rings around some elements at all unless relevant accessibility
+    features are enabled. This API is intended to follow these
+    conventions.</p>
+
+    <p>The focus ring should not be subject to the <a href=#shadows title=shadows>shadow effects</a>, the <a href=#dom-context-2d-globalalpha title=dom-context-2d-globalAlpha>global alpha</a>, or the <a href=#dom-context-2d-globalcompositeoperation title=dom-context-2d-globalCompositeOperation>global composition
+    operators</a>, but <em>should</em> be subject to the <a href=#clipping-region title="clipping region">clipping region</a>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Optionally, <a href=#inform>inform the user</a> that the
+    focus is at the location given by the path. User agents may wait
+    until the next time the <a href=#event-loop>event loop</a> reaches its
+    "update the rendering" step to optionally inform the user.</p>
+
+   </li>
+
+  </ol><p>The <dfn id=dom-context-2d-drawcustomfocusring title=dom-context-2d-drawCustomFocusRing><code>drawCustomFocusRing(<var title="">element</var>)</code></dfn> method, when invoked, must run
+  the following steps:</p>
+
+  <ol><li><p>If <var title="">element</var> is not focused or is not a
+   descendant of the element with whose context the method is
+   associated, then return false and abort these steps.</li>
+
+   <li>
+
+    <p>If the user has requested the use of particular focus rings
+    (e.g. high-contrast focus rings), then draw a focus ring of the
+    appropriate style along the path, return false, and abort these
+    steps.</p>
+
+    <p>The focus ring should not be subject to the <a href=#shadows title=shadows>shadow effects</a>, the <a href=#dom-context-2d-globalalpha title=dom-context-2d-globalAlpha>global alpha</a>, or the <a href=#dom-context-2d-globalcompositeoperation title=dom-context-2d-globalCompositeOperation>global composition
+    operators</a>, but <em>should</em> be subject to the <a href=#clipping-region title="clipping region">clipping region</a>.</p>
+
+   </li>
+
+   <li>
+
+    <p>Optionally, <a href=#inform>inform the user</a> that the
+    focus is at the location given by the path. User agents may wait
+    until the next time the <a href=#event-loop>event loop</a> reaches its
+    "update the rendering" step to optionally inform the user.</p>
+
+   </li>
+
+   <li><p>Return true.</li>
+
+  </ol><p>The <dfn id=dom-context-2d-scrollpathintoview title=dom-context-2d-scrollPathIntoView><code>scrollPathIntoView()</code></dfn>
+  method, when invoked, must run the following steps:</p>
+
+  <ol><li><p>Let <var title="">notional child</var> be a hypothetical
+   element that is a rendered child of the <code><a href=#the-canvas-element>canvas</a></code> element
+   whose dimensions are exactly the rectangle of the bounding box of
+   the current path.</li>
+
+   <li><p><span title="scroll an element into view">Scroll <var title="">notional child</var> into view</span> with the <var title="">align to top flag</var> set.</p>
+
+   <li><p>Optionally, <a href=#inform>inform the user</a> that the
+   caret and/or selection cover <var title="">the specified
+   rectangle</var> of the canvas. User agents may wait until the next
+   time the <a href=#event-loop>event loop</a> reaches its "update the rendering"
+   step to optionally inform the user.</li>
+
+  </ol><p class=note id=inform>"Inform the user", as used in this
+  section, could mean calling a system accessibility API, which would
+  notify assistive technologies such as magnification tools. To
+  properly drive magnification based on a focus change, a system
+  accessibility API driving a screen magnifier needs the bounds for
+  the newly focused object. The methods above are intended to enable
+  this by allowing the user agent to report the bounding box of the
+  path used to render the focus ring as the bounds of the <var title="">element</var> element passed as an argument, if that
+  element is focused, and the bounding box of the area to which the
+  user agent is scrolling as the bounding box of the current
+  selection.</p>
+
+  <hr><p>The <dfn id=dom-context-2d-clip title=dom-context-2d-clip><code>clip()</code></dfn>
   method must create a new <dfn id=clipping-region>clipping region</dfn> by calculating
   the intersection of the current clipping region and the area
   described by the current path, using the non-zero winding number
@@ -35800,8 +35934,7 @@
     * support ways of resetting the clipping region without save/restore
   -->
 
-
-  <p>The <dfn id=dom-context-2d-ispointinpath title=dom-context-2d-isPointInPath><code>isPointInPath(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must
+  <hr><p>The <dfn id=dom-context-2d-ispointinpath title=dom-context-2d-isPointInPath><code>isPointInPath(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must
   return true if the point given by the <var title="">x</var> and <var title="">y</var> coordinates passed to the method, when treated as
   coordinates in the canvas coordinate space unaffected by the current
   transformation, is inside the current path as determined by the
@@ -35813,110 +35946,41 @@
   </div>
 
 
-  <h6 id=focus-management-0><span class=secno>4.8.11.1.9 </span>Focus management</h6> <!-- a v4 feature -->
+  <div class=example id=drawCustomFocusRingExample>
 
-  <p>When a canvas is interactive, authors should include focusable
-  elements in the element's fallback content corresponding to each
-  focusable part of the canvas.</p>
+   <p>This <code><a href=#the-canvas-element>canvas</a></code> element has a couple of checkboxes. The
+   path-related commands are highlighted:</p>
 
-  <p>To indicate which focusable part of the canvas is currently
-  focused, authors should use the <code title=dom-context-2d-drawFocusRing><a href=#dom-context-2d-drawfocusring>drawFocusRing()</a></code> method,
-  passing it the element for which a ring is being drawn. This method
-  only draws the focus ring if the element is focused, so that it can
-  simply be called whenever drawing the element, without checking
-  whether the element is focused or not first. The position of the
-  center of the control, or of the editing caret if the control has
-  one, should be given in the <var title="">x</var> and <var title="">y</var> arguments.</p>
-
-  <dl class=domintro><dt><var title="">shouldDraw</var> = <var title="">context</var> . <code title=dom-context-2d-drawFocusRing><a href=#dom-context-2d-drawfocusring>drawFocusRing</a></code>(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>, [ <var title="">canDrawCustom</var> ])</dt>
-
-   <dd>
-
-    <p>If the given element is focused, draws a focus ring around the
-    current path, following the platform conventions for focus
-    rings. The given coordinate is used if the user's attention needs
-    to be brought to a particular position (e.g. if a magnifier is
-    following the editing caret in a text field).</p>
-
-    <p>If the <var title="">canDrawCustom</var> argument is true, then
-    the focus ring is only drawn if the user has configured his system
-    to draw focus rings in a particular manner. (For example, high
-    contrast focus rings.)</p>
-
-    <p>Returns true if the given element is focused, the <var title="">canDrawCustom</var> argument is true, and the user has
-    not configured his system to draw focus rings in a particular
-    manner. Otherwise, returns false.</p>
-
-    <p>When the method returns true, the author is expected to
-    manually draw a focus ring.</p>
-
-   </dd>
-
-  </dl><div class=impl>
-
-  <p>The <dfn id=dom-context-2d-drawfocusring title=dom-context-2d-drawFocusRing><code>drawFocusRing(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>, [<var title="">canDrawCustom</var>])</code></dfn>
-  method, when invoked, must run the following steps:</p>
-
-  <ol><li><p>If <var title="">element</var> is not focused or is not a
-   descendant of the element with whose context the method is
-   associated, then return false and abort these steps.</li>
-
-   <li><p>Transform the given point (<var title="">x</var>, <var title="">y</var>) according to the <a href=#transformations title=dom-context-2d-transformation>current transformation
-   matrix</a>.</li>
-
-   <li><p>Optionally, inform the user that the focus is at the given
-   (transformed) coordinate on the canvas. (For example, this could
-   involve moving the user's magnification tool.)</li>
-
-   <li>
-
-    <p>If the user has requested the use of particular focus rings
-    (e.g. high-contrast focus rings), or if the <var title="">canDrawCustom</var> argument is absent or false, then
-    draw a focus ring of the appropriate style along the path,
-    following platform conventions, return false, and abort these
-    steps.</p>
-
-    <p>The focus ring should not be subject to the <a href=#shadows title=shadows>shadow effects</a>, the <a href=#dom-context-2d-globalalpha title=dom-context-2d-globalAlpha>global alpha</a>, or the <a href=#dom-context-2d-globalcompositeoperation title=dom-context-2d-globalCompositeOperation>global composition
-    operators</a>, but <em>should</em> be subject to the <a href=#clipping-region title="clipping region">clipping region</a>.</p>
-
-   </li>
-
-   <li><p>Return true.</li>
-
-  </ol></div>
-
-  <div class=example>
-
-   <p>This <code><a href=#the-canvas-element>canvas</a></code> element has a couple of checkboxes:</p>
-
    <pre><canvas height=400 width=750>
  <label><input type=checkbox id=showA> Show As</label>
  <label><input type=checkbox id=showB> Show Bs</label>
  <!-- ... -->
 </canvas>
 <script>
- function drawCheckbox(context, element, x, y) {
+ function drawCheckbox(context, element, x, y, paint) {
    context.save();
    context.font = '10px sans-serif';
    context.textAlign = 'left';
    context.textBaseline = 'middle';
    var metrics = context.measureText(element.labels[0].textContent);
-   context.beginPath();
-   context.strokeStyle = 'black';
-   context.rect(x-5, y-5, 10, 10);
-   context.stroke();
-   if (element.checked) {
-     context.fillStyle = 'black';
-     context.fill();
+   if (paint) {
+<strong>     context.beginPath();
+     context.strokeStyle = 'black';
+     context.rect(x-5, y-5, 10, 10);
+     context.stroke();
+</strong>     if (element.checked) {
+<strong>       context.fillStyle = 'black';
+       context.fill();
+</strong>     }
+     context.fillText(element.labels[0].textContent, x+5, y);
    }
-   context.fillText(element.labels[0].textContent, x+5, y);
-   context.beginPath();
+<strong>   context.beginPath();
    context.rect(x-7, y-7, 12 + metrics.width+2, 14);
-   if (context.drawFocusRing(element, x, y, true)) {
+   if (paint && context.drawCustomFocusRing(element)) {
      context.strokeStyle = 'silver';
      context.stroke();
    }
-   context.restore();
+</strong>   context.restore();
  }
  function drawBase() { /* ... */ }
  function drawAs() { /* ... */ }
@@ -35925,8 +35989,8 @@
    var canvas = document.getElementsByTagName('canvas')[0];
    var context = canvas.getContext('2d');
    context.clearRect(0, 0, canvas.width, canvas.height);
-   drawCheckbox(context, document.getElementById('showA'), 20, 40);
-   drawCheckbox(context, document.getElementById('showB'), 20, 60);
+   drawCheckbox(context, document.getElementById('showA'), 20, 40, true);
+   drawCheckbox(context, document.getElementById('showB'), 20, 60, true);
    drawBase();
    if (document.getElementById('showA').checked)
      drawAs();
@@ -35936,12 +36000,17 @@
  function processClick(event) {
    var canvas = document.getElementsByTagName('canvas')[0];
    var context = canvas.getContext('2d');
-   var x = event.clientX - canvas.offsetLeft;
-   var y = event.clientY - canvas.offsetTop;
-   drawCheckbox(context, document.getElementById('showA'), 20, 40);
+   var x = event.clientX;
+   var y = event.clientY;
+   while (node) {
+     x -= node.offsetLeft - node.scrollLeft;
+     y -= node.offsetTop - node.scrollTop;
+     node = node.offsetParent;
+   }
+   drawCheckbox(context, document.getElementById('showA'), 20, 40, false);
    if (context.isPointInPath(x, y))
      document.getElementById('showA').checked = !(document.getElementById('showA').checked);
-   drawCheckbox(context, document.getElementById('showB'), 20, 60);
+   drawCheckbox(context, document.getElementById('showB'), 20, 60, false);
    if (context.isPointInPath(x, y))
      document.getElementById('showB').checked = !(document.getElementById('showB').checked);
    redraw();
@@ -35957,8 +36026,10 @@
   </div>
 
 
-  <h6 id=text-0><span class=secno>4.8.11.1.10 </span>Text</h6> <!-- a v3 feature -->
 
+
+  <h6 id=text-0><span class=secno>4.8.11.1.9 </span>Text</h6> <!-- a v3 feature -->
+
   <dl class=domintro><dt><var title="">context</var> . <code title=dom-context-2d-font><a href=#dom-context-2d-font>font</a></code> [ = <var title="">value</var> ]</dt>
 
    <dd>
@@ -36465,7 +36536,7 @@
 
 
 
-  <h6 id=images><span class=secno>4.8.11.1.11 </span>Images</h6>
+  <h6 id=images><span class=secno>4.8.11.1.10 </span>Images</h6>
 
   <p>To draw images onto the canvas, the <dfn id=dom-context-2d-drawimage title=dom-context-2d-drawImage><code>drawImage</code></dfn> method
   can be used.</p>
@@ -36606,7 +36677,7 @@
 
 
 
-  <h6 id=pixel-manipulation><span class=secno>4.8.11.1.12 </span><dfn>Pixel manipulation</dfn></h6>
+  <h6 id=pixel-manipulation><span class=secno>4.8.11.1.11 </span><dfn>Pixel manipulation</dfn></h6>
 
   <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>
 
@@ -36965,7 +37036,7 @@
 
   <div class=impl>
 
-  <h6 id=drawing-model><span class=secno>4.8.11.1.13 </span><dfn>Drawing model</dfn></h6>
+  <h6 id=drawing-model><span class=secno>4.8.11.1.12 </span><dfn>Drawing model</dfn></h6>
 
   <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>
@@ -36996,6 +37067,68 @@
   </ol></div>
 
 
+  <h6 id=best-practices><span class=secno>4.8.11.1.13 </span>Best practices</h6>
+
+  <p><i>This section is non-normative.</i></p>
+
+  <p>When a canvas is interactive, authors should include focusable
+  elements in the element's fallback content corresponding to each
+  focusable part of the canvas, as in the <a href=#drawCustomFocusRingExample>example above</a>.</p>
+
+  <p>To indicate which focusable part of the canvas is currently
+  focused, authors should use the <code title=dom-context-2d-drawOSFocusRing><a href=#dom-context-2d-drawosfocusring>drawOSFocusRing()</a></code> method,
+  passing it the element for which a ring is being drawn. This method
+  only draws the focus ring if the element is focused, so that it can
+  simply be called whenever drawing the element, without checking
+  whether the element is focused or not first.</p>
+
+  <p>Authors should avoid implementing text editing controls using the
+  <code><a href=#the-canvas-element>canvas</a></code> element. Doing so has a large number of
+  disadvantages:</p>
+
+  <ul><li>Mouse placement of the caret has to be reimplemented.</li>
+
+   <li>Keyboard movement of the caret has to be reimplemented (possibly across lines, for multiline text input).</li>
+
+   <li>Scrolling of the text field has to be implemented (horizontally for long lines, vertically for multiline input).</li>
+
+   <li>Native features such as copy-and-paste have to be reimplemented.</li>
+
+   <li>Native features such as spell-checking have to be reimplemented.</li>
+
+   <li>Native features such as drag-and-drop have to be reimplemented.</li>
+
+   <li>Native features such as page-wide text search have to be reimplemented.</li>
+
+   <li>Native features specific to the user, for example custom text
+   services, have to be reimplemented. This is close to impossible
+   since each user might have different services installed, and there
+   is an unbounded set of possible such services.</li>
+
+   <li>Bidirectional text editing has to be reimplemented.</li>
+
+   <li>For multiline text editing, line wrapping has to be implemented for all relevant languages.</li>
+
+   <li>Text selection has to be reimplemented.</li>
+
+   <li>Dragging of bidirectional text selections has to be reimplemented.</li>
+
+   <li>Platform-native keyboard shortcuts have to be reimplemented.</li>
+
+   <li>Platform-native input method editors (IMEs) have to be reimplemented.</li>
+
+   <li>Undo and redo functionality has to be reimplemented.</li>
+
+   <li>Accessibility features such as magnification following the
+   caret or selection have to be reimplemented.</li>
+
+  </ul><p>This is a huge amount of work, and authors are most strongly
+  encouraged to avoid doing any of it by instead using the
+  <code><a href=#the-input-element>input</a></code> element, the <code><a href=#the-textarea-element>textarea</a></code> element, or
+  the <code title=attr-contenteditable><a href=#attr-contenteditable>contenteditable</a></code>
+  attribute.</p>
+
+
   <h6 id=examples><span class=secno>4.8.11.1.14 </span>Examples</h6>
 
   <p><i>This section is non-normative.</i></p>

Modified: source
===================================================================
--- source	2011-05-09 22:22:16 UTC (rev 6124)
+++ source	2011-05-11 00:08:45 UTC (rev 6125)
@@ -176,6 +176,14 @@
    <li><a href="#crossDocumentMessages">Cross-document messaging</a> (also known as Communications)<!--POSTMSG-->
    <li><a href="#channel-messaging">Channel messaging</a> (also known as Communications)<!--POSTMSG-->
   </ul>
+  
+  <p>The specification that covers the Canvas 2D Graphics Context at
+  the W3C does not include all the advice included in the equivalent
+  section in this document, because of <a
+  href="http://lists.w3.org/Archives/Public/public-html/2011Apr/0712.html">the
+  discussion</a> that followed <a
+  href="http://lists.w3.org/Archives/Public/public-html/2011Apr/0271.html">a
+  working gorup decision from April 2011</a>.</p>
 
   <p>The <a href="#forms">forms</a> part of this specification was
   previously published separately in a specification known as Web
@@ -37675,7 +37683,7 @@
 
   <h5 id="2dcontext">The 2D context</h5>
 
-  <!-- v2: we're on v4. suggestions for next version are marked v5. -->
+  <!-- v2: we're on v4.1. suggestions for next version are marked v5. -->
 
   <!--START 2dcontext-->
 
@@ -37776,12 +37784,12 @@
   void <span title="dom-context-2d-arc">arc</span>(in double x, in double y, in double radius, in double startAngle, in double endAngle, in optional boolean anticlockwise);
   void <span title="dom-context-2d-fill">fill</span>();
   void <span title="dom-context-2d-stroke">stroke</span>();
+  void <span title="dom-context-2d-drawOSFocusRing">drawOSFocusRing</span>(in <span>Element</span> element);
+  boolean <span title="dom-context-2d-drawCustomFocusRing">drawCustomFocusRing</span>(in <span>Element</span> element);
+  void <span title="dom-context-2d-scrollPathIntoView">scrollPathIntoView</span>();
   void <span title="dom-context-2d-clip">clip</span>();
   boolean <span title="dom-context-2d-isPointInPath">isPointInPath</span>(in double x, in double y);
 
-  // focus management
-  boolean <span title="dom-context-2d-drawFocusRing">drawFocusRing</span>(in <span>Element</span> element, in double xCaret, in double yCaret, in optional boolean canDrawCustom);
-
   // text
            attribute DOMString <span title="dom-context-2d-font">font</span>; // (default 10px sans-serif)
            attribute DOMString <span title="dom-context-2d-textAlign">textAlign</span>; // "start", "end", "left", "right", "center" (default: "start")
@@ -39346,6 +39354,42 @@
 
    </dd>
 
+   <dt><var title="">context</var> . <code title="dom-context-2d-drawOSFocusRing">drawOSFocusRing</code>(<var title="">element</var>)</dt>
+
+   <dd>
+
+    <p>If the given element is focused, draws a focus ring around the
+    current path, following the platform conventions for focus
+    rings.</p>
+
+   </dd>
+
+   <dt><var title="">shouldDraw</var> = <var title="">context</var> . <code title="dom-context-2d-drawCustomFocusRing">drawCustomFocusRing</code>(<var title="">element</var>)</dt>
+
+   <dd>
+
+    <p>If the given element is focused, and the user has configured
+    his system to draw focus rings in a particular manner (for
+    example, high contrast focus rings), draws a focus ring around the
+    current path and returns false.</p>
+
+    <p>Otherwise, returns true if the given element is focused, and
+    false otherwise. This can thus be used to determine when to draw a
+    focus ring (see <a href="#drawCustomFocusRingExample">the
+    example</a> below).</p>
+
+   </dd>
+
+   <dt><var title="">context</var> . <code title="dom-context-2d-scrollPathIntoView">scrollPathIntoView</code>()</dt>
+
+   <dd>
+
+    <p>Scrolls the current path into view. This is especially useful
+    on devices with small screens, where the whole canvas might not be
+    visible at once.</p>
+
+   </dd>
+
    <dt><var title="">context</var> . <code title="dom-context-2d-clip">clip</code>()</dt>
 
    <dd>
@@ -39611,95 +39655,58 @@
   <p>Zero-length line segments must be pruned before stroking a
   path. Empty subpaths must be ignored.</p>
 
+  <hr>
 
-  <p>The <dfn title="dom-context-2d-clip"><code>clip()</code></dfn>
-  method must create a new <dfn>clipping region</dfn> by calculating
-  the intersection of the current clipping region and the area
-  described by the current path, using the non-zero winding number
-  rule. Open subpaths must be implicitly closed when computing the
-  clipping region, without affecting the actual subpaths. The new
-  clipping region replaces the current clipping region.</p>
-
-  <p>When the context is initialized, the clipping region must be set
-  to the rectangle with the top left corner at (0,0) and the width and
-  height of the coordinate space.</p>
-
-  <!-- v5
-   Jordan OSETE suggests:
-    * support ways of extending the clipping region (union instead of intersection)
-       - also "add", "subtract", "replace", "intersect" and "xor"
-    * support ways of resetting the clipping region without save/restore
-  -->
-
-
   <p>The <dfn
-  title="dom-context-2d-isPointInPath"><code>isPointInPath(<var
-  title="">x</var>, <var title="">y</var>)</code></dfn> method must
-  return true if the point given by the <var title="">x</var> and <var
-  title="">y</var> coordinates passed to the method, when treated as
-  coordinates in the canvas coordinate space unaffected by the current
-  transformation, is inside the current path as determined by the
-  non-zero winding number rule; and must return false
-  otherwise. Points on the path itself are considered to be inside the
-  path. If either of the arguments is infinite or NaN, then the method
-  must return false.</p>
+  title="dom-context-2d-drawOSFocusRing"><code>drawOSFocusRing(<var
+  title="">element</var>)</code></dfn> method, when invoked,
+  must run the following steps:</p>
 
-  </div>
+  <ol>
 
+   <li><p>If <var title="">element</var> is not focused or is not a
+   descendant of the element with whose context the method is
+   associated, then abort these steps.</p></li>
 
-  <h6>Focus management</h6> <!-- a v4 feature -->
+   <li>
 
-  <p>When a canvas is interactive, authors should include focusable
-  elements in the element's fallback content corresponding to each
-  focusable part of the canvas.</p>
+    <p>If the user has requested the use of particular focus rings
+    (e.g. high-contrast focus rings), or if the <var
+    title="">element</var> would have a focus ring drawn around it,
+    then draw a focus ring of the appropriate style along the path,
+    following platform conventions, and abort these steps.</p>
 
-  <p>To indicate which focusable part of the canvas is currently
-  focused, authors should use the <code
-  title="dom-context-2d-drawFocusRing">drawFocusRing()</code> method,
-  passing it the element for which a ring is being drawn. This method
-  only draws the focus ring if the element is focused, so that it can
-  simply be called whenever drawing the element, without checking
-  whether the element is focused or not first. The position of the
-  center of the control, or of the editing caret if the control has
-  one, should be given in the <var title="">x</var> and <var
-  title="">y</var> arguments.</p>
+    <p class="note">Some platforms only draw focus rings around
+    elements that have been focused from the keyboard, and not those
+    focused from the mouse. Other platforms simply don't draw focus
+    rings around some elements at all unless relevant accessibility
+    features are enabled. This API is intended to follow these
+    conventions.</p>
 
-  <dl class="domintro">
+    <p>The focus ring should not be subject to the <span
+    title="shadows">shadow effects</span>, the <span
+    title="dom-context-2d-globalAlpha">global alpha</span>, or the <span
+    title="dom-context-2d-globalCompositeOperation">global composition
+    operators</span>, but <em>should</em> be subject to the <span
+    title="clipping region">clipping region</span>.</p>
 
-   <dt><var title="">shouldDraw</var> = <var title="">context</var> . <code title="dom-context-2d-drawFocusRing">drawFocusRing</code>(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>, [ <var title="">canDrawCustom</var> ])</dt>
+   </li>
 
-   <dd>
+   <li>
 
-    <p>If the given element is focused, draws a focus ring around the
-    current path, following the platform conventions for focus
-    rings. The given coordinate is used if the user's attention needs
-    to be brought to a particular position (e.g. if a magnifier is
-    following the editing caret in a text field).</p>
+    <p>Optionally, <a href="#inform">inform the user</a> that the
+    focus is at the location given by the path. User agents may wait
+    until the next time the <span>event loop</span> reaches its
+    "update the rendering" step to optionally inform the user.</p>
 
-    <p>If the <var title="">canDrawCustom</var> argument is true, then
-    the focus ring is only drawn if the user has configured his system
-    to draw focus rings in a particular manner. (For example, high
-    contrast focus rings.)</p>
+   </li>
 
-    <p>Returns true if the given element is focused, the <var
-    title="">canDrawCustom</var> argument is true, and the user has
-    not configured his system to draw focus rings in a particular
-    manner. Otherwise, returns false.</p>
+  </ol>
 
-    <p>When the method returns true, the author is expected to
-    manually draw a focus ring.</p>
-
-   </dd>
-
-  </dl>
-
-  <div class="impl">
-
   <p>The <dfn
-  title="dom-context-2d-drawFocusRing"><code>drawFocusRing(<var
-  title="">element</var>, <var title="">x</var>, <var
-  title="">y</var>, [<var title="">canDrawCustom</var>])</code></dfn>
-  method, when invoked, must run the following steps:</p>
+  title="dom-context-2d-drawCustomFocusRing"><code>drawCustomFocusRing(<var
+  title="">element</var>)</code></dfn> method, when invoked, must run
+  the following steps:</p>
 
   <ol>
 
@@ -39707,22 +39714,11 @@
    descendant of the element with whose context the method is
    associated, then return false and abort these steps.</p></li>
 
-   <li><p>Transform the given point (<var title="">x</var>, <var
-   title="">y</var>) according to the <span
-   title="dom-context-2d-transformation">current transformation
-   matrix</span>.</p></li>
-
-   <li><p>Optionally, inform the user that the focus is at the given
-   (transformed) coordinate on the canvas. (For example, this could
-   involve moving the user's magnification tool.)</p></li>
-
    <li>
 
     <p>If the user has requested the use of particular focus rings
-    (e.g. high-contrast focus rings), or if the <var
-    title="">canDrawCustom</var> argument is absent or false, then
-    draw a focus ring of the appropriate style along the path,
-    following platform conventions, return false, and abort these
+    (e.g. high-contrast focus rings), then draw a focus ring of the
+    appropriate style along the path, return false, and abort these
     steps.</p>
 
     <p>The focus ring should not be subject to the <span
@@ -39734,44 +39730,128 @@
 
    </li>
 
+   <li>
+
+    <p>Optionally, <a href="#inform">inform the user</a> that the
+    focus is at the location given by the path. User agents may wait
+    until the next time the <span>event loop</span> reaches its
+    "update the rendering" step to optionally inform the user.</p>
+
+   </li>
+
    <li><p>Return true.</p></li>
 
   </ol>
 
+  <p>The <dfn
+  title="dom-context-2d-scrollPathIntoView"><code>scrollPathIntoView()</code></dfn>
+  method, when invoked, must run the following steps:</p>
+
+  <ol>
+
+   <li><p>Let <var title="">notional child</var> be a hypothetical
+   element that is a rendered child of the <code>canvas</code> element
+   whose dimensions are exactly the rectangle of the bounding box of
+   the current path.</p></li>
+
+   <li><p><span title="scroll an element into view">Scroll <var
+   title="">notional child</var> into view</span> with the <var
+   title="">align to top flag</var> set.</p>
+
+   <li><p>Optionally, <a href="#inform">inform the user</a> that the
+   caret and/or selection cover <var title="">the specified
+   rectangle</var> of the canvas. User agents may wait until the next
+   time the <span>event loop</span> reaches its "update the rendering"
+   step to optionally inform the user.</p></li>
+
+  </ol>
+
+  <p class="note" id="inform">"Inform the user", as used in this
+  section, could mean calling a system accessibility API, which would
+  notify assistive technologies such as magnification tools. To
+  properly drive magnification based on a focus change, a system
+  accessibility API driving a screen magnifier needs the bounds for
+  the newly focused object. The methods above are intended to enable
+  this by allowing the user agent to report the bounding box of the
+  path used to render the focus ring as the bounds of the <var
+  title="">element</var> element passed as an argument, if that
+  element is focused, and the bounding box of the area to which the
+  user agent is scrolling as the bounding box of the current
+  selection.</p>
+
+  <hr>
+
+  <p>The <dfn title="dom-context-2d-clip"><code>clip()</code></dfn>
+  method must create a new <dfn>clipping region</dfn> by calculating
+  the intersection of the current clipping region and the area
+  described by the current path, using the non-zero winding number
+  rule. Open subpaths must be implicitly closed when computing the
+  clipping region, without affecting the actual subpaths. The new
+  clipping region replaces the current clipping region.</p>
+
+  <p>When the context is initialized, the clipping region must be set
+  to the rectangle with the top left corner at (0,0) and the width and
+  height of the coordinate space.</p>
+
+  <!-- v5
+   Jordan OSETE suggests:
+    * support ways of extending the clipping region (union instead of intersection)
+       - also "add", "subtract", "replace", "intersect" and "xor"
+    * support ways of resetting the clipping region without save/restore
+  -->
+
+  <hr>
+
+  <p>The <dfn
+  title="dom-context-2d-isPointInPath"><code>isPointInPath(<var
+  title="">x</var>, <var title="">y</var>)</code></dfn> method must
+  return true if the point given by the <var title="">x</var> and <var
+  title="">y</var> coordinates passed to the method, when treated as
+  coordinates in the canvas coordinate space unaffected by the current
+  transformation, is inside the current path as determined by the
+  non-zero winding number rule; and must return false
+  otherwise. Points on the path itself are considered to be inside the
+  path. If either of the arguments is infinite or NaN, then the method
+  must return false.</p>
+
   </div>
 
-  <div class="example">
 
-   <p>This <code>canvas</code> element has a couple of checkboxes:</p>
+  <div class="example" id="drawCustomFocusRingExample">
 
+   <p>This <code>canvas</code> element has a couple of checkboxes. The
+   path-related commands are highlighted:</p>
+
    <pre><canvas height=400 width=750>
  <label><input type=checkbox id=showA> Show As</label>
  <label><input type=checkbox id=showB> Show Bs</label>
  <!-- ... -->
 </canvas>
 <script>
- function drawCheckbox(context, element, x, y) {
+ function drawCheckbox(context, element, x, y, paint) {
    context.save();
    context.font = '10px sans-serif';
    context.textAlign = 'left';
    context.textBaseline = 'middle';
    var metrics = context.measureText(element.labels[0].textContent);
-   context.beginPath();
-   context.strokeStyle = 'black';
-   context.rect(x-5, y-5, 10, 10);
-   context.stroke();
-   if (element.checked) {
-     context.fillStyle = 'black';
-     context.fill();
+   if (paint) {
+<strong>     context.beginPath();
+     context.strokeStyle = 'black';
+     context.rect(x-5, y-5, 10, 10);
+     context.stroke();
+</strong>     if (element.checked) {
+<strong>       context.fillStyle = 'black';
+       context.fill();
+</strong>     }
+     context.fillText(element.labels[0].textContent, x+5, y);
    }
-   context.fillText(element.labels[0].textContent, x+5, y);
-   context.beginPath();
+<strong>   context.beginPath();
    context.rect(x-7, y-7, 12 + metrics.width+2, 14);
-   if (context.drawFocusRing(element, x, y, true)) {
+   if (paint && context.drawCustomFocusRing(element)) {
      context.strokeStyle = 'silver';
      context.stroke();
    }
-   context.restore();
+</strong>   context.restore();
  }
  function drawBase() { /* ... */ }
  function drawAs() { /* ... */ }
@@ -39780,8 +39860,8 @@
    var canvas = document.getElementsByTagName('canvas')[0];
    var context = canvas.getContext('2d');
    context.clearRect(0, 0, canvas.width, canvas.height);
-   drawCheckbox(context, document.getElementById('showA'), 20, 40);
-   drawCheckbox(context, document.getElementById('showB'), 20, 60);
+   drawCheckbox(context, document.getElementById('showA'), 20, 40, true);
+   drawCheckbox(context, document.getElementById('showB'), 20, 60, true);
    drawBase();
    if (document.getElementById('showA').checked)
      drawAs();
@@ -39791,12 +39871,17 @@
  function processClick(event) {
    var canvas = document.getElementsByTagName('canvas')[0];
    var context = canvas.getContext('2d');
-   var x = event.clientX - canvas.offsetLeft;
-   var y = event.clientY - canvas.offsetTop;
-   drawCheckbox(context, document.getElementById('showA'), 20, 40);
+   var x = event.clientX;
+   var y = event.clientY;
+   while (node) {
+     x -= node.offsetLeft - node.scrollLeft;
+     y -= node.offsetTop - node.scrollTop;
+     node = node.offsetParent;
+   }
+   drawCheckbox(context, document.getElementById('showA'), 20, 40, false);
    if (context.isPointInPath(x, y))
      document.getElementById('showA').checked = !(document.getElementById('showA').checked);
-   drawCheckbox(context, document.getElementById('showB'), 20, 60);
+   drawCheckbox(context, document.getElementById('showB'), 20, 60, false);
    if (context.isPointInPath(x, y))
      document.getElementById('showB').checked = !(document.getElementById('showB').checked);
    redraw();
@@ -39812,6 +39897,8 @@
   </div>
 
 
+
+
   <h6>Text</h6> <!-- a v3 feature -->
 
   <dl class="domintro">
@@ -41074,6 +41161,74 @@
   </div>
 
 
+  <h6>Best practices</h6>
+
+  <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+  <p>When a canvas is interactive, authors should include focusable
+  elements in the element's fallback content corresponding to each
+  focusable part of the canvas, as in the <a
+  href="#drawCustomFocusRingExample">example above</a>.</p>
+
+  <p>To indicate which focusable part of the canvas is currently
+  focused, authors should use the <code
+  title="dom-context-2d-drawOSFocusRing">drawOSFocusRing()</code> method,
+  passing it the element for which a ring is being drawn. This method
+  only draws the focus ring if the element is focused, so that it can
+  simply be called whenever drawing the element, without checking
+  whether the element is focused or not first.</p>
+
+  <p>Authors should avoid implementing text editing controls using the
+  <code>canvas</code> element. Doing so has a large number of
+  disadvantages:</p>
+
+  <ul>
+
+   <li>Mouse placement of the caret has to be reimplemented.</li>
+
+   <li>Keyboard movement of the caret has to be reimplemented (possibly across lines, for multiline text input).</li>
+
+   <li>Scrolling of the text field has to be implemented (horizontally for long lines, vertically for multiline input).</li>
+
+   <li>Native features such as copy-and-paste have to be reimplemented.</li>
+
+   <li>Native features such as spell-checking have to be reimplemented.</li>
+
+   <li>Native features such as drag-and-drop have to be reimplemented.</li>
+
+   <li>Native features such as page-wide text search have to be reimplemented.</li>
+
+   <li>Native features specific to the user, for example custom text
+   services, have to be reimplemented. This is close to impossible
+   since each user might have different services installed, and there
+   is an unbounded set of possible such services.</li>
+
+   <li>Bidirectional text editing has to be reimplemented.</li>
+
+   <li>For multiline text editing, line wrapping has to be implemented for all relevant languages.</li>
+
+   <li>Text selection has to be reimplemented.</li>
+
+   <li>Dragging of bidirectional text selections has to be reimplemented.</li>
+
+   <li>Platform-native keyboard shortcuts have to be reimplemented.</li>
+
+   <li>Platform-native input method editors (IMEs) have to be reimplemented.</li>
+
+   <li>Undo and redo functionality has to be reimplemented.</li>
+
+   <li>Accessibility features such as magnification following the
+   caret or selection have to be reimplemented.</li>
+
+  </ul>
+
+  <p>This is a huge amount of work, and authors are most strongly
+  encouraged to avoid doing any of it by instead using the
+  <code>input</code> element, the <code>textarea</code> element, or
+  the <code title="attr-contenteditable">contenteditable</code>
+  attribute.</p>
+
+
   <h6>Examples</h6>
 
   <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->




More information about the Commit-Watchers mailing list