W3C home > Mailing lists > Public > public-html-commits@w3.org > January 2010

html5/spec Overview.html,1.3564,1.3565

From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
Date: Tue, 05 Jan 2010 02:54:40 +0000
To: public-html-commits@w3.org
Message-Id: <E1NRzZA-0004bK-Uh@lionel-hutz.w3.org>
Update of /sources/public/html5/spec
In directory hutz:/tmp/cvs-serv17640

Modified Files:
	Overview.html 
Log Message:
drawFocusRing() support (whatwg r4465)

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec/Overview.html,v
retrieving revision 1.3564
retrieving revision 1.3565
diff -u -d -r1.3564 -r1.3565
--- Overview.html	5 Jan 2010 00:58:43 -0000	1.3564
+++ Overview.html	5 Jan 2010 02:54:37 -0000	1.3565
@@ -654,11 +654,12 @@
          <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="#text"><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="#examples"><span class="secno">4.8.11.1.13 </span>Examples</a></ol></li>
+         <li><a href="#focus-management-0"><span class="secno">4.8.11.1.9 </span>Focus management</a></li>
+         <li><a href="#text"><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="#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>
      <li><a href="#the-map-element"><span class="secno">4.8.12 </span>The <code>map</code> element</a></li>
@@ -21482,7 +21483,7 @@
   more carefully control compression settings, image metadata,
   etc.</p>
 
-  </div><h5 id="the-2d-context"><span class="secno">4.8.11.1 </span>The 2D context</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><!-- v2: we're on v3. suggestions for next version are marked v4. --><p>When the <code title="dom-canvas-getContext"><a href="#dom-canvas-getcontext">getContext()</a></code>
+  </div><h5 id="the-2d-context"><span class="secno">4.8.11.1 </span>The 2D context</h5><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><!-- v2: we're on v4. suggestions for next version are marked v5. --><p>When the <code title="dom-canvas-getContext"><a href="#dom-canvas-getcontext">getContext()</a></code>
   method of a <code><a href="#the-canvas-element">canvas</a></code> element is invoked with <dfn id="canvas-context-2d" title="canvas-context-2d"><code>2d</code></dfn> as the argument, a
   <code><a href="#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code> object is returned.<div class="impl">
 
@@ -21502,7 +21503,7 @@
   void <a href="#dom-context-2d-save" title="dom-context-2d-save">save</a>(); // push state on state stack
   void <a href="#dom-context-2d-restore" title="dom-context-2d-restore">restore</a>(); // pop state stack and restore state
 <!--
-  // v4 we've also received requests for:
+  // v5 we've also received requests for:
           attribute boolean <span title="dom-context-2d-forceHighQuality">forceHighQuality</span> // (default false)
   // when enabled, it would prevent the UA from falling back on lower-quality but faster rendering routines
   // useful e.g. for when an image manipulation app uses <canvas> both for UI previews and the actual work
@@ -21514,7 +21515,7 @@
   void <a href="#dom-context-2d-transform" title="dom-context-2d-transform">transform</a>(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy);
   void <a href="#dom-context-2d-settransform" title="dom-context-2d-setTransform">setTransform</a>(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy);
 <!--
-  // v4 we've also received requests for:
+  // v5 we've also received requests for:
   void skew(...);
   void reflect(...); // or mirror(...)
 -->
@@ -21522,7 +21523,7 @@
            attribute float <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">globalAlpha</a>; // (default 1.0)
            attribute DOMString <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">globalCompositeOperation</a>; // (default source-over)
 <!--
-  // v4 we've also received requests for:
+  // v5 we've also received requests for:
   - turning off antialiasing to avoid seams when patterns are painted next to each other
     - might be better to overdraw?
     - might be better to just draw at a higher res then downsample, like for 3d?
@@ -21571,12 +21572,15 @@
   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 float x, in float y);
 
+  // focus management
+  boolean <a href="#dom-context-2d-drawfocusring" title="dom-context-2d-drawFocusRing">drawFocusRing</a>(in <span>Element</span> element, in float xCaret, in float yCaret, in optional 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")
            attribute DOMString <a href="#dom-context-2d-textbaseline" title="dom-context-2d-textBaseline">textBaseline</a>; // "top", "hanging", "middle", "alphabetic", "ideographic", "bottom" (default: "alphabetic")
   void <a href="#dom-context-2d-filltext" title="dom-context-2d-fillText">fillText</a>(in DOMString text, in float x, in float y, in optional float maxWidth);
-  void <a href="#dom-context-2d-stroketext" title="dom-context-2d-strokeText">strokeText</a>(in DOMString text, in float x, in float y, in optional float maxWidth);<!-- v4DVT
+  void <a href="#dom-context-2d-stroketext" title="dom-context-2d-strokeText">strokeText</a>(in DOMString text, in float x, in float y, in optional float maxWidth);<!-- v5DVT
   void <span title="dom-context-2d-fillVerticalText">fillVerticalText</span>(in DOMString text, in float x, in float y, in optional float maxHeight);
   void <span title="dom-context-2d-strokeVerticalText">strokeVerticalText</span>(in DOMString text, in float x, in float y, in optional float maxHeight); -->
   <a href="#textmetrics">TextMetrics</a> <a href="#dom-context-2d-measuretext" title="dom-context-2d-measureText">measureText</a>(in DOMString text);
@@ -21695,7 +21699,7 @@
   drawing state it describes. If there is no saved state, the method
   must do nothing.</p>
 
-  <!-- v4
+  <!-- v5
 idea from Mihai:
 > 5. Drawing states should be saveable with IDs, and for easier restoring.
 >
@@ -21986,7 +21990,7 @@
 
   </dl><div class="impl">
 
-  <!-- v4 feature requests:
+  <!-- v5 feature requests:
 
    * Getting and setting colours by component to bypass the CSS value parsing.
 
@@ -22298,7 +22302,7 @@
   <!-- drawImage() has an equivalent paragraph -->
 
   <!--
-   Requests for v4 features:
+   Requests for v5 features:
     * apply transforms to patterns, so you don't have to create
       transformed patterns manually by rendering them to an off-screen
       canvas then using that canvas as the pattern.
@@ -22452,7 +22456,7 @@
   initially have the value <code>10.0</code>.</p>
 
   <!--
-v4: dashed lines have been requested. Philip Taylor provides these
+v5: dashed lines have been requested. Philip Taylor provides these
 notes on what would need to be defined for dashed lines:
 > I don't think it's entirely trivial to add, to the detail that's
 > necessary in a specification. The common graphics APIs (at least
@@ -22937,7 +22941,7 @@
   a new subpath with the point (<var title="">x</var>, <var title="">y</var>) as the only point in the subpath.</p>
 
 
-  <!-- v4 feature request:
+  <!-- v5 feature request:
         * points as a primitive shape
           http://home.comcast.net/~urbanjost/canvas/vogle4.html
   -->
@@ -22989,7 +22993,7 @@
   to the rectangle with the top left corner at (0,0) and the width and
   height of the coordinate space.</p>
 
-  <!-- v4
+  <!-- v5
    Jordan OSETE suggests:
     * support ways of extending the clipping region (union instead of intersection)
        - also "add", "subtract", "replace", "intersect" and "xor"
@@ -23006,7 +23010,140 @@
   path. If either of the arguments is infinite or NaN, then the method
   must return false.</p>
 
-  </div><h6 id="text"><span class="secno">4.8.11.1.9 </span>Text</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><!-- 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>
+  </div><h6 id="focus-management-0"><span class="secno">4.8.11.1.9 </span>Focus management</h6><!-- a v4 feature --><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>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.<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 user 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>&lt;canvas height=400 width=750&gt;
+ &lt;label&gt;&lt;input type=checkbox id=showA&gt; Show As&lt;/label&gt;
+ &lt;label&gt;&lt;input type=checkbox id=showB&gt; Show Bs&lt;/label&gt;
+ &lt;!-- ... --&gt;
+&lt;/canvas&gt;
+&lt;script&gt;
+ function drawCheckbox(context, element, x, y) {
+   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();
+   }
+   context.fillText(element.labels[0].textContent, x+5, y);
+   context.beginPath();
+   context.rect(x-7, y-7, 12 + metrics.width+2, 14);
+   if (context.drawFocusRing(element, x, y, true)) {
+     context.strokeStyle = 'silver';
+     context.stroke();
+   }
+   context.restore();
+ }
+ function drawBase() { /* ... */ }
+ function drawAs() { /* ... */ }
+ function drawBs() { /* ... */ }
+ function redraw() {
+   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);
+   drawBase();
+   if (document.getElementById('showA').checked)
+     drawAs();
+   if (document.getElementById('showB').checked)
+     drawBs();
+ }
+ 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);
+   if (context.isPointInPath(x, y))
+     document.getElementById('showA').checked = !(document.getElementById('showA').checked);
+   drawCheckbox(context, document.getElementById('showB'), 20, 60);
+   if (context.isPointInPath(x, y))
+     document.getElementById('showB').checked = !(document.getElementById('showB').checked);
+   redraw();
+ }
+ document.getElementsByTagName('canvas')[0].addEventListener('focus', redraw, true);
+ document.getElementsByTagName('canvas')[0].addEventListener('blur', redraw, true);
+ document.getElementsByTagName('canvas')[0].addEventListener('change', redraw, true);
+ document.getElementsByTagName('canvas')[0].addEventListener('click', processClick, false);
+ redraw();
+&lt;/script&gt;</pre>
+<!-- http://software.hixie.ch/utilities/js/live-dom-viewer/saved/340 -->
+
+  </div><h6 id="text"><span class="secno">4.8.11.1.10 </span>Text</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p><!-- 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>
 
@@ -23316,7 +23453,7 @@
 
    </li>
 
-  </ol><!--v4DVT - this is commented out until CSS can get its act together
+  </ol><!--v5DVT - this is commented out until CSS can get its act together
 enough to actual specify vertical text rendering (how long have we
 been waiting now?)
 
@@ -23462,7 +23599,7 @@
 
   </ol>
 
-v4DVT (also check for '- -' bits in the part above) --><p>The <dfn id="dom-context-2d-measuretext" title="dom-context-2d-measureText"><code>measureText()</code></dfn>
+v5DVT (also check for '- -' bits in the part above) --><p>The <dfn id="dom-context-2d-measuretext" title="dom-context-2d-measureText"><code>measureText()</code></dfn>
   method takes one argument, <var title="">text</var>. When the method
   is invoked, the user agent must replace all the <a href="#space-character" title="space
   character">space characters</a> in <var title="">text</var> with
@@ -23491,15 +23628,15 @@
   area of the canvas that the clipping region covers, not just the box
   given by the em square height and measured text width.</p>
 
-  <!-- v4: Drawing text along a given path -->
-  <!-- v4: Adding text to a path -->
+  <!-- v5: Drawing text along a given path -->
+  <!-- v5: Adding text to a path -->
   <!-- see also: http://www.w3.org/TR/SVG11/text.html#TextpathLayoutRules -->
   <!-- see also: http://developer.mozilla.org/en/docs/Drawing_text_using_a_canvas -->
 
   </div><p class="note">A future version of the 2D context API may provide a
   way to render fragments of documents, rendered using CSS, straight
   to the canvas. This would be provided in preference to a dedicated
-  way of doing multiline layout.<h6 id="images"><span class="secno">4.8.11.1.10 </span>Images</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><p>To draw images onto the canvas, the <dfn id="dom-context-2d-drawimage" title="dom-context-2d-drawImage"><code>drawImage</code></dfn> method
+  way of doing multiline layout.<h6 id="images"><span class="secno">4.8.11.1.11 </span>Images</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><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>This method can be invoked with three different sets of arguments:<ul class="brief"><li><code title="">drawImage(<var title="">image</var>, <var title="">dx</var>, <var title="">dy</var>)</code>
    <li><code title="">drawImage(<var title="">image</var>, <var title="">dx</var>, <var title="">dy</var>, <var title="">dw</var>, <var title="">dh</var>)</code>
    <li><code title="">drawImage(<var title="">image</var>, <var title="">sx</var>, <var title="">sy</var>, <var title="">sw</var>, <var title="">sh</var>, <var title="">dx</var>, <var title="">dy</var>, <var title="">dw</var>, <var title="">dh</var>)</code>
@@ -23611,7 +23748,7 @@
   subject to <a href="#shadows" title="shadows">shadow effects</a>, <a href="#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, the <a href="#clipping-region" title="clipping region">clipping region</a>, and <a href="#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition
   operators</a>.</p>
 
-  </div><h6 id="pixel-manipulation"><span class="secno">4.8.11.1.11 </span><dfn>Pixel manipulation</dfn></h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><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>
+  </div><h6 id="pixel-manipulation"><span class="secno">4.8.11.1.12 </span><dfn>Pixel manipulation</dfn></h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><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>
 
    <dd>
 
@@ -23970,7 +24107,7 @@
 
   </div><div class="impl">
 
-  <h6 id="drawing-model"><span class="secno">4.8.11.1.12 </span>Drawing model</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
+  <h6 id="drawing-model"><span class="secno">4.8.11.1.13 </span>Drawing model</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i></p>
 
   <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>
@@ -23997,7 +24134,7 @@
    over the current canvas bitmap using the current composition
    operator.</li>
 
-  </ol></div><h6 id="examples"><span class="secno">4.8.11.1.13 </span>Examples</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><p><i>This section is non-normative.</i><p>Here is an example of a script that uses canvas to draw pretty
+  </ol></div><h6 id="examples"><span class="secno">4.8.11.1.14 </span>Examples</h6><p class="XXX annotation"><b>Status: </b><i>Last call for comments</i><p><i>This section is non-normative.</i><p>Here is an example of a script that uses canvas to draw pretty
   glowing lines.<pre>&lt;canvas width="800" height="450"&gt;&lt;/canvas&gt;
 &lt;script&gt;
 
Received on Tuesday, 5 January 2010 02:54:43 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 5 January 2010 02:54:44 GMT