W3C

HTML Canvas 2D Context Extensions

W3C Editor's Draft 16 December 2011

(acting) Editor:
Steve Faulkner, The Paciello Group sfaulkner@paciellogroup.com

Abstract

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.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document is a proposal that is being made available for public review in order to solicit feedback, particularly from implementors, with a goal of potential cross-browser implementation and standardization.

This document is being made available by an editor within the HTML Working Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-html-comments@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Table of Contents

1. Introduction

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.

2. Typographic conventions

A hyperlink reference to a definition in the HTML Canvas 2D Context specification looks like this (hover over the link and note the style change).

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 following any links to definitions in the HTML Canvas 2D Context specification.

Content that is in an IDL for the HTML Canvas 2D Context specification but that the IDL in this HTML Canvas 2D Context Extensions specification removes is marked up like this.

Content that is not in an IDL for the HTML Canvas 2D Context specification but that the IDL for this HTML Canvas 2D Context Extensions specification adds is marked up like this.

3. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

Interfaces are defined in terms of Web IDL [WEBIDL].

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.

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].

4. The CanvasRenderingContext2D interface

This specification overrides and extends the 2d context type, whose API is implemented using the CanvasRenderingContext2D interface.

Conforming user agents MUST implement the CanvasRenderingContext2D interface as specified in the following IDL definition.

interface CanvasRenderingContext2D {

  // back-reference to the canvas
  readonly attribute HTMLCanvasElement canvas;

  // state
  void save(); // push state on state stack
  void restore(); // pop state stack and restore state
  // transformations (default transform is the identity matrix)
  void scale(double x, double y);
  void rotate(double angle);
  void translate(double x, double y);
  void transform(double a, double b, double c, double d, double e, double f);
  void setTransform(double a, double b, double c, double d, double e, double f);
  // compositing
           attribute double globalAlpha; // (default 1.0)
           attribute DOMString globalCompositeOperation; // (default source-over)
  // colors and styles
           attribute any strokeStyle; // (default black)
           attribute any fillStyle; // (default black)
  CanvasGradient createLinearGradient(double x0, double y0, double x1, double y1);
  CanvasGradient createRadialGradient(double x0, double y0, double r0, double x1, double y1, double r1);
  CanvasPattern createPattern(HTMLImageElement image, DOMString repetition);
  CanvasPattern createPattern(HTMLCanvasElement image, DOMString repetition);
  CanvasPattern createPattern(HTMLVideoElement image, DOMString repetition);

  // line caps/joins
           attribute double lineWidth; // (default 1)
           attribute DOMString lineCap; // "butt", "round", "square" (default "butt")
           attribute DOMString lineJoin; // "round", "bevel", "miter" (default "miter")
           attribute double miterLimit; // (default 10)

  // shadows
           attribute double shadowOffsetX; // (default 0)
           attribute double shadowOffsetY; // (default 0)
           attribute double shadowBlur; // (default 0)
           attribute DOMString shadowColor; // (default transparent black)

  // rects
  void clearRect(double x, double y, double w, double h);
  void fillRect(double x, double y, double w, double h);
  void strokeRect(double x, double y, double w, double h);

  // path API
  void beginPath();
  void closePath();
  void moveTo(double x, double y);
  void lineTo(double x, double y);
  void quadraticCurveTo(double cpx, double cpy, double x, double y);
  void bezierCurveTo(double cp1x, double cp1y, double cp2x, double cp2y, double x, double y);
  void arcTo(double x1, double y1, double x2, double y2, double radius); 
  void rect(double x, double y, double w, double h);
  void arc(double x, double y, double radius, double startAngle, double endAngle, optional boolean anticlockwise); 
  void fill();
  void stroke();
  void drawSystemFocusRing(Element element);
  boolean drawCustomFocusRing(Element element);
  void scrollPathIntoView();
  void clip();
  boolean isPointInPath(double x, double y);


                                                                                                         
  // Focus management                                                                                    
  boolean drawFocusRing(in Element element, in optional boolean canDrawCustom);                          
                                                                                                         
  // Caret and selection management                                                                      
  long caretBlinkRate();                                                                                 
  boolean setCaretSelectionRect(in Element element, in double x, in double y, in double w, in double h); 
                                                                                                         


  // text
           attribute DOMString font; // (default 10px sans-serif)
           attribute DOMString textAlign; // "start", "end", "left", "right", "center" (default: "start")
           attribute DOMString textBaseline; // "top", "hanging", "middle", "alphabetic", "ideographic", "bottom" (default: "alphabetic")
  void fillText(DOMString text, double x, double y, optional double maxWidth);
  void strokeText(DOMString text, double x, double y, optional double maxWidth);  TextMetrics measureText(DOMString text);

  // drawing images
  void drawImage(HTMLImageElement image, double dx, double dy);
  void drawImage(HTMLImageElement image, double dx, double dy, double dw, double dh);
  void drawImage(HTMLImageElement image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);
  void drawImage(HTMLCanvasElement image, double dx, double dy);
  void drawImage(HTMLCanvasElement image, double dx, double dy, double dw, double dh);
  void drawImage(HTMLCanvasElement image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);
  void drawImage(HTMLVideoElement image, double dx, double dy);
  void drawImage(HTMLVideoElement image, double dx, double dy, double dw, double dh);
  void drawImage(HTMLVideoElement image, double sx, double sy, double sw, double sh, double dx, double dy, double dw, double dh);

  // pixel manipulation
  ImageData createImageData(double sw, double sh);
  ImageData createImageData(ImageData imagedata);
  ImageData getImageData(double sx, double sy, double sw, double sh);
  void putImageData(ImageData imagedata, double dx, double dy);
  void putImageData(ImageData imagedata, double dx, double dy, double dirtyX, double dirtyY, double dirtyWidth, double dirtyHeight);
};

interface CanvasGradient {
  // opaque object
  void addColorStop(double offset, DOMString color);
};

interface CanvasPattern {
  // opaque object
};

interface TextMetrics {
  readonly attribute double width;
  readonly attribute double baseline;  

};

interface ImageData {
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;
  readonly attribute Uint8ClampedArray data;
};

5. Focus management

When a canvas is interactive, authors SHOULD include focusable elements in the element's fallback content corresponding to each focusable part of the canvas.

To indicate which focusable part of the canvas is currently focused, authors SHOULD use the drawFocusRing() 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.

shouldDraw = context . drawFocusRing(element, [ canDrawCustom ])

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.

If the canDrawCustom 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.)

Returns true if the given element is focused, the canDrawCustom argument is true, and the user has not configured his system to draw focus rings in a particular manner. Otherwise, returns false.

When the method returns true, the author is expected to manually draw a focus ring.

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.

The drawFocusRing(element, [canDrawCustom]) method, when invoked, MUST run the following steps:

  1. If the element 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.

  2. 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.

  3. If the user has requested the use of particular focus rings (e.g. high-contrast focus rings), or if the canDrawCustom 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.

    The focus ring SHOULD not be subject to the shadow effects, the global alpha, or the global composition operators, but SHOULD be subject to the clipping region.

  4. Return true.

6. Caret and selection management

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.

The setCaretSelectionRect() method SHOULD be used to indicate the location of the last rendered caret position or selection position on the canvas, passing it the canvas fallback element associated with the last drawn of either the caret position or the selection.

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.

To access the system caret blink rate in canvas use the caretBlinkRate() method

success = context . setCaretSelectionRect(element, x, y, w, h)

Returns true if the given element is focused or a document descendant of an element with focus. Otherwise, returns false.

rate = context . caretBlinkRate()

Returns the blink rate of the system in milliseconds if supported. Otherwise, returns -1 if it is unsupported by the system.

Screen magnifiers, used by low vision users, use this position to move the magnification point on the screen.

The setCaretSelectionRect(element, x, y, w, h) method, when invoked, MUST run the following steps:

  1. If element does not have selected content and is not focused return false and abort these steps.

  2. If the element is not a descendant of the element with whose context the method is associated, then return false and abort these step.

  3. Transform the given point (x, y), the width w, and the height h according to the current transformation matrix.

  4. 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.

  5. Return true.

If the user resizes or moves the user agent window the user agent report MUST reflect the revised (x, y, w, h) position (or rectangle) in the accessibility API mapping.

High blink rates may cause epileptic seizures in some users.

The caretBlinkRate() method, when invoked, MUST run the following steps:

  1. If the operating system supports a caret blink rate setting the user agent MUST return a long value in milliseconds.

  2. If the operating system does not support a caret blink rate setting the user agent MUST return a long value less than zero.

When the caret blink rate value returned:

The caret position is the rectangular left edge of the caret position within an element having focus. The selection position 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.

7. Extension to the TextMetrics interface

This specification extends the TextMetrics interface used for the objects returned from measureText(); this specification adds a baseline attribute to the TextMetrics interface, for the purpose of returning the vertical offset of a text anchor point.

metrics . baseline

Returns the vertical offset of the anchor point for the text that was passed to the measureText() method.

The measureText() method takes one argument, text. When the method is invoked, the user agent MUST replace all the space characters in text with U+0020 SPACE characters, and then MUST form a hypothetical infinitely wide CSS line box containing a single inline box containing the text text, 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 font attribute, and MUST then return a new TextMetrics object with its width attribute set to the width of that inline box, in CSS pixels and its baseline attribute set to the anchor point's vertical position as determined by the current textBaseline value, in CSS pixels. [CSS21]

A. References

A.1 Normative references

[CANVAS-2D]
Ian Hickson. HTML Canvas 2D Context. URL:http://dev.w3.org/html5/2dcontext/Overview.html
[CSS21]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification.. W3C Recommendation. URL: http://www.w3.org/TR/CSS21/
[HTML5]
Ian Hickson; David Hyatt. HTML5. URL: http://dev.w3.org/html5/spec/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219

A.2 Informative references

[WAI-ARIA]
Lisa Pappas; et al. Accessible Rich Internet Applications (WAI-ARIA) 1.0. 24 February 2009. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2009/WD-wai-aria-20090224