HTML Canvas 2D Context Extensions

Table of Contents

• 1. Introduction
• 2. Typographic conventions
• 3. Conformance
• 4. The CanvasRenderingContext2D interface
• 5. Focus management
• 6. Caret and selection management
• 7. Extension to the TextMetrics interface
• A. References
  • A.1 Normative references
  • A.2 Informative references

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.

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.

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.

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]