Skip to content

Commit 9554fe7

Browse files
eaeneteaenet
committed
[font-metrics-api] Initial FontMetrics draft
1 parent 3e32d4a commit 9554fe7

File tree

1 file changed

+199
-2
lines changed

1 file changed

+199
-2
lines changed

‎font-metrics-api/Overview.bs

+199-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,204 @@ ED: https://drafts.css-houdini.org/font-metrics-api-1/
66
Shortname: font-metrics-api
77
Level: 1
88
Abstract:
9-
Editor: Stephen Zilles, szilles@adobe.com
9+
Editor: Emil A Eklund, eae@google.com
1010
Editor: Alan Stearns, stearns@adobe.com
11-
Editor: Chris Lilley, chris@w3.org
1211
</pre>
12+
13+
<pre class=link-defaults>
14+
spec:dom; type:interface; text:Document
15+
spec:dom; type:interface; text:Element;
16+
spec:cssom-1; type:interface; text:CSS;
17+
</pre>
18+
19+
Introduction {#intro}
20+
=====================
21+
22+
The API exposed by this specification is designed to provide basic font metrics
23+
for both in-document and out-of-document content.
24+
25+
Note: In a future version of this spec support may be added for exposing
26+
information about individual runs of text, including information about
27+
directionality, script, and character properties.
28+
29+
Measure API {#measure-api}
30+
============================================
31+
32+
<pre class='idl'>
33+
partial interface Document {
34+
FontMetrics measureElement(Element element);
35+
FontMetrics measureText(DOMString text, StylePropertyMapReadOnly styleMap);
36+
};
37+
</pre>
38+
39+
Two methods are provided for measuring text, one for in-document measurements
40+
and another for out-of-document measurements. Both return a {{FontMetrics}}
41+
object.
42+
43+
{{Document/measureElement()}} takes an {{Element}} and returns a {{FontMetrics}}
44+
object. If the {{Element}} is not in the document or isn't rendered an empty
45+
{{FontMetrics}} object will be returned.
46+
47+
{{Document/measureText()}} takes a {{DOMString}} and a
48+
{{StylePropertyMapReadOnly}}, returning a {{FontMetrics}} object. Unless a font
49+
is specified as a part of the styleMap the user agents default will be used.
50+
51+
Note: The only styles that apply to the {{Document/measureText()}} method are
52+
those that are passed in as a part of the styleMap. Document styles do not apply.
53+
54+
{{FontMetrics}} object {#fontmetrics-definition}
55+
----------------------------
56+
57+
<pre class='idl'>
58+
interface FontMetrics {
59+
readonly attribute double width;
60+
readonly attribute sequence&lt;double> advances;
61+
62+
readonly attribute double boundingBoxLeft;
63+
readonly attribute double boundingBoxRight;
64+
65+
readonly attribute double height;
66+
readonly attribute double emHeightAscent;
67+
readonly attribute double emHeightDescent;
68+
readonly attribute double boundingBoxAscent;
69+
readonly attribute double boundingBoxDescent;
70+
readonly attribute double fontBoundingBoxAscent;
71+
readonly attribute double fontBoundingBoxDescent;
72+
73+
readonly attribute Baseline dominantBaseline;
74+
readonly attribute sequence&lt;Baseline> baselines;
75+
readonly attribute sequence&lt;Font> fonts;
76+
};
77+
</pre>
78+
79+
The {{FontMetrics}} object has the following attributes:
80+
81+
{{FontMetrics/width}}
82+
The advance width of the line box, in CSS pixels.
83+
84+
{{FontMetrics/advances}}
85+
List of advances for each codepoint in the given text relative to the preceding
86+
codepoint, in CSS pixels. Where a glyph is composed of a sequence of codepoints
87+
the advance for the all but the first codepoint in the sequence will be zero.
88+
89+
{{FontMetrics/boundingBoxLeft}}
90+
The distance parallel to the {{FontMetrics/dominantBaseline}} from the alignment
91+
point given by the text-align property to the left side of the bounding
92+
rectangle of the given text, in CSS pixels; positive numbers indicating a
93+
distance going left from the given alignment point.
94+
95+
Note: The sum of this value and {{FontMetrics/boundingBoxRight}} can be wider
96+
than the {{FontMetrics/width}}, in particular with slanted fonts where
97+
characters overhang their advance width.
98+
99+
{{FontMetrics/boundingBoxRight}}
100+
The distance parallel to the {{FontMetrics/dominantBaseline}} from the alignment
101+
point given by the text-align property to the right side of the bounding
102+
rectangle of the given text, in CSS pixels. Positive numbers indicating a
103+
distance going right from the given alignment point.
104+
105+
{{FontMetrics/height}}
106+
The distance between the highest top and the lowest bottom of the em squares in
107+
the line box, in CSS pixels.
108+
109+
{{FontMetrics/emHeightAscent}}
110+
The distance from the {{FontMetrics/dominantBaseline}} to the highest top of the
111+
em squares in the line box, in CSS pixels.
112+
Positive numbers indicating that the {{FontMetrics/dominantBaseline}} is below
113+
the top of that em square (so this value will usually be positive).
114+
Zero if the {{FontMetrics/dominantBaseline}} is the top of that em square.
115+
Half the font size if the {{FontMetrics/dominantBaseline}} is the middle of that
116+
em square.
117+
118+
{{FontMetrics/emHeightDescent}}
119+
The distance from the {{FontMetrics/dominantBaseline}} to the lowest bottom of
120+
the em squares in the line box, in CSS pixels.
121+
Positive numbers indicating that the {{FontMetrics/dominantBaseline}} is below
122+
the bottom of that em square (so this value will usually be negative).
123+
Zero if the {{FontMetrics/dominantBaseline}} is the bottom of that em square.
124+
125+
{{FontMetrics/boundingBoxAscent}}
126+
The distance from the {{FontMetrics/dominantBaseline}} to the top of the
127+
bounding rectangle of the given text, in CSS pixels; positive numbers indicating
128+
a distance going up from the {{FontMetrics/dominantBaseline}}.
129+
130+
Note: This number can vary greatly based on the input text, even if the first
131+
font specified covers all the characters in the input.
132+
133+
{{FontMetrics/boundingBoxDescent}}
134+
The distance from the {{FontMetrics/dominantBaseline}} to the bottom of the
135+
bounding rectangle of the given text, in CSS pixels; positive numbers indicating
136+
a distance going down from the {{FontMetrics/dominantBaseline}}.
137+
138+
{{FontMetrics/fontBoundingBoxAscent}}
139+
The distance from the {{FontMetrics/dominantBaseline}} to the top of the highest
140+
bounding rectangle of all the fonts used to render the text, in CSS pixels;
141+
positive numbers indicating a distance going up from the
142+
{{FontMetrics/dominantBaseline}}.
143+
144+
Note: This value and {{FontMetrics/fontBoundingBoxDescent}} are useful when
145+
metrics independent of the actual text being measured are desired as the values
146+
will be consistent regardless of the text as long as the same fonts are being
147+
used.
148+
The {{FontMetrics/boundingBoxAscent}} attribute (and its corresponding attribute
149+
for the descent) are useful when metrics specific to the given text are desired.
150+
151+
{{FontMetrics/fontBoundingBoxDescent}}
152+
The distance from the {{FontMetrics/dominantBaseline}} to the bottom of the
153+
lowest bounding rectangle of all the fonts used to render the text, in
154+
CSS pixels; positive numbers indicating a distance going down from the
155+
{{FontMetrics/dominantBaseline}}.
156+
157+
{{FontMetrics/dominantBaseline}}
158+
Reference to the dominant {{Baseline}} for the given text in the list of
159+
{{FontMetrics/baselines}}.
160+
161+
{{FontMetrics/baselines}}
162+
List of all {{Baseline}}s for the given text.
163+
164+
165+
{{Baseline}} object {#baseline-definition}
166+
----------------------------
167+
168+
<pre class='idl'>
169+
interface Baseline {
170+
readonly attribute DOMString name;
171+
readonly attribute double value;
172+
};
173+
</pre>
174+
175+
Each {{Baseline}} object represents a baseline of the measured text and has the
176+
following attributes:
177+
178+
{{Baseline/name}}
179+
Name of the baseline in question.
180+
181+
{{Baseline/value}}
182+
Distance from the {{FontMetrics/dominantBaseline}}, in CSS pixels.
183+
Positive numbers indicating a distance going down from the
184+
{{FontMetrics/dominantBaseline}}.
185+
186+
187+
{{Font}} object {#font-definition}
188+
----------------------------
189+
190+
<pre class='idl'>
191+
interface Font {
192+
readonly attribute DOMString name;
193+
readonly attribute unsigned long glyphsRendered;
194+
};
195+
</pre>
196+
197+
Each {{Font}} object represents a font that was used for at least one glyph in
198+
the measured text. It contains the following fields:
199+
200+
{{Font/name}}
201+
Font family name.
202+
203+
{{Font/glyphsRendered}}
204+
Number of glyphs used from the specific font. If multiple fonts are required to
205+
render the specified text this attribute will indicate how many glyphs where
206+
used from each font.
207+
208+
Note: Indicates the number of glyphs which may be lower than the number of
209+
codepoints.

0 commit comments

Comments
 (0)