8000 csswg-drafts/css-font-loading-3/Overview.bs at 98db39062266f185493788d6e93d24fa498ad7ef · w3c/csswg-drafts · GitHub
Skip to content

Overview.bs

Latest commit

 

History

History
1183 lines (958 loc) · 52.7 KB

Overview.bs

File metadata and controls

1183 lines (958 loc) · 52.7 KB
<li>
<a>Find the matching font faces</a> from <var>font face set</var>
using the {{FontFaceSet/check()/font}} and {{FontFaceSet/check()/text}} arguments passed to the function,
and including system fonts,
and let <var>font face list</var> be the returned list of font faces,
and <var>found faces</var> be the returned <var>found faces</var> flag.
If a syntax error was returned,
throw a SyntaxError exception
and terminate these steps.
<li>
If <var>found faces</var> is false,
throw C220 an XXX error
and abort this algorithm.
<li>
If <var>font face list</var> is empty,
or all fonts in the <var>font face list</var> either have a {{FontFace/status}} attribute of "loaded" or are system fonts,
return <code>true</code>.
Otherwise, return <code>false</code>.
</ol>
<!--
████████ ████████ ███ ████████ ██ ██
██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ████
████████ ██████ ██ ██ ██ ██ ██
██ ██ ██ █████████ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██
██ ██ ████████ ██ ██ ████████ ██
-->
<h3 id='font-face-set-ready'>
The <code>ready</code> attribute</h3>
Because the number of fonts loaded depends on the how many fonts are used for a given piece of text,
in some cases whether fonts need to be loaded or not may not be known.
The {{FontFaceSet/ready}} attribute contains a {{Promise}} which is resolved when the document is done loading fonts,
which provides a way for authors to avoid having to keep track of which fonts have or haven't been loaded
before examining content which may be affected by loading fonts.
Note: Authors should note that a given <var>ready promise</var> is only fulfilled once,
but further fonts may be loaded after it fulfills.
This is similar to listening for a {{loadingdone}} event to fire,
but the callbacks passed to the {{FontFaceSet/ready}} promise will <strong>always</strong> get called,
even when no font loads occur because the fonts in question are already loaded.
It's a simple, easy way to synchronize code to font loads
without the need to keep track of what fonts are needed and precisely when they load.
Note: Note that the user agent may need to iterate over multiple font loads before the <var>ready promise</var> is fulfilled.
This can occur with font fallback situations,
where one font in the fontlist is loaded
but doesn't contain a particular glyph
and other fonts in the fontlist need to be loaded.
The <var>ready promise</var> is only fulfilled after layout operations complete
and no additional font loads are necessary.
Note: Note that the Promise returned by this {{FontFaceSet/ready}} attribute is only ever fulfilled,
never rejected,
unlike the Promise returned by the {{FontFace}} {{FontFace/load()}} method.
<h3 id='font-face-set-css'>
Interaction with CSS Font Loading and Matching</h3>
When the font matching algorithm in [[CSS-FONTS-3]] is run automatically by the user-agent,
the set of font faces it matches over must be precisely the set of fonts in the <a>font source</a> for the document,
plus any local font faces.
When a user-agent needs to load a font face,
it must do so by calling the {{FontFace/load()}} method
of the corresponding {{FontFace}} object.
(This means it must run the same algorithm,
not literally call the value currently stored in the <code>load</code> property of the object.)
<div class="example" highlight=js>
Fonts are available when they are added to a {{FontFaceSet}}.
Adding a new ''@font-face'' rule to a stylesheet
also adds a new {{FontFace}} to the {{FontFaceSet}} of the {{Document}} object.
Adding a new ''@font-face'' rule:
<pre>
document.styleSheets[0].insertRule(
"@font-face { font-family: newfont; src: url(newfont.woff); }", 0);
document.body.style.fontFamily = "newfont, serif";
</pre>
Constructing a new {{FontFace}} object and adding it to <code>document.fonts</code>:
<pre>
var f = new FontFace("newfont", "url(newfont.woff)");
document.fonts.add(f);
document.body.style.fontFamily = "newfont, serif";
</pre>
In both cases, the loading of the font resource “newfont.woff” will be initiated by the layout engine,
just as other ''@font-face'' rule fonts are loaded.
Omitting the addition to <code>document.fonts</code> means the font would never be loaded
and text would be displayed in the default serif font:
<pre>
var f = new FontFace("newfont", "url(newtest.woff)", {});
/* new {{FontFace}} not added to {{FontFaceSet}},
so the 'font-family' property can't see it,
and serif will be used instead */
document.body.style.fontFamily = "newfont, serif";
</pre>
To explicitly preload a font before using it,
authors can defer the addition of a new {{FontFace}} to a {{FontFaceSet}} until the load has completed:
<pre>
var f = new FontFace("newfont", "url(newfont.woff)", {});
f.load().then(function (loadedFace) {
document.fonts.add(loadedFace);
document.body.style.fontFamily = "newfont, serif";
});
</pre>
In this case, the font resource “newfont.woff” is first downloaded.
Once the download completes,
the font is added to the document's {{FontFaceSet}},
the body font is changed,
and the layout engine uses the new font resource.
</div>
<!--
████████ ███████ ██ ██ ████████ ████████ ███ ██████ ████████ ██████ ███████ ██ ██ ████████ ██████ ████████
██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██████ ██ ██ ██ ██ ██ ██ ██████ ██ ██ ██ ██████ ██████ ██ ██ ██ ██ ████████ ██ ██████
██ ██ ██ ██ ████ ██ ██ █████████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██
██ ███████ ██ ██ ██ ██ ██ ██ ██████ ████████ ██████ ███████ ███████ ██ ██ ██████ ████████
-->
<h2 id='font-face-source'>
The <code>FontFaceSource</code> interface</h2>
<pre class='idl'>
[Exposed=(Window,Worker),
NoInterfaceObject]
interface FontFaceSource {
readonly attribute FontFaceSet fonts;
};
View remainder of file in raw view