Font Metrics API Level 1

A Collection of Interesting Ideas,

This version:
https://drafts.css-houdini.org/font-metrics-api-1/
Feedback:
public-houdini@w3.org with subject line “[font-metrics-api] … message topic …” (archives)
Issue Tracking:
GitHub
Editors:

Abstract

Status of this document

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

interface FontMetrics {
  readonly attribute double width;
  readonly attribute sequence<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 sequence<Baseline> baselines;
  readonly attribute sequence<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

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

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.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-TYPED-OM-1]
Shane Stephens. CSS Typed OM Level 1. URL: https://drafts.css-houdini.org/css-typed-om-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL: https://heycam.github.io/webidl/

IDL Index

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

interface FontMetrics {
  readonly attribute double width;
  readonly attribute sequence<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 sequence<Baseline> baselines;
  readonly attribute sequence<Font> fonts;
};

interface Baseline {
  readonly attribute DOMString name;
  readonly attribute double value;
};

interface Font {
  readonly attribute DOMString name;
  readonly attribute unsigned long glyphsRendered;
};