- From: Michael Smith via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 14 Dec 2011 07:32:52 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/ReSpec.js
In directory hutz:/tmp/cvs-serv23747
Added Files:
.cvsignore Overview.html
Log Message:
new
--- NEW FILE: .cvsignore ---
nohup.out
--- NEW FILE: Overview.html ---
<!doctype html>
<meta charset=utf-8>
<title>HTML Canvas 2D Context Extensions</title>
<style>
body {
counter-reset: figcaption;
counter-reset: example;
}
figcaption {
font-weight: bold;
}
figcaption:before {
font-weight: bold;
content: "Figure " counter(figcaption) ": ";
counter-increment: figcaption;
}
var {
font-weight: bold;
color: green;
padding-left: 2px;
padding-right: 4px;
}
.tocline {
padding-top: 2px;
}
.ed_mailto:before {
content: "<";
}
.ed_mailto:after {
content: ">";
}
pre.example::before {
content: "Example " counter(example) " " !important;
counter-increment: example;
}
pre.widl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
pre.widl :link, pre.widl :visited { color: inherit; background: transparent; }
pre.widl::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
dl.domintro dd p { margin: 0.5em 0; }
dl.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
a.upstream-link:link:hover,
a.upstream-link:visited:hover {
background: #ffa;
color: #556b2f;
outline-offset: 4px;
outline: 3px solid blue;
}
</style>
<script class='remove'>
function addEllipsis(id) {
document.getElementById(id).childNodes.item(2).textContent = "\n …\n";
}
function removeNodes(nodesToRemove) {
var i, j;
for (i = 0; i < nodesToRemove.length; ++i) {
for (j = 0; j < nodesToRemove[i].length; ++j) {
nodesToRemove[i][j].parentNode.removeChild(nodesToRemove[i][j]);
}
}
}
</script>
<script class='remove'>
function getLastModifiedDate() {
var d = new Date(document.lastModified);
return d.toISOString().substring(0,10);
}
</script>
<script type="text/javascript" src='ReSpec.js/js/respec.js' class='remove'></script>
<script type="text/javascript" class='remove'>
var respecConfig =
{
specStatus: "ED",
shortName: "ime-api",
edDraftURI: "http://dev.w3.org/html5/canvas-extensions", // FIXME
editors: [
{ name: "Michael[tm] Smith",
mailto: "sideshowbarker@gmail.com"
},
],
wgURI: "http://www.w3.org/html/wg/",
wg: "HTML Working Group",
wgPublicList: "public-html-comments",
wgPatentURI: "[to come]",
publishDate: getLastModifiedDate(),
extraCSS: ["ReSpec.js/css/respec.css"],
after: function () {
var nodesToRemove = [
document.querySelectorAll("table.parameters"),
document.querySelectorAll("li.tocline > a[href^='#attributes']"),
document.querySelectorAll("li.tocline > a[href^='#methods']"),
]
addEllipsis('idl-def-HTMLElement');
removeNodes(nodesToRemove);
}
}
</script>
</head>
<body>
<section id='abstract'>
<p>This specification extends and overrides the
HTML Canvas 2D Context specification
[[!CANVAS-2D]]
with additional features
for caret and selection management,
for setting the caret blink rate,
for returning the vertical offset of a text anchor point,
and
for drawing a focus ring around the current path.</p>
</section>
<section id='sotd'>
<p>
This document is a proposal that is being made available for public
review in order to solicit feedback, <b>particularly from
implementors</b>, with a goal of potential cross-browser implementation
and standardization.
</p>
</section>
<section id="conformance">
<p>Interfaces are defined in terms of Web IDL [[!WEBIDL]].</p>
<p>This specification is an extension of the
HTML Canvas 2D Context specification
[[!CANVAS-2D]].
All normative content in the
HTML Canvas 2D Context specification,
unless specifically overridden by this specification, is intended to be
the basis for this specification.</p>
<p>This specification is an HTML specification. All the conformance
requirements, conformance classes, definitions, dependencies,
terminology, and typographical conventions described in the core
HTML5 specification apply to this specification. [[!HTML5]].</p>
</section>
<section id="the-CanvasRenderingContext2D-interface">
<h2>The CanvasRenderingContext2D interface</h2>
<p>This specification overrides and extends the <dfn id="canvas-context-2d" title="canvas-context-2d"><code>2d</code></dfn> context type, whose
API is implemented using the
<code><a href="http://dev.w3.org/html5/2dcontext/#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>
interface.</p>
<p>Conforming user agents MUST implement the
<code><a href="http://dev.w3.org/html5/2dcontext/#canvasrenderingcontext2d">CanvasRenderingContext2D</a></code>
interface as specified in the following IDL definition.</p>
<p class=note>Hyperlink references marked up with
<code>class=upstream</code> in the following IDL and throughout other parts
of this document
are links to definitions in the
HTML Canvas 2D Context specification
[[!CANVAS-2D]].
In order to make them easy to identify visually, those links are rendered
with a blue outline on hover.
Because this HTML Canvas 2D Context Extensions specification overrides and
extends the
HTML Canvas 2D Context specification,
be careful to return to this HTML
Canvas 2D Context Extensions specification after visiting the HTML Canvas
2D Context specification. </p>
<pre class="widl">interface <dfn id="canvasrenderingcontext2d">CanvasRenderingContext2D</dfn> {
// back-reference to the canvas
readonly attribute <span>HTMLCanvasElement</span> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-canvas" title="dom-context-2d-canvas">canvas</a>;
// state
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-save" title="dom-context-2d-save">save</a>(); // push state on state stack
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-restore" title="dom-context-2d-restore">restore</a>(); // pop state stack and restore state
// transformations (default transform is the identity matrix)
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-scale" title="dom-context-2d-scale">scale</a>(double x, double y);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-rotate" title="dom-context-2d-rotate">rotate</a>(double angle);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-translate" title="dom-context-2d-translate">translate</a>(double x, double y);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-transform" title="dom-context-2d-transform">transform</a>(double a, double b, double c, double d, double e, double f);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-settransform" title="dom-context-2d-setTransform">setTransform</a>(double a, double b, double c, double d, double e, double f);
// compositing
attribute double <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">globalAlpha</a>; // (default 1.0)
attribute DOMString <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">globalCompositeOperation</a>; // (default source-over)
// colors and styles
attribute any <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-strokestyle" title="dom-context-2d-strokeStyle">strokeStyle</a>; // (default black)
attribute any <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-fillstyle" title="dom-context-2d-fillStyle">fillStyle</a>; // (default black)
<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#canvasgradient">CanvasGradient</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-createlineargradient" title="dom-context-2d-createLinearGradient">createLinearGradient</a>(double x0, double y0, double x1, double y1);
<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#canvasgradient">CanvasGradient</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-createradialgradient" title="dom-context-2d-createRadialGradient">createRadialGradient</a>(double x0, double y0, double r0, double x1, double y1, double r1);
<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#canvaspattern">CanvasPattern</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-createpattern" title="dom-context-2d-createPattern">createPattern</a>(<span>HTMLImageElement</span> image, DOMString repetition);
<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#canvaspattern">CanvasPattern</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-createpattern" title="dom-context-2d-createPattern">createPattern</a>(<span>HTMLCanvasElement</span> image, DOMString repetition);
<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#canvaspattern">CanvasPattern</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-createpattern" title="dom-context-2d-createPattern">createPattern</a>(<span>HTMLVideoElement</span> image, DOMString repetition);
// line caps/joins
attribute double <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-linewidth" title="dom-context-2d-lineWidth">lineWidth</a>; // (default 1)
attribute DOMString <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-linecap" title="dom-context-2d-lineCap">lineCap</a>; // "butt", "round", "square" (default "butt")
attribute DOMString <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-linejoin" title="dom-context-2d-lineJoin">lineJoin</a>; // "round", "bevel", "miter" (default "miter")
attribute double <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-miterlimit" title="dom-context-2d-miterLimit">miterLimit</a>; // (default 10)
// shadows
attribute double <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-shadowoffsetx" title="dom-context-2d-shadowOffsetX">shadowOffsetX</a>; // (default 0)
attribute double <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-shadowoffsety" title="dom-context-2d-shadowOffsetY">shadowOffsetY</a>; // (default 0)
attribute double <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-shadowblur" title="dom-context-2d-shadowBlur">shadowBlur</a>; // (default 0)
attribute DOMString <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-shadowcolor" title="dom-context-2d-shadowColor">shadowColor</a>; // (default transparent black)
// rects
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-clearrect" title="dom-context-2d-clearRect">clearRect</a>(double x, double y, double w, double h);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-fillrect" title="dom-context-2d-fillRect">fillRect</a>(double x, double y, double w, double h);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-strokerect" title="dom-context-2d-strokeRect">strokeRect</a>(double x, double y, double w, double h);
// path API
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-beginpath" title="dom-context-2d-beginPath">beginPath</a>();
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-closepath" title="dom-context-2d-closePath">closePath</a>();
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-moveto" title="dom-context-2d-moveTo">moveTo</a>(double x, double y);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-lineto" title="dom-context-2d-lineTo">lineTo</a>(double x, double y);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-quadraticcurveto" title="dom-context-2d-quadraticCurveTo">quadraticCurveTo</a>(double cpx, double cpy, double x, double y);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-beziercurveto" title="dom-context-2d-bezierCurveTo">bezierCurveTo</a>(double cp1x, double cp1y, double cp2x, double cp2y, double x, double y);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-arcto" title="dom-context-2d-arcTo">arcTo</a>(double x1, double y1, double x2, double y2, double radius);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-rect" title="dom-context-2d-rect">rect</a>(double x, double y, double w, double h);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-arc" title="dom-context-2d-arc">arc</a>(double x, double y, double radius, double startAngle, double endAngle, optional boolean anticlockwise);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-fill" title="dom-context-2d-fill">fill</a>();
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-stroke" title="dom-context-2d-stroke">stroke</a>();
<!--
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawsystemfocusring" title="dom-context-2d-drawSystemFocusRing">drawSystemFocusRing</a>(<span>Element</span> element);
boolean <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawcustomfocusring" title="dom-context-2d-drawCustomFocusRing">drawCustomFocusRing</a>(<span>Element</span> element);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-scrollpathintoview" title="dom-context-2d-scrollPathIntoView">scrollPathIntoView</a>();
-->
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-clip" title="dom-context-2d-clip">clip</a>();
boolean <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-ispointinpath" title="dom-context-2d-isPointInPath">isPointInPath</a>(double x, double y);
// Focus management
boolean <a href="#dom-context-2d-drawfocusring" title="dom-context-2d-drawFocusRing">drawFocusRing</a>(in <span>Element</span> element);
// Caret and selection management
long <a href="#dom-context-2d-caretBlinkRate" title="dom-context-2d-caretBlinkRate">caretBlinkRate</a>();
boolean <a href="#dom-context-2d-setCaretSelectionRect" title="dom-context-2d-setCaretSelectionRect">setCaretSelectionRect</a>(in <span>Element</span> element, in double x, in double y, in double w, in double h);
// text
attribute DOMString <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-font" title="dom-context-2d-font">font</a>; // (default 10px sans-serif)
attribute DOMString <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-textalign" title="dom-context-2d-textAlign">textAlign</a>; // "start", "end", "left", "right", "center" (default: "start")
attribute DOMString <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-textbaseline" title="dom-context-2d-textBaseline">textBaseline</a>; // "top", "hanging", "middle", "alphabetic", "ideographic", "bottom" (default: "alphabetic")
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-filltext" title="dom-context-2d-fillText">fillText</a>(DOMString text, double x, double y, optional double maxWidth);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-stroketext" title="dom-context-2d-strokeText">strokeText</a>(DOMString text, double x, double y, optional double maxWidth); <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#textmetrics">TextMetrics</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-measuretext" title="dom-context-2d-measureText">measureText</a>(DOMString text);
// drawing images
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLImageElement</span> image, double dx, double dy);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLImageElement</span> image, double dx, double dy, double dw, double dh);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLImageElement</span> image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLCanvasElement</span> image, double dx, double dy);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLCanvasElement</span> image, double dx, double dy, double dw, double dh);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLCanvasElement</span> image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLVideoElement</span> image, double dx, double dy);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLVideoElement</span> image, double dx, double dy, double dw, double dh);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawimage" title="dom-context-2d-drawImage">drawImage</a>(<span>HTMLVideoElement</span> image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);
// pixel manipulation
<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#imagedata">ImageData</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-createimagedata" title="dom-context-2d-createImageData">createImageData</a>(double sw, double sh);
<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#imagedata">ImageData</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-createimagedata" title="dom-context-2d-createImageData">createImageData</a>(<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#imagedata">ImageData</a> imagedata);
<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#imagedata">ImageData</a> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-getimagedata" title="dom-context-2d-getImageData">getImageData</a>(double sx, double sy, double sw, double sh);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-putimagedata" title="dom-context-2d-putImageData">putImageData</a>(<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#imagedata">ImageData</a> imagedata, double dx, double dy);
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-putimagedata" title="dom-context-2d-putImageData">putImageData</a>(<a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#imagedata">ImageData</a> imagedata, double dx, double dy, double dirtyX, double dirtyY, double dirtyWidth, double dirtyHeight);
};
interface <dfn id="canvasgradient">CanvasGradient</dfn> {
// opaque object
void <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-canvasgradient-addcolorstop" title="dom-canvasgradient-addColorStop">addColorStop</a>(double offset, DOMString color);
};
interface <dfn id="canvaspattern">CanvasPattern</dfn> {
// opaque object
};
interface <dfn id="textmetrics">TextMetrics</dfn> {
readonly attribute double <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-textmetrics-width" title="dom-textmetrics-width">width</a>;
readonly attribute double <a href="#dom-textmetrics-width" title="dom-textmetrics-width">baseline</a>;
};
interface <dfn id="imagedata">ImageData</dfn> {
readonly attribute unsigned long <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-imagedata-width" title="dom-imagedata-width">width</a>;
readonly attribute unsigned long <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-imagedata-height" title="dom-imagedata-height">height</a>;
readonly attribute <span>Uint8ClampedArray</span> <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-imagedata-data" title="dom-imagedata-data">data</a>;
};</pre>
</section>
<section>
<h2 id="focus-management">Focus management</h2>
<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 class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#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 or is a descendant
of the element with focus. <dl class="domintro"><dt><var title="">shouldDraw</var> = <var title="">context</var> . <code title="dom-context-2d-drawFocusRing"><a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-drawfocusring">drawFocusRing</a></code>(<var title="">element</var>, [ <var title="">canDrawCustom</var> ])</dt>
<dd>
<p>If the given element is focused or a descendant of the element with focus, draws a focus ring around the
current path, following the platform conventions for focus
rings. </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 drawing path is used to form the focus ring provided that
drawing path contains a closed path. The drawing path is used to
form a best fit bounding rectangle in screen coordinates. The
bounding rectangle and drawing path may be used to enhance
accessibility properties
[[WAI-ARIA]]
for the targeted element.</p>
<p>The <dfn id="dom-context-2d-drawfocusring" title="dom-context-2d-drawFocusRing"><code>drawFocusRing(<var title="">element</var>, [<var title="">canDrawCustom</var>])</code></dfn>
method, when invoked, must run the following steps:</p>
<ol><li><p>If the <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 supporting an accessibility API, implementors may use the drawing path to form a best fit rectangle in screen coordinates and apply it to the bounding rectangle of the associated accessible object. </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 class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#shadows" title="shadows">shadow effects</a>, the <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-globalalpha" title="dom-context-2d-globalAlpha">global alpha</a>, or the <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-globalcompositeoperation" title="dom-context-2d-globalCompositeOperation">global composition
operators</a>, but <em>should</em> be subject to the <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#clipping-region" title="clipping region">clipping region</a>.</p>
</li>
<li><p>Return true.</li>
</ol></div>
</section>
<section>
<h2 id="caret-selection">Caret and selection management</h2>
<p>
When a canvas implementation is used to render
interactive content that contains a caret or selection, it is
essential that all users be able to follow the current caret or
selection position.
</p>
<!--
<p class="XXX annotation"><b>Status: </b><i>Ideally setCaretSelectionRect() and caretBlinkRate() should be managed under the covers by canvas methods that draw carets or content selections. If <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=10248">defect 10248</a> and <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=10249">defect 10249</a> are accepted with the provisions for supporting accessibility services we can operate off those methods to complete to address the caret and selection position tracking component of Issue-74. </i></p>
-->
<p>The <code title="dom-context-2d-setCaretSelectionRect"><a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-setCaretSelectionRect">setCaretSelectionRect()</a></code> method should be used
to indicate the location of the last rendered <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#caretpos" title="caret position">caret position</a> or <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#selectionpos" title="selection position">selection position</a> on the canvas, passing it the canvas fallback element
associated with the last drawn of either the caret position or the selection.</p>
<!--
<p>Authors MUST use the <code title="dom-context-2d-setCaretSelectionRect"><a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-setCaretSelectionRect">setCaretSelectionRect()</a></code> method,
to indicate the pixel location of the last rendered of either caret
or selection position on the focused canvas, passing it the element
associated with the last drawn of either the caret position or the
selected text.</p>
-->
<p>
When drawing a blinking caret the author must adhere to the blink rates in systems that support this feature. User agents must provide the system caret blink rate to content authors. Default system caret blink rate settings are roughly once every 500 milliseconds.
</p>
<p>To access the system caret blink rate in canvas use the
<code title="dom-context-2d-caretBlinkRate"><a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-caretBlinkRate">caretBlinkRate()</a></code> method</p>
<p>
<dl class="domintro"><dt><var title="">success</var> = <var title="">context</var> . <code title="dom-context-2d-setCaretSelectionRect"><a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-setCaretSelectionRect">setCaretSelectionRect</a></code>(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</dt>
<dd>
<p>Returns true if the given element is focused or a document descendant of an element with focus. Otherwise, returns false.</p>
<!--
<p>The given coordinates (<var title="">x</var>, <var title="">y</var>) are relative to the outer edge of the caret or selection position where the edge represents the left or right edge in the direction of the user's selection.</p>
<p>The <var title="">w</var> and <var title="">h</var> are supplied to indicate the respective width of the caret and height of the caret or selection point. Authors should compute the height based on the font height of the associated character, in pixels, and the width of the caret or nearest associated selected character.</p>
<p>The top left pixel coordinate of the caret or selection position must be given in the <var title="">x</var> and <var title="">y</var> arguments. When this coordinate is the selection position, the top left pixel coordinate must be positioned equivalent to the top left pixel location of the last character selected. Additionally, the <var title="">w</var> and <var title="">h</var> are supplied to indicate the width and height of the caret or selection point. Authors must compute the height based on the font height of the associated character, in pixels. In the case of a caret, authors must compute the width based on the caret's with in pixels. In the case of a selected character the width must correspond to the width of the last selected character in pixels. </p>
-->
</dd>
<dt><var title="">rate</var> = <var title="">context</var> . <code title="dom-context-2d-caretBlinkRate"><a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#dom-context-2d-caretBlinkRate">caretBlinkRate</a></code>()</dt>
<dd>
<p>Returns the blink rate of the system in milliseconds if supported. Otherwise, returns -1 if it is unsupported by the system.</p>
</dd>
</dl><div class="impl">
<!--
<p>When this last rendered screen position is the selection position, the screen position must be equivalent to the the pixel location of the outer top left or right corner of the last character selected in the direction (left or right) of the selection. A rectangle is used to represent this position as carets may vary in width and at large magnification levels the width of the caret may be important in determining where to magnify.</p>
-->
<p class="note">Screen magnifiers, used by low vision users, use this position to move the magnification point on the screen.</p>
<!--
<p>For user agents that support an accessibility API, these coordinates are converted to screen coordinates within the user agent and used to notify the assistive technology of the change in either the current caret or selection position.</p>
<p>The caret position is typically the last rendered screen position of either the end of the last visible selected character, or the caret position when the associated text has focus or is a descendant of an element that has focus.</p>
<p class="note">Some systems follow a convention whereby caret position does not track the selected text, in which case the last drawn position must be tracked. Furthermore, when <var title="">element</var> is a descendent of an element with focus there must be only one descendent of the element with focus that has either a caret or selection position and the last call to this function must be for the last caret or selection drawn. </p>
-->
<p>The <dfn id="dom-context-2d-setCaretSelectionRect" title="dom-context-2d-setCaretSelectionRect"><code>setCaretSelectionRect(<var title="">element</var>, <var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>)</code></dfn>
method, when invoked, must run the following steps:</p>
<ol>
<li><p>If <var title="">element</var> does not have selected content and is not focused return false and abort these steps.</p></li>
<!-- <li><p>If <var title="">element</var> does have a caret but is not focused then return false and abort these steps </p></li> -->
<li><p>If the element is not a descendant of the element with whose context the method is associated, then return false and abort these step.</p></li>
<li><p>Transform the given point (<var title="">x</var>, <var title="">y</var>), the width <var title="">w</var>, and the height <var title="">h</var> according to the <a class="upstream-link" href="http://dev.w3.org/html5/2dcontext/#transformations" title="dom-context-2d-transformation">current transformation matrix</a>.</p></li>
<li><p>If the user agent supports a platform accessibility API the user agent must use the element, transformed coordinates and transformed bounding box, and provide it through the supported accessibility API implementation.
<!--
The element used to determine the corresponding accessible object for purposes of supporting the accessibility API. This is for the purposes of driving screen magnification.
-->
</li>
<!--
<li><p>If your user agent supports a platform accessibility API the user agent must use the
(transformed) coordinate on the canvas and compute a caret or selection position (or rectangle) in screen coordinates and provide it to an assistive technology through the supported accessibility API implementation for that element. </li>
-->
<li><p>Return true.</li>
</ol></div>
<p>If the user resizes or moves the user agent window the user agent report must reflect the revised (<var title="">x</var>, <var title="">y</var>, <var title="">w</var>, <var title="">h</var>) position (or rectangle) in the accessibility API mapping. </p>
<div class="impl">
<p class="note">High blink rates may cause epileptic seizures in some users.</p>
<p>The <dfn id="dom-context-2d-blinkRate" title="dom-context-2d-blinkRate"><code>caretBlinkRate()</code></dfn>
method, when invoked, must run the following steps:</p>
<ol>
<li><p>If the operating system supports a caret blink rate setting the user agent must return a long value in milliseconds.</p></li>
<li><p>If the operating system does not support a caret blink rate setting the user agent must return a long value less than zero.</p></li>
</ol>
<p>
When the caret blink rate value returned:
</p>
<ul>
<li><p>For blink rates greater than zero the author, when drawing a blinking caret, must reflect the blink rate returned by this method.</p></li>
<li><p>For a blink rate less than zero the author, when drawing a blinking caret, must determine the blink rate.</p></li>
<li><p>For a blink rate of zero the author should visibly render the caret.</p></li>
</ul>
</div>
<p>
The <dfn id="caretpos">caret position</dfn> is the rectangular left edge of the caret position within an element having focus. The <dfn id="selectionpos">selection position</dfn> is the rectangular left or right edge of the highlighted position that moves in response to a users selection of content such as when dragging a pointing device during a content selection operation. The right edge is used when moving the selection position to the right and the left edge is used when moving the position to the left.
</p>
</section>
<section>
<h2 id="Text">Extension to the TextMetrics interface</h2>
<p>This specification extends the
<code><a href="#textmetrics">TextMetrics</a></code>
interface used for the objects
returned from <code title="dom-context-2d-measureText"><a href="#dom-context-2d-measuretext">measureText()</a></code>.
This specification adds
a <dfn id="dom-textmetrics-baseline" title="dom-textmetrics-baseline"><code>baseline</code></dfn>
attribute to the
<code><a href="#textmetrics">TextMetrics</a></code>
interface, for the purpose of returning the vertical offset of a text anchor point.</p>
<dl class=domintro>
<dt><var title="">metrics</var> .
<code title="dom-textmetrics-baseline"><a href="#dom-textmetrics-baseline">baseline</a></code></dt>
<dd>
<p>Returns the vertical offset of the <var title="">anchor point</var> for the text that was passed to the
<code title="dom-context-2d-measureText"><a href="#dom-context-2d-measuretext">measureText()</a></code>
method.</p>
</dd>
</dl>
<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 <span title="space
character">space characters</span> in <var title="">text</var> with
U+0020 SPACE characters, and then must form a hypothetical
infinitely wide CSS line box containing a single inline box
containing the text <var title="">text</var>, with all the
properties at their initial values except the 'font' property of the
inline element set to the current font of the context, as given by
the <code title="dom-context-2d-font"><a href="#dom-context-2d-font">font</a></code> attribute, and
must then return a new <code><a href="#textmetrics">TextMetrics</a></code> object with its
<code title="dom-textmetrics-width"><a href="#dom-textmetrics-width">width</a></code> attribute set to
the width of that inline box, in CSS pixels and its
<code title="dom-textmetrics-baseline"><a href="#dom-textmetrics-baseline">baseline</a></code> attribute
set to the <var title="">anchor point</var>'s vertical position as determined by the current
<code title="dom-context-2d-textBaseline"><a href="#dom-context-2d-textbaseline">textBaseline</a></code> value,
in CSS pixels. [[!CSS21]]</p>
</section>
Received on Wednesday, 14 December 2011 07:32:58 UTC