Font Metrics API Level 1

1. Introduction

The API exposed by this specification is designed to provide basic font metrics for both in-document and out-of-document content.

Note: In a future version of this spec support may be added for exposing information about individual runs of text, including information about directionality, script, and character properties.

2. Measure API

partial interface Document {
    FontMetrics measureElement(Element element);
    FontMetrics measureText(DOMString text, StylePropertyMapReadOnly styleMap);
};

Two methods are provided for measuring text, one for in-document measurements and another for out-of-document measurements. Both return a FontMetrics object.

measureElement() takes an Element and returns a FontMetrics object. If the Element is not in the document or isn’t rendered an empty FontMetrics object will be returned.

measureText() takes a DOMString and a StylePropertyMapReadOnly, returning a FontMetrics object. Unless a font is specified as a part of the styleMap the user agents default will be used.

Note: The only styles that apply to the measureText() method are those that are passed in as a part of the styleMap. Document styles do not apply.

2.1. FontMetrics object

[Exposed=Window]
interface FontMetrics {
  readonly attribute double width;
  readonly attribute FrozenArray<double> advances;
  readonly attribute double boundingBoxLeft;
  readonly attribute double boundingBoxRight;
  readonly attribute double height;
  readonly attribute double emHeightAscent;
  readonly attribute double emHeightDescent;
  readonly attribute double boundingBoxAscent;
  readonly attribute double boundingBoxDescent;
  readonly attribute double fontBoundingBoxAscent;
  readonly attribute double fontBoundingBoxDescent;
  readonly attribute Baseline dominantBaseline;
  readonly attribute FrozenArray<Baseline> baselines;
  readonly attribute FrozenArray<Font> fonts;
};

The FontMetrics object has the following attributes:

width The advance width of the line box, in CSS pixels.

advances List of advances for each codepoint in the given text relative to the preceding codepoint, in CSS pixels. Where a glyph is composed of a sequence of codepoints the advance for the all but the first codepoint in the sequence will be zero.

boundingBoxLeft The distance parallel to the dominantBaseline from the alignment point given by the text-align property to the left side of the bounding rectangle of the given text, in CSS pixels; positive numbers indicating a distance going left from the given alignment point.

Note: The sum of this value and boundingBoxRight can be wider than the width, in particular with slanted fonts where characters overhang their advance width.

boundingBoxRight The distance parallel to the dominantBaseline from the alignment point given by the text-align property to the right side of the bounding rectangle of the given text, in CSS pixels. Positive numbers indicating a distance going right from the given alignment point.

height The distance between the highest top and the lowest bottom of the em squares in the line box, in CSS pixels.

emHeightAscent The distance from the dominantBaseline to the highest top of the em squares in the line box, in CSS pixels. Positive numbers indicating that the dominantBaseline is below the top of that em square (so this value will usually be positive). Zero if the dominantBaseline is the top of that em square. Half the font size if the dominantBaseline is the middle of that em square.

emHeightDescent The distance from the dominantBaseline to the lowest bottom of the em squares in the line box, in CSS pixels. Positive numbers indicating that the dominantBaseline is below the bottom of that em square (so this value will usually be negative). Zero if the dominantBaseline is the bottom of that em square.

boundingBoxAscent The distance from the dominantBaseline to the top of the bounding rectangle of the given text, in CSS pixels; positive numbers indicating a distance going up from the dominantBaseline.

Note: This number can vary greatly based on the input text, even if the first font specified covers all the characters in the input.

boundingBoxDescent The distance from the dominantBaseline to the bottom of the bounding rectangle of the given text, in CSS pixels; positive numbers indicating a distance going down from the dominantBaseline.

fontBoundingBoxAscent The distance from the dominantBaseline to the top of the highest bounding rectangle of all the fonts used to render the text, in CSS pixels; positive numbers indicating a distance going up from the dominantBaseline.

Note: This value and fontBoundingBoxDescent are useful when metrics independent of the actual text being measured are desired as the values will be consistent regardless of the text as long as the same fonts are being used. The boundingBoxAscent attribute (and its corresponding attribute for the descent) are useful when metrics specific to the given text are desired.

fontBoundingBoxDescent The distance from the dominantBaseline to the bottom of the lowest bounding rectangle of all the fonts used to render the text, in CSS pixels; positive numbers indicating a distance going down from the dominantBaseline.

dominantBaseline Reference to the dominant Baseline for the given text in the list of baselines.

baselines List of all Baselines for the given text.

2.2. Baseline object

[Exposed=Window]
interface Baseline {
  readonly attribute DOMString name;
  readonly attribute double value;
};

Each Baseline object represents a baseline of the measured text and has the following attributes:

name Name of the baseline in question.

value Distance from the dominantBaseline, in CSS pixels. Positive numbers indicating a distance going down from the dominantBaseline.

2.3. Font object

[Exposed=Window]
interface Font {
  readonly attribute DOMString name;
  readonly attribute unsigned long glyphsRendered;
};

Each Font object represents a font that was used for at least one glyph in the measured text. It contains the following fields:

name Font family name.

glyphsRendered Number of glyphs used from the specific font. If multiple fonts are required to render the specified text this attribute will indicate how many glyphs where used from each font.

Note: Indicates the number of glyphs which may be lower than the number of codepoints.