8000 csswg-drafts/css-font-loading/Overview.html at 01da8b2efa7ccb3aee5a24758d85e9e07932c072 · w3c/csswg-drafts · GitHub
Skip to content

Overview.html

Latest commit

 

History

History
1237 lines (1001 loc) · 113 KB

Overview.html

File metadata and controls

1237 lines (1001 loc) · 113 KB
<!DOCTYPE html><html lang=en><head>
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
<title>CSS Font Loading Module Level 3</title>
<link href=../default.css rel=stylesheet type=text/css>
<link href=../csslogo.ico rel="shortcut icon" type=image/x-icon>
<style>
body {
background: url("https://www.w3.org/StyleSheets/TR/logo-ED") top left no-repeat white;
background-attachment: fixed;
color: black;
font-family: sans-serif;
margin: 0 auto;
max-width: 50em;
padding: 2em 1em 2em 70px;
}
:link { color: #00C; background: transparent }
:visited { color: #609; background: transparent }
a[href]:active { color: #C00; background: transparent }
a[href]:hover { background: #ffa }
a[href] img { border-style: none }
h1, h2, h3, h4, h5, h6 { text-align: left }
8096 h1, h2, h3 { color: #005A9C; }
h1 { font: 170% sans-serif }
h2 { font: 140% sans-serif }
h3 { font: 120% sans-serif }
h4 { font: bold 100% sans-serif }
h5 { font: italic 100% sans-serif }
h6 { font: small-caps 100% sans-serif }
.hide { display: none }
div.head { margin-bottom: 1em }
div.head h1 { margin-top: 2em; clear: both }
div.head table { margin-left: 2em; margin-top: 2em }
p.copyright { font-size: small }
p.copyright small { font-size: small }
pre { margin-left: 2em }
dt { font-weight: bold }
ul.toc, ol.toc {
list-style: none;
}
</style>
</head>
<body class=h-entry>
<div class=head>
<p data-fill-with=logo><a class=logo href=http://www.w3.org/>
<img alt=W3C height=48 src=https://www.w3.org/Icons/w3c_home width=72>
</a>
</p>
<h1 class="p-name no-ref" id=title>CSS Font Loading Module Level 3</h1>
<h2 class="no-num no-toc no-ref heading settled" id=subtitle><span class=content>Editor’s Draft,
<span class=dt-updated><span class=value-title title=20140929>29 September 2014</span></span></span></h2>
<div data-fill-with=spec-metadata><dl><dt>This version:<dd><a class=u-url href=http://dev.w3.org/csswg/css-font-loading/>http://dev.w3.org/csswg/css-font-loading/</a><dt>Latest version:<dd><a href=http://w3.org/TR/css-font-loading/>http://w3.org/TR/css-font-loading/</a><dt>Previous Versions:<dd><a href=http://www.w3.org/TR/2014/WD-css-font-loading-3-20140522/ rel=previous>http://www.w3.org/TR/2014/WD-css-font-loading-3-20140522/</a><dt>Feedback:<dd><span><a href="mailto:www-style@w3.org?subject=[css-font-loading] feedback">www-style@w3.org</a> with subject line “<kbd>[css-font-loading] <var>… message topic …</var></kbd>” (<a href=http://lists.w3.org/Archives/Public/www-style/ rel=discussion>archives</a>)</span><dt>Editor:<dd><div class="p-author h-card vcard"><a class="p-name fn u-url url" href=http://xanthir.com/contact/>Tab Atkins Jr.</a> (<span class="p-org org">Google</span>)</div><dt>Former Editor:<dd><div class="p-author h-card vcard"><a class="p-name fn u-email email" href=mailto:jdaggett@mozilla.com>John Daggett</a> (<span class="p-org org">Mozilla</span>)</div></dl></div>
<div data-fill-with=warning></div>
<p class=copyright data-fill-with=copyright><a href=http://www.w3.org/Consortium/Legal/ipr-notice#Copyright>Copyright</a> © 2014 <a href=http://www.w3.org/><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href=http://www.csail.mit.edu/><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href=http://www.ercim.eu/><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href=http://www.keio.ac.jp/>Keio</a>, <a href=http://ev.buaa.edu.cn/>Beihang</a>), All Rights Reserved. W3C <a href=http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer>liability</a>, <a href=http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks>trademark</a> and <a href=http://www.w3.org/Consortium/Legal/copyright-documents>document use</a> rules apply.
</p>
<hr title="Separator for header">
</div>
<h2 class="no-num no-toc no-ref heading settled" id=abstract><span class=content>Abstract</span></h2>
<div class=p-summary data-fill-with=abstract><p>This CSS module describes events and interfaces used for dynamically loading font resources.</p>
<a href=http://www.w3.org/TR/CSS/>CSS</a> is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, in speech, etc.</div>
<h2 class="no-num no-toc no-ref heading settled" id=status><span class=content>Status of this document</span></h2>
<div data-fill-with=status><p>
This is a public copy of the editors’ draft.
It is provided for discussion only and may change at any moment.
Its publication here does not imply endorsement of its contents by W3C.
Don’t cite this document other than as work in progress.
<p>
The (<a href=http://lists.w3.org/Archives/Public/www-style/>archived</a>) public mailing list
<a href="mailto:www-style@w3.org?Subject=%5Bcss-font-loading%5D%20PUT%20SUBJECT%20HERE">www-style@w3.org</a>
(see <a href=http://www.w3.org/Mail/Request>instructions</a>)
is preferred for discussion of this specification.
When sending e-mail,
please put the text “css-font-loading” in the subject,
preferably like this:
“[css-font-loading] <em>…summary of comment…</em>”
<p>
This document was produced by the <a href=http://www.w3.org/Style/CSS/members>CSS Working Group</a>
(part of the <a href=http://www.w3.org/Style/>Style Activity</a>).
<p>
This document was produced by a group operating under
the <a href=http://www.w3.org/Consortium/Patent-Policy-20040205/>5 February 2004 W3C Patent Policy</a>.
W3C maintains a <a href=http://www.w3.org/2004/01/pp-impl/32061/status rel=disclosure>public list of any patent disclosures</a>
made in connection with the deliverables of the group;
that page also includes instructions for disclosing a patent.
An individual who has actual knowledge of a patent which the individual believes contains <a href=http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential>Essential Claim(s)</a>
must disclose the information in accordance with <a href=http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure>section 6 of the W3C Patent Policy</a>.</div>
<div data-fill-with=at-risk></div>
<h2 class="no-num no-toc no-ref heading settled" id=contents><span class=content>Table of Contents</span></h2>
<div data-fill-with=table-of-contents><ul class=toc><li><a href=#introduction><span class=secno>1</span> <span class=content>
Introduction</span></a><ul class=toc><li><a href=#values><span class=secno>1.1</span> <span class=content>
Values</span></a><li><a href=#task-source><span class=secno>1.2</span> <span class=content>
Task Sources</span></a></ul><li><a href=#fontface-interface><span class=secno>2</span> <span class=content>
The <code>FontFace</code> Interface</span></a><ul class=toc><li><a href=#font-face-constructor><span class=secno>2.1</span> <span class=content>
The Constructor</span></a><li><a href=#font-face-load><span class=secno>2.2</span> <span class=content>
The <code>load()</code> method</span></a><li><a href=#font-face-css-connection><span class=secno>2.3</span> <span class=content>
Interaction with CSS’s <span class=css data-link-type=maybe title=@font-face>@font-face</span> Rule</span></a></ul><li><a href=#FontFaceSet-interface><span class=secno>3</span> <span class=content>
The <code>FontFaceSet</code> Interface</span></a><ul class=toc><li><a href=#FontFaceSet-events><span class=secno>3.1</span> <span class=content>
Events</span></a><li><a href=#font-face-set-load><span class=secno>3.2</span> <span class=content>
The <code>load()</code> method</span></a><li><a href=#font-face-set-check><span class=secno>3.3</span> <span class=content>
The <code>check()</code> method</span></a><li><a href=#font-face-set-ready><span class=secno>3.4</span> <span class=content>
The <code>ready</code> attribute</span></a><li><a href=#font-face-set-css><span class=secno>3.5</span> <span class=content>
Interaction with CSS Font Loading and Matching</span></a></ul><li><a href=#font-face-source><span class=secno>4</span> <span class=content>
The <code>FontFaceSource</code> interface</span></a><ul class=toc><li><a href=#fontfacesource-workers><span class=secno>4.1</span> <span class=content>
Worker FontFaceSources</span></a><li><a href=#document-font-face-set><span class=secno>4.2</span> <span class=content>
Interaction with CSS’s <span class=css data-link-type=maybe title=@font-face>@font-face</span> Rule</span></a></ul><li><a href=#font-load-event-examples><span class=secno>5</span> <span class=content>
API Examples</span></a><li><a href=#changes><span class=secno></span> <span class=content>Changes</span></a><li><a href=#acknowledgments><span class=secno></span> <span class=content>
Acknowledgments</span></a><li><a href=#conformance><span class=secno></span> <span class=content>
Conformance</span></a><ul class=toc><li><a href=#conventions><span class=secno></span> <span class=content>
Document conventions</span></a><li><a href=#conformance-classes><span class=secno></span> <span class=content>
Conformance classes</span></a><li><a href=#partial><span class=secno></span> <span class=content>
Partial implementations</span></a><li><a href=#experimental><span class=secno></span> <span class=content>
Experimental implementations</span></a><li><a href=#testing><span class=secno></span> <span class=content>
Non-experimental implementations</span></a></ul><li><a href=#references><span class=secno></span> <span class=content>References</span></a><ul class=toc><li><a href=#normative><span class=secno></span> <span class=content>Normative References</span></a></ul><li><a href=#index><span class=secno></span> <span class=content>Index</span></a><li><a href=#issues-index><span class=secno></span> <span class=content>Issues Index</span></a></ul></div>
<h2 class="heading settled" data-level=1 id=introduction><span class=secno>1 </span><span class=content>
Introduction</span><a class=self-link href=#introduction></a></h2>
<p>CSS allows authors to load custom fonts from the web via the <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule.
While this is easy to use when authoring a stylesheet,
it’s much more difficult to use dynamically via scripting.</p>
<p>Further, CSS allows the user agent to choose when to actually load a font;
if a font face isn’t <em>currently</em> used by anything on a page,
most user agents will not download its associated file.
This means that later use of the font face will incur a delay
as the user agent finally notices a usage and begins downloading and parsing the font file.</p>
<p>This specification defines a scripting interface to font faces in CSS,
allowing font faces to be easily created and loaded from script.
It also provides methods to track the loading status of an individual font,
or of all the fonts on an entire page.</p>
<p class=issue id=issue-531209c4><a class=self-link href=#issue-531209c4></a>Several things in this spec use normal ES objects to define behavior,
such as various things using Promises internally,
and FontFaceSet using a Set internally.
I believe the intention here is that these objects
(and their prototype chains) are pristine,
unaffected by anything the author has done.
Is this a good intention?
If so, how should I indicate this in the spec?</p>
<h3 class="heading settled" data-level=1.1 id=values><span class=secno>1.1 </span><span class=content>
Values</span><a class=self-link href=#values></a></h3>
<p>This specification uses <dfn class=idl-code data-dfn-type=interface data-export="" id=dom-promise title=Promise>Promises<a class=self-link href=#dom-promise></a></dfn>,
which are defined in <a href="http://wiki.ecmascript.org/doku.php?id=harmony:specification_drafts">ECMAScript 6</a>.
HTML5Rocks has some <a href=http://www.html5rocks.com/en/tutorials/es6/promises/>good tutorial material introducing Promises</a>.</p>
<h3 class="heading settled" data-level=1.2 id=task-source><span class=secno>1.2 </span><span class=content>
Task Sources</span><a class=self-link href=#task-source></a></h3>
<p>Whenever this specification queues a task,
it queues it onto the "font loading" task source.</p>
<h2 class="heading settled" data-level=2 id=fontface-interface><span class=secno>2 </span><span class=content>
The <code>FontFace</code> Interface</span><a class=self-link href=#fontface-interface></a></h2>
<p>The <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> interface represents a single usable font face.
CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rules implicitly define FontFace objects,
or they can be constructed manually from a url or binary data.</p>
<pre class=idl>typedef (<a data-link-type=idl href=http://www.khronos.org/registry/typedarray/specs/latest/#ArrayBuffer title=ArrayBuffer>ArrayBuffer</a> or <a data-link-type=idl href=http://www.khronos.org/registry/typedarray/specs/latest/#ArrayBufferView title=ArrayBufferView>ArrayBufferView</a>) <dfn class=idl-code data-dfn-type=typedef data-export="" data-global-name="" id=typedefdef-binarydata>BinaryData<a class=self-link href=#typedefdef-binarydata></a></dfn>;
dictionary <dfn class=idl-code data-dfn-type=dictionary data-export="" data-global-name="" id=dictdef-fontfacedescriptors>FontFaceDescriptors<a class=self-link href=#dictdef-fontfacedescriptors></a></dfn> {
DOMString <dfn class=idl-code data-default='"normal"' data-dfn-for=FontFaceDescriptors data-dfn-type=dict-member data-export="" data-global-name="FontFaceDescriptors<dictionary>/style<dict-member>" data-type="DOMString " id=dom-fontfacedescriptors-style>style<a class=self-link href=#dom-fontfacedescriptors-style></a></dfn> = "normal";
DOMString <dfn class=idl-code data-default='"normal"' data-dfn-for=FontFaceDescriptors data-dfn-type=dict-member data-export="" data-global-name="FontFaceDescriptors<dictionary>/weight<dict-member>" data-type="DOMString " id=dom-fontfacedescriptors-weight>weight<a class=self-link href=#dom-fontfacedescriptors-weight></a></dfn> = "normal";
DOMString <dfn class=idl-code data-default='"normal"' data-dfn-for=FontFaceDescriptors data-dfn-type=dict-member data-export="" data-global-name="FontFaceDescriptors<dictionary>/stretch<dict-member>" data-type="DOMString " id=dom-fontfacedescriptors-stretch>stretch<a class=self-link href=#dom-fontfacedescriptors-stretch></a></dfn> = "normal";
DOMString <dfn class=idl-code data-default='"U+0-10FFFF"' data-dfn-for=FontFaceDescriptors data-dfn-type=dict-member data-export="" data-global-name="FontFaceDescriptors<dictionary>/unicoderange<dict-member>" data-type="DOMString " id=dom-fontfacedescriptors-unicoderange>unicodeRange<a class=self-link href=#dom-fontfacedescriptors-unicoderange></a></dfn> = "U+0-10FFFF";
DOMString <dfn class=idl-code data-default='"normal"' data-dfn-for=FontFaceDescriptors data-dfn-type=dict-member data-export="" data-global-name="FontFaceDescriptors<dictionary>/variant<dict-member>" data-type="DOMString " id=dom-fontfacedescriptors-variant>variant<a class=self-link href=#dom-fontfacedescriptors-variant></a></dfn> = "normal";
DOMString <dfn class=idl-code data-default='"normal"' data-dfn-for=FontFaceDescriptors data-dfn-type=dict-member data-export="" data-global-name="FontFaceDescriptors<dictionary>/featuresettings<dict-member>" data-type="DOMString " id=dom-fontfacedescriptors-featuresettings>featureSettings<a class=self-link href=#dom-fontfacedescriptors-featuresettings></a></dfn> = "normal";
};
enum <dfn class=idl-code data-dfn-type=enum data-export="" data-global-name="" id=enumdef-fontfaceloadstatus>FontFaceLoadStatus<a class=self-link href=#enumdef-fontfaceloadstatus></a></dfn> { "unloaded", "loading", "loaded", "error" };
[Constructor(DOMString <a class=idl-code data-global-name="FontFace<interface>/FontFace()<method>/family<argument>" data-link-for=FontFace/FontFace() data-link-type=argument href=#dom-fontface-fontface-family title=family>family</a>, (DOMString or <a data-link-type=idl href=#typedefdef-binarydata title=BinaryData>BinaryData</a>) <a class=idl-code data-global-name="FontFace<interface>/FontFace()<method>/source<argument>" data-link-for=FontFace/FontFace() data-link-type=argument href=#dom-fontface-fontface-source title=source>source</a>,
optional <a data-link-type=idl href=#dictdef-fontfacedescriptors title=FontFaceDescriptors>FontFaceDescriptors</a> <a class=idl-code data-global-name="FontFace<interface>/FontFace()<method>/descriptors<argument>" data-link-for=FontFace/FontFace() data-link-type=argument href=#dom-fontface-fontface-descriptors title=descriptors>descriptors</a>),
Exposed=Window,Worker]
interface <dfn class=idl-code data-dfn-type=interface data-export="" data-global-name="" id=dom-fontface>FontFace<a class=self-link href=#dom-fontface></a></dfn> {
attribute DOMString <a class=idl-code data-global-name="FontFace<interface>/family<attribute>" data-link-for=FontFace data-link-type=attribute data-type="DOMString " href=#dom-fontface-family title=family>family</a>;
attribute DOMString <a class=idl-code data-global-name="FontFace<interface>/style<attribute>" data-link-for=FontFace data-link-type=attribute data-type="DOMString " href=#dom-fontface-style title=style>style</a>;
attribute DOMString <a class=idl-code data-global-name="FontFace<interface>/weight<attribute>" data-link-for=FontFace data-link-type=attribute data-type="DOMString " href=#dom-fontface-weight title=weight>weight</a>;
attribute DOMString <a class=idl-code data-global-name="FontFace<interface>/stretch<attribute>" data-link-for=FontFace data-link-type=attribute data-type="DOMString " href=#dom-fontface-stretch title=stretch>stretch</a>;
attribute DOMString <a class=idl-code data-global-name="FontFace<interface>/unicoderange<attribute>" data-link-for=FontFace data-link-type=attribute data-type="DOMString " href=#dom-fontface-unicoderange title=unicodeRange>unicodeRange</a>;
attribute DOMString <a class=idl-code data-global-name="FontFace<interface>/variant<attribute>" data-link-for=FontFace data-link-type=attribute data-type="DOMString " href=#dom-fontface-variant title=variant>variant</a>;
attribute DOMString <a class=idl-code data-global-name="FontFace<interface>/featuresettings<attribute>" data-link-for=FontFace data-link-type=attribute data-type="DOMString " href=#dom-fontface-featuresettings title=featureSettings>featureSettings</a>;
readonly attribute <a data-link-type=idl href=#enumdef-fontfaceloadstatus title=FontFaceLoadStatus>FontFaceLoadStatus</a> <a class=idl-code data-global-name="FontFace<interface>/status<attribute>" data-link-for=FontFace data-link-type=attribute data-readonly="" data-type="FontFaceLoadStatus " href=#dom-fontface-status title=status>status</a>;
Promise&lt;<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a>&gt; <a class=idl-code data-global-name="FontFace<interface>/load()<method>" data-link-for=FontFace data-link-type=method href=#dom-fontface-load title=load()>load</a>();
readonly attribute Promise&lt;<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a>&gt; <a class=idl-code data-global-name="FontFace<interface>/loaded<attribute>" data-link-for=FontFace data-link-type=attribute data-readonly="" data-type="Promise<FontFace> " href=#dom-fontface-loaded title=loaded>loaded</a>;
};
</pre>
<p class=issue id=issue-4c5be6c8><a class=self-link href=#issue-4c5be6c8></a>Other APIs use other names for .loaded, like .readyState. Can we align?</p>
<p class=issue id=issue-2602b7ed><a class=self-link href=#issue-2602b7ed></a>"unloaded" is usually used for things that start loaded and then become not loaded.
Can we rename that value?
Media stuff uses "none", other APIs use "empty", "idle", "nothing".</p>
<dl data-dfn-for=FontFace data-dfn-type=attribute>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-family>family<a class=self-link href=#dom-fontface-family></a></dfn>, <span data-attribute-info="" for=family> of type <a data-link-type=idl-name title=DOMString>DOMString</a></span>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-style>style<a class=self-link href=#dom-fontface-style></a></dfn>, <span data-attribute-info="" for=style> of type <a data-link-type=idl-name title=DOMString>DOMString</a></span>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-weight>weight<a class=self-link href=#dom-fontface-weight></a></dfn>, <span data-attribute-info="" for=weight> of type <a data-link-type=idl-name title=DOMString>DOMString</a></span>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-stretch>stretch<a class=self-link href=#dom-fontface-stretch></a></dfn>, <span data-attribute-info="" for=stretch> of type <a data-link-type=idl-name title=DOMString>DOMString</a></span>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-unicoderange>unicodeRange<a class=self-link href=#dom-fontface-unicoderange></a></dfn>, <span data-attribute-info="" for=unicodeRange> of type <a data-link-type=idl-name title=DOMString>DOMString</a></span>
<dd>
These attributes all represent the corresponding aspects of a font face,
as defined by the descriptors defined in the CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule.
They are parsed the same as the corresponding <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> descriptors.
They are used by the font matching algorithm,
but otherwise have no effect.
<p>For example, a <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> with a <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-style title=style>style</a></code> of <code>"italic"</code>
<em>represents</em> an italic font face;
it does not <strong>make</strong> the font face italic.</p>
<p>On getting, return the string associated with this attribute.</p>
<p>On setting, parse the string according to the grammar for the CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule.
If it does not match the grammar,
throw a SyntaxError;
otherwise, set the attribute to the serialization of the parsed value.</p>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-variant>variant<a class=self-link href=#dom-fontface-variant></a></dfn>, <span data-attribute-info="" for=variant> of type <a data-link-type=idl-name title=DOMString>DOMString</a></span>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-featuresettings>featureSettings<a class=self-link href=#dom-fontface-featuresettings></a></dfn>, <span data-attribute-info="" for=featureSettings> of type <a data-link-type=idl-name title=DOMString>DOMString</a></span>
<dd>
These attributes have the same meaning,
and are parsed the same as,
the corresponding descriptors in the CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rules.
<p>They turn on or off specific features in fonts that support them.
Unlike the previous attributes,
these attributes actually affect the font face.</p>
<p>On getting, return the string associated with this attribute.</p>
<p>On setting, parse the string according to the grammar for the CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule.
If it does not match the grammar,
throw a SyntaxError;
otherwise, set the attribute to the serialization of the parsed value.</p>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-status>status<a class=self-link href=#dom-fontface-status></a></dfn>, <span data-attribute-info="" for=FontFace/status> of type <a data-link-type=idl-name href=#enumdef-fontfaceloadstatus title=FontFaceLoadStatus>FontFaceLoadStatus</a>, readonly</span>
<dd>
This attribute reflects the current status of the font face.
It must be "unloaded" for a newly-created <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code>.
<p>It can change due to an author explicitly requesting a font face to load,
such as through the <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-load title=load()>load()</a></code> method on <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code>,
or implicitly by the user agent,
due to it detecting that the font face is needed to draw some text on the screen.</p>
<dt><dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-loaded>loaded<a class=self-link href=#dom-fontface-loaded></a></dfn>, <span data-attribute-info="" for=loaded> of type Promise&lt;<a data-link-type=idl-name href=#dom-fontface title=FontFace>FontFace</a>&gt;, readonly</span>
<dd>
This attribute reflects the <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code> of the font face.
</dl>
<p>All <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects contain an internal <dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-fontstatuspromise>[[FontStatusPromise]]<a class=self-link href=#dom-fontface-fontstatuspromise></a></dfn> slot,
which tracks the status of the font.
It starts out pending,
and fulfills or rejects when the font is successfully loaded and parsed, or hits an error.</p>
<p>All <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects also contain
internal <dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-urls>[[Urls]]<a class=self-link href=#dom-fontface-urls></a></dfn> and <dfn class=idl-code data-dfn-for=FontFace data-dfn-type=attribute data-export="" id=dom-fontface-data>[[Data]]<a class=self-link href=#dom-fontface-data></a></dfn> slots,
of which one is <code>null</code> and the other is not <code>null</code>
(the non-null one is set by the constructor,
based on which data is passed in).</p>
<h3 class="heading settled" data-level=2.1 id=font-face-constructor><span class=secno>2.1 </span><span class=content>
The Constructor</span><a class=self-link href=#font-face-constructor></a></h3>
<p>A <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> can be constructed either
from a URL pointing to a font face file,
or from an ArrayBuffer (or ArrayBufferView) containing the binary representation of a font face.</p>
<p>When the <dfn class=idl-code data-dfn-for=FontFace data-dfn-type=method data-export="" id=dom-fontface-fontface title=FontFace()>FontFace<a class=self-link href=#dom-fontface-fontface></a></dfn>(DOMString <dfn class=idl-code data-dfn-for=FontFace/FontFace() data-dfn-type=argument data-export="" id=dom-fontface-fontface-family>family<a class=self-link href=#dom-fontface-fontface-family></a></dfn>, (DOMString or <code class=idl><a data-link-type=idl href=#typedefdef-binarydata title=BinaryData>BinaryData</a></code>) <dfn class=idl-code data-dfn-for=FontFace/FontFace() data-dfn-type=argument data-export="" id=dom-fontface-fontface-source>source<a class=self-link href=#dom-fontface-fontface-source></a></dfn>, <code class=idl><a data-link-type=idl href=#dictdef-fontfacedescriptors title=FontFaceDescriptors>FontFaceDescriptors</a></code> <dfn class=idl-code data-dfn-for=FontFace/FontFace() data-dfn-type=argument data-export="" id=dom-fontface-fontface-descriptors>descriptors<a class=self-link href=#dom-fontface-fontface-descriptors></a></dfn>) method is called,
execute these steps:</p>
<ol><li data-md=""><p>Let <var>font face</var> be a fresh <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object.
Set <var>font face’s</var> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to <code>"unloaded"</code>,
Set its internal <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code> slot to a fresh pending <code class=idl><a data-link-type=idl href=#dom-promise title=Promise>Promise</a></code> object.</p>
<p>Parse the <code class=idl><a class=idl-code data-link-type=argument href=#dom-fontface-fontface-family title=family>family</a></code> argument,
and the members of the <code class=idl><a class=idl-code data-link-type=argument href=#dom-fontface-fontface-descriptors title=descriptors>descriptors</a></code> argument,
according to the grammars of the corresponding descriptors of the CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule.
If any of them fail to parse correctly,
reject <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code> with a DOMException named "SyntaxError",
set <var>font face’s</var> corresponding attributes to the empty string,
and set <var>font face’s</var> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "error".
Otherwise, set <var>font face’s</var> corresponding attributes to the serialization of the parsed values.</p>
<p>Return <var>font face</var>.
If <var>font face’s <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> is "error",
terminate this algorithm;
otherwise,
complete the rest of these steps asynchronously.</var></p>
<li data-md=""><p>If the <code class=idl><a class=idl-code data-link-type=argument href=#dom-fontface-fontface-source title=source>source</a></code> argument was a <code class=idl><a data-link-type=idl title=DOMString>DOMString</a></code>,
parse it according to the grammar of the <a class=property data-link-type=propdesc href=http://dev.w3.org/csswg/css-fonts-3/#descdef-src title=src>src</a> descriptor of the CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule.
If it fails to parse correctly,
reject <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code> with a DOMException named "SyntaxError" exception,
queue a task to set <var>font face’s</var> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "error",
and abort these steps;
otherwise, set <var>font face’s</var> internal <code class=idl><a data-link-type=idl href=#dom-fontface-urls title=[[Urls]]>[[Urls]]</a></code> slot to the string.</p>
<p class=note>Note: Note that this means that passing a naked url as the source argument,
like <code>"http://example.com/myFont.woff"</code>,
won’t work - it needs to be at least wrapped in a <span class=css>url()</span> function,
like <code>"url(http://example.com/myFont.woff)"</code>.
In return for this inconvenience,
you get to specify multiple fallbacks,
specify the type of font each fallback is,
and refer to local fonts easily.</p>
<p class=issue id=issue-0c9d1948><a class=self-link href=#issue-0c9d1948></a>Need to define the base url,
so relative urls can resolve.
Should it be the url of the document?
Is that correct for workers too,
or should they use their worker url?
Is that always defined?</p>
67F6
<p>If the <code class=idl><a data-link-type=idl href=#dom-fontface-fontface-source title=source>source</a></code> argument was a <code class=idl><a data-link-type=idl href=#typedefdef-binarydata title=BinaryData>BinaryData</a></code>,
set <var>font face’s</var> internal <code class=idl><a data-link-type=idl href=#dom-fontface-data title=[[Data]]>[[Data]]</a></code> slot to the passed argument.</p>
<li data-md=""><p>If <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-data title=[[Data]]>[[Data]]</a></code> slot is not <code>null</code>,
queue a task to set <var>font face’s</var> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "loading".
Attempt to parse the data in it as a font.
When this is completed,
successfully or not,
queue a task to run the following steps synchronously:</p>
<ol><li data-md=""><p>If the load was successful,
<var>font face</var> now represents the parsed font;
fulfill <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code> with <var>font face</var>,
and set its <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "loaded".</p>
<li data-md=""><p>Otherwise,
reject <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code> with a DOMException named "SyntaxError"
and set <var>font face’s</var> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "error".</p>
</ol></ol>
<p class=note>Note: Newly constructed FontFace objects are not automatically added
to the FontFaceSet associated with a document
or a context for a worker thread.
This means that while newly constructed fonts can be preloaded,
they cannot actually be used until they are explicitly added to a FontFaceSet.
See the following section for a more complete description of FontFaceSet.</p>
<h3 class="heading settled" data-level=2.2 id=font-face-load><span class=secno>2.2 </span><span class=content>
The <code>load()</code> method</span><a class=self-link href=#font-face-load></a></h3>
<p>The <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-load title=load()>load()</a></code> method of <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code>
forces a url-based font face to request its font data and load.
For fonts constructed from binary data,
or fonts that are already loading or loaded,
it does nothing.</p>
<p>When the <dfn class=idl-code data-dfn-for=FontFace data-dfn-type=method data-export="" id=dom-fontface-load>load()<a class=self-link href=#dom-fontface-load></a></dfn> method is called,
execute these steps:</p>
<ol data-link-type=idl>
<li>
Let <var>font face</var> be the <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object on which this method was called.
<li>
If <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-urls title=[[Urls]]>[[Urls]]</a></code> slot is <code>null</code>,
or its <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute is anything other than <code>"unloaded"</code>,
return <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code>
and abort these steps.
<li>
Otherwise,
set <var>font face’s</var> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "loading",
return <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code>,
and continue executing the rest of this algorithm asynchronously.
<li>
Using the value of <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-urls title=[[Urls]]>[[Urls]]</a></code> slot,
attempt to load a font as defined in <a data-biblio-type=normative data-link-type=biblio href=#biblio-css3-fonts title=CSS3-FONTS>[CSS3-FONTS]</a>,
as if it was the value of a <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule’s <a class=property data-link-type=propdesc href=http://dev.w3.org/csswg/css-fonts-3/#descdef-src title=src>src</a> descriptor.
<li>
When the load operation completes,
successfully or not,
queue a task to run the following steps synchronously:
<ol>
<li>
If the attempt to load fails,
reject <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code> with
a DOMException whose name is "NetworkError"
and set <var>font face’s</var> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "error".
<li>
Otherwise,
<var>font face</var> now represents the loaded font;
fulfill <var>font face’s</var> <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code> with <var>font face</var>
and set <var>font face’s</var> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "loaded".
</ol>
</ol>
<p>User agents can initiate font loads on their own,
whenever they determine that a given font face is necessary to render something on the page.
When this happens,
they must act as if they had called the corresponding <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code>’s <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-load title=load()>load()</a></code> method described here.</p>
<p class=note>Note: Some UAs utilize a "font cache"
which avoids having to download the same font multiple times
on a page or on multiple pages within the same origin.
Multiple <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects can be mapped to the same entry in the font cache,
which means that a <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object might start loading unexpectedly,
even if it’s not in a <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>,
because some other <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object pointing to the same font data
(perhaps on a different page entirely!)
has been loaded.</p>
<h3 class="heading settled" data-level=2.3 id=font-face-css-connection><span class=secno>2.3 </span><span class=content>
Interaction with CSS’s <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> Rule</span><a class=self-link href=#font-face-css-connection></a></h3>
<p>A CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule automatically defines a corresponding <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object,
which is automatically placed in the document’s <a data-link-type=dfn href=#font-source title="font source">font source</a>
when the rule is parsed.
This <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object is <dfn data-dfn-type=dfn data-noexport="" id=css-connected>CSS-connected<a class=self-link href=#css-connected></a></dfn>.</p>
<p>The <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object corresponding to a <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule
has its <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-family title=family>family</a></code>, <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-style title=style>style</a></code>, <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-weight title=weight>weight</a></code>, <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-stretch title=stretch>stretch</a></code>, <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-unicoderange title=unicodeRange>unicodeRange</a></code>, <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-variant title=variant>variant</a></code>, and <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-featuresettings title=featureSettings>featureSettings</a></code> attributes
set to the same value as the corresponding descriptors in the <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule.
There is a two-way connection between the two:
any change made to a <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> descriptor is immediately reflected in the corresponding <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> attribute,
and vice versa.</p>
<p>The internal <code class=idl><a data-link-type=idl href=#dom-fontface-urls title=[[Urls]]>[[Urls]]</a></code> slot of the <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object is set to the value of the <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule’s <a class=property data-link-type=propdesc href=http://dev.w3.org/csswg/css-fonts-3/#descdef-src title=src>src</a> descriptor,
and reflects any changes made to the <a class=property data-link-type=propdesc href=http://dev.w3.org/csswg/css-fonts-3/#descdef-src title=src>src</a> descriptor.</p>
<p>Otherwise, a <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object created by a CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule is identical to one created manually.</p>
<p>If a <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule is removed from the document, its corresponding <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object is no longer <a data-link-type=dfn href=#css-connected title=CSS-connected>CSS-connected</a>.
The connection is not restorable by any means
(but adding the <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> back to the stylesheet will create a brand new <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object which <em>is</em> <a data-link-type=dfn href=#css-connected title=CSS-connected>CSS-connected</a>).</p>
<h2 class="heading settled" data-level=3 id=FontFaceSet-interface><span class=secno>3 </span><span class=content>
The <code>FontFaceSet</code> Interface</span><a class=self-link href=#FontFaceSet-interface></a></h2>
<pre class=idl>dictionary <dfn class=idl-code data-dfn-type=dictionary data-export="" data-global-name="" id=dictdef-fontfacesetloadeventinit>FontFaceSetLoadEventInit<a class=self-link href=#dictdef-fontfacesetloadeventinit></a></dfn> : <a data-link-type=idl href=http://dom.spec.whatwg.org/#eventinit title=EventInit>EventInit</a> {
sequence&lt;<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a>&gt; <dfn class=idl-code data-default=None data-dfn-for=FontFaceSetLoadEventInit data-dfn-type=dict-member data-export="" data-global-name="FontFaceSetLoadEventInit<dictionary>/fontfaces<dict-member>" data-type="sequence<FontFace> " id=dom-fontfacesetloadeventinit-fontfaces>fontfaces<a class=self-link href=#dom-fontfacesetloadeventinit-fontfaces></a></dfn> = [];
};
[Constructor(DOMString <dfn class=idl-code data-dfn-for=FontFaceSetLoadEvent/FontFaceSetLoadEvent() data-dfn-type=argument data-export="" data-global-name="FontFaceSetLoadEvent<interface>/FontFaceSetLoadEvent()<method>/type<argument>" id=dom-fontfacesetloadevent-fontfacesetloadevent-type>type<a class=self-link href=#dom-fontfacesetloadevent-fontfacesetloadevent-type></a></dfn>, optional <a data-link-type=idl href=#dictdef-fontfacesetloadeventinit title=FontFaceSetLoadEventInit>FontFaceSetLoadEventInit</a> <dfn class=idl-code data-dfn-for=FontFaceSetLoadEvent/FontFaceSetLoadEvent() data-dfn-type=argument data-export="" data-global-name="FontFaceSetLoadEvent<interface>/FontFaceSetLoadEvent()<method>/eventinitdict<argument>" id=dom-fontfacesetloadevent-fontfacesetloadevent-eventinitdict>eventInitDict<a class=self-link href=#dom-fontfacesetloadevent-fontfacesetloadevent-eventinitdict></a></dfn>),
Exposed=Window,Worker]
interface <dfn class=idl-code data-dfn-type=interface data-export="" data-global-name="" id=dom-fontfacesetloadevent>FontFaceSetLoadEvent<a class=self-link href=#dom-fontfacesetloadevent></a></dfn> : <a data-link-type=idl href=http://dom.spec.whatwg.org/#event title=Event>Event</a> {
readonly attribute sequence&lt;<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a>&gt; <dfn class=idl-code data-dfn-for=FontFaceSetLoadEvent data-dfn-type=attribute data-export="" data-global-name="FontFaceSetLoadEvent<interface>/fontfaces<attribute>" data-readonly="" data-type="sequence<FontFace> " id=dom-fontfacesetloadevent-fontfaces>fontfaces<a class=self-link href=#dom-fontfacesetloadevent-fontfaces></a></dfn>;
};
enum <dfn class=idl-code data-dfn-type=enum data-export="" data-global-name="" id=enumdef-fontfacesetloadstatus>FontFaceSetLoadStatus<a class=self-link href=#enumdef-fontfacesetloadstatus></a></dfn> { "loading", "loaded" };
callback <dfn class=idl-code data-dfn-type=callback data-export="" data-global-name="" id=callbackdef-foreachcallback>ForEachCallback<a class=self-link href=#callbackdef-foreachcallback></a></dfn> = void (<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a> <dfn class=idl-code data-dfn-for=ForEachCallback data-dfn-type=argument data-export="" data-global-name="ForEachCallback/font<argument>" id=dom-foreachcallback-font>font<a class=self-link href=#dom-foreachcallback-font></a></dfn>, long <dfn class=idl-code data-dfn-for=ForEachCallback data-dfn-type=argument data-export="" data-global-name="ForEachCallback/index<argument>" id=dom-foreachcallback-index>index<a class=self-link href=#dom-foreachcallback-index></a></dfn>, <a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a> <dfn class=idl-code data-dfn-for=ForEachCallback data-dfn-type=argument data-export="" data-global-name="ForEachCallback/self<argument>" id=dom-foreachcallback-self>self<a class=self-link href=#dom-foreachcallback-self></a></dfn>);
[Exposed=Window,Worker,
Constructor(sequence initialFaces)]
interface <dfn class=idl-code data-dfn-type=interface data-export="" data-global-name="" id=dom-fontfaceset>FontFaceSet<a class=self-link href=#dom-fontfaceset></a></dfn> : <a data-link-type=idl href=http://dom.spec.whatwg.org/#eventtarget title=EventTarget>EventTarget</a> {
// Emulate the Set interface, until we can extend Set correctly.
readonly attribute unsigned long <a class=idl-code data-global-name="FontFaceSet<interface>/size<attribute>" data-link-for=FontFaceSet data-link-type=attribute data-readonly="" data-type="unsigned long " href=#dom-fontfaceset-size title=size>size</a>;
void <a class=idl-code data-global-name="FontFaceSet<interface>/add()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-add title=add()>add</a>(<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a> <dfn class=idl-code data-dfn-for=FontFaceSet/add() data-dfn-type=argument data-export="" data-global-name="FontFaceSet<interface>/add()<method>/font<argument>" id=dom-fontfaceset-add-font>font<a class=self-link href=#dom-fontfaceset-add-font></a></dfn>);
boolean <a class=idl-code data-global-name="FontFaceSet<interface>/has()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-has title=has()>has</a>(<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a> <dfn class=idl-code data-dfn-for=FontFaceSet/has() data-dfn-type=argument data-export="" data-global-name="FontFaceSet<interface>/has()<method>/font<argument>" id=dom-fontfaceset-has-font>font<a class=self-link href=#dom-fontfaceset-has-font></a></dfn>);
boolean <a class=idl-code data-global-name="FontFaceSet<interface>/delete()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-delete title=delete()>delete</a>(<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a> <dfn class=idl-code data-dfn-for=FontFaceSet/delete() data-dfn-type=argument data-export="" data-global-name="FontFaceSet<interface>/delete()<method>/font<argument>" id=dom-fontfaceset-delete-font>font<a class=self-link href=#dom-fontfaceset-delete-font></a></dfn>);
void <a class=idl-code data-global-name="FontFaceSet<interface>/clear()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-clear title=clear()>clear</a>();
<a data-link-type=idl href=#dom-fontfaceset-iterator title=Iterator>Iterator</a> <a class=idl-code data-global-name="FontFaceSet<interface>/entries()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-entries title=entries()>entries</a>();
<a data-link-type=idl href=#dom-fontfaceset-iterator title=Iterator>Iterator</a> <a class=idl-code data-global-name="FontFaceSet<interface>/keys()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-keys title=keys()>keys</a>();
<a data-link-type=idl href=#dom-fontfaceset-iterator title=Iterator>Iterator</a> <a class=idl-code data-global-name="FontFaceSet<interface>/values()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-values title=values()>values</a>();
void <a class=idl-code data-global-name="FontFaceSet<interface>/foreach()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-foreach title=forEach()>forEach</a>(<a data-link-type=idl href=#callbackdef-foreachcallback title=ForEachCallback>ForEachCallback</a> <dfn class=idl-code data-dfn-for=FontFaceSet/forEach() data-dfn-type=argument data-export="" data-global-name="FontFaceSet<interface>/forEach()<method>/cb<argument>" id=dom-fontfaceset-foreach-cb>cb<a class=self-link href=#dom-fontfaceset-foreach-cb></a></dfn>, optional any<dfn class=idl-code data-dfn-for=FontFaceSet/forEach() data-dfn-type=argument data-export="" data-global-name="FontFaceSet<interface>/forEach()<method>/thisarg<argument>" id=dom-fontfaceset-foreach-thisarg>thisArg<a class=self-link href=#dom-fontfaceset-foreach-thisarg></a></dfn>);
<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a> iterator;
// -- events for when loading state changes
attribute <a data-link-type=idl href=http://www.w3.org/html/wg/drafts/html/CR/webappapis.html#eventhandler title=EventHandler>EventHandler</a> <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" data-global-name="FontFaceSet<interface>/onloading<attribute>" data-type="EventHandler " id=dom-fontfaceset-onloading>onloading<a class=self-link href=#dom-fontfaceset-onloading></a></dfn>;
attribute <a data-link-type=idl href=http://www.w3.org/html/wg/drafts/html/CR/webappapis.html#eventhandler title=EventHandler>EventHandler</a> <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" data-global-name="FontFaceSet<interface>/onloadingdone<attribute>" data-type="EventHandler " id=dom-fontfaceset-onloadingdone>onloadingdone<a class=self-link href=#dom-fontfaceset-onloadingdone></a></dfn>;
attribute <a data-link-type=idl href=http://www.w3.org/html/wg/drafts/html/CR/webappapis.html#eventhandler title=EventHandler>EventHandler</a> <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" data-global-name="FontFaceSet<interface>/onloadingerror<attribute>" data-type="EventHandler " id=dom-fontfaceset-onloadingerror>onloadingerror<a class=self-link href=#dom-fontfaceset-onloadingerror></a></dfn>;
// check and start loads if appropriate
// and fulfill promise when all loads complete
Promise&lt;sequence&lt;<a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a>&gt;&gt; <a class=idl-code data-global-name="FontFaceSet<interface>/load()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-load title=load()>load</a>(DOMString <a class=idl-code data-global-name="FontFaceSet<interface>/load()<method>/font<argument>" data-link-for=FontFaceSet/load() data-link-type=argument href=#dom-fontfaceset-load-font title=font>font</a>, optional DOMString <a class=idl-code data-global-name="FontFaceSet<interface>/load()<method>/text<argument>" data-link-for=FontFaceSet/load() data-link-type=argument href=#dom-fontfaceset-load-text title=text>text</a> = " ");
// return whether all fonts in the fontlist are loaded
// (does not initiate load if not available)
boolean <a class=idl-code data-global-name="FontFaceSet<interface>/check()<method>" data-link-for=FontFaceSet data-link-type=method href=#dom-fontfaceset-check title=check()>check</a>(DOMString <a class=idl-code data-global-name="FontFaceSet<interface>/check()<method>/font<argument>" data-link-for=FontFaceSet/check() data-link-type=argument href=#dom-fontfaceset-check-font title=font>font</a>, optional DOMString <a class=idl-code data-global-name="FontFaceSet<interface>/check()<method>/text<argument>" data-link-for=FontFaceSet/check() data-link-type=argument href=#dom-fontfaceset-check-text title=text>text</a> = " ");
// async notification that font loading and layout operations are done
readonly attribute Promise&lt;<a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a>&gt; <a class=idl-code data-global-name="FontFaceSet<interface>/ready<attribute>" data-link-for=FontFaceSet data-link-type=attribute data-readonly="" data-type="Promise<FontFaceSet> " href=#dom-fontfaceset-ready title=ready>ready</a>;
// loading state, "loading" while one or more fonts loading, "loaded" otherwise
readonly attribute <a data-link-type=idl href=#enumdef-fontfacesetloadstatus title=FontFaceSetLoadStatus>FontFaceSetLoadStatus</a> <a class=idl-code data-global-name="FontFaceSet<interface>/status<attribute>" data-link-for=FontFaceSet data-link-type=attribute data-readonly="" data-type="FontFaceSetLoadStatus " href=#dom-fontfaceset-status title=status>status</a>;
};
</pre>
<dl data-dfn-for=FontFaceSet data-dfn-type=attribute>
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" id=dom-fontfaceset-ready>ready<a class=self-link href=#dom-fontfaceset-ready></a></dfn> <span data-attribute-info="" for=FontFaceSet/ready> of type Promise&lt;<a data-link-type=idl-name href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a>&gt;, readonly</span>
<dd>
This attribute reflects the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>'s <code class=idl><a data-link-type=idl href=#dom-fontfaceset-readypromise title=[[ReadyPromise]]>[[ReadyPromise]]</a></code> slot.
<p>See <a data-section="" href=#font-face-set-ready>§3.4
The ready attribute</a> for more details on this <code class=idl><a data-link-type=idl href=#dom-promise title=Promise>Promise</a></code> and its use.</p>
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" id=dom-fontfaceset-size>size<a class=self-link href=#dom-fontfaceset-size></a></dfn> <span data-attribute-info="" for=FontFaceSet/size> of type <a data-link-type=idl-name title="unsigned long">unsigned long</a>, readonly</span>
<dd>
This attribute reflects the <code>size</code> attribute of the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>'s <code class=idl><a data-link-type=idl href=#dom-fontfaceset-containedfonts title=[[ContainedFonts]]>[[ContainedFonts]]</a></code> slot.
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" id=dom-fontfaceset-status>status<a class=self-link href=#dom-fontfaceset-status></a></dfn> <span data-attribute-info="" for=FontFaceSet/status> of type <a data-link-type=idl-name href=#enumdef-fontfacesetloadstatus title=FontFaceSetLoadStatus>FontFaceSetLoadStatus</a>, readonly</span>
<dd>
If there are <a data-link-type=dfn href=#possibly-pending-font-loads title="possibly pending font loads">possibly pending font loads</a>,
the <code class=idl><a data-link-for=FontFaceSet data-link-type=idl href=#dom-fontfaceset-status title=status>status</a></code> attribute must have the value <code>"loading"</code>.
Otherwise, it must have the value <code>"loaded"</code>.
</dl>
<dl data-dfn-for=FontFaceSet data-dfn-type=method>
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=constructor data-export="" id=dom-fontfaceset-fontfaceset title=FontFaceSet()>FontFaceSet<a class=self-link href=#dom-fontfaceset-fontfaceset></a></dfn>(sequence&lt;<code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code>&gt; <dfn class=idl-code data-dfn-for=FontFaceSet/FontFaceSet() data-dfn-type=argument data-export="" id=dom-fontfaceset-fontfaceset-initialfaces>initialFaces<a class=self-link href=#dom-fontfaceset-fontfaceset-initialfaces></a></dfn>)
<dd>
The <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> constructor, when called,
must construct a new <code class=idl><a data-link-type=idl title=Set>Set</a></code> object
by passing its <code class=idl><a data-link-type=idl href=#dom-fontfaceset-fontfaceset-initialfaces title=initialFaces>initialFaces</a></code> argument
to the <code class=idl><a data-link-type=idl title=Set>Set</a></code> constructor,
then assigning that <code class=idl><a data-link-type=idl title=Set>Set</a></code> object to the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>'s <code class=idl><a data-link-type=idl href=#dom-fontfaceset-containedfonts title=[[ContainedFonts]]>[[ContainedFonts]]</a></code> slot.
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-add title=add()>add<a class=self-link href=#dom-fontfaceset-add></a></dfn>(<code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> font)
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-has title=has()>has<a class=self-link href=#dom-fontfaceset-has></a></dfn>(<code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> font)
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-delete title=delete()>delete<a class=self-link href=#dom-fontfaceset-delete></a></dfn>(<code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> font)
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-entries title=entries()>entries<a class=self-link href=#dom-fontfaceset-entries></a></dfn>()
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-keys title=keys()>keys<a class=self-link href=#dom-fontfaceset-keys></a></dfn>()
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-values title=values()>values<a class=self-link href=#dom-fontfaceset-values></a></dfn>()
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-foreach title=forEach()>forEach<a class=self-link href=#dom-fontfaceset-foreach></a></dfn>(<code class=idl><a data-link-type=idl href=#callbackdef-foreachcallback title=ForEachCallback>ForEachCallback</a></code> cb, optional any thisArg)
<dd>
If <code class=idl><a data-link-type=idl href=#dom-fontfaceset-add title=add()>add()</a></code> or <code class=idl><a data-link-type=idl href=#dom-fontfaceset-delete title=delete()>delete()</a></code> are called
with an argument that is a <a data-link-type=dfn href=#css-connected title=CSS-connected>CSS-connected</a> <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object,
they must throw an InvalidModificationError exception.
<p>All of these methods call the corresponding method of the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>'s <code class=idl><a data-link-type=idl href=#dom-fontfaceset-containedfonts title=[[ContainedFonts]]>[[ContainedFonts]]</a></code> slot
with the same arguments as were passed to them,
and return the value returned by the called method.</p>
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-clear title=clear()>clear<a class=self-link href=#dom-fontfaceset-clear></a></dfn>()
<dd>
This must remove all non-<a data-link-type=dfn href=#css-connected title=CSS-connected>CSS-connected</a> <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects
from the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>'s <code class=idl><a data-link-type=idl href=#dom-fontfaceset-containedfonts title=[[ContainedFonts]]>[[ContainedFonts]]</a></code> slot.
<dt><dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=iterator data-export="" id=dom-fontfaceset-iterator title=iterator>iterator behavior<a class=self-link href=#dom-fontfaceset-iterator></a></dfn>
<dd>
The <a data-link-spec=webidl data-link-type=dfn href=https://heycam.github.io/webidl/#dfn-iterator-behavior title="iterator behavior">iterator behavior</a> is the iterator behavior of the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>'s <code class=idl><a data-link-type=idl href=#dom-fontfaceset-containedfonts title=[[ContainedFonts]]>[[ContainedFonts]]</a></code> slot.
</dl>
<p><code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> objects also have internal
<dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" id=dom-fontfaceset-loadingfonts>[[LoadingFonts]]<a class=self-link href=#dom-fontfaceset-loadingfonts></a></dfn>,
<dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" id=dom-fontfaceset-loadedfonts>[[LoadedFonts]]<a class=self-link href=#dom-fontfaceset-loadedfonts></a></dfn>,
and <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" id=dom-fontfaceset-failedfonts>[[FailedFonts]]<a class=self-link href=#dom-fontfaceset-failedfonts></a></dfn> slots,
all of which are initialized to the empty list,
a <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" id=dom-fontfaceset-readypromise>[[ReadyPromise]]<a class=self-link href=#dom-fontfaceset-readypromise></a></dfn> slot,
which is initialized to a fresh pending <code class=idl><a data-link-type=idl href=#dom-promise title=Promise>Promise</a></code>,
and a <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=attribute data-export="" id=dom-fontfaceset-containedfonts>[[ContainedFonts]]<a class=self-link href=#dom-fontfaceset-containedfonts></a></dfn> slot,
which is initialized by the <a class=idl-code data-link-type=constructor href=#dom-fontfaceset-fontfaceset title=FontFaceSet()>FontFaceSet constructor</a> to a <code class=idl><a data-link-type=idl title=Set>Set</a></code> object
(though see <a data-section="" href=#document-font-face-set>§4.2
Interaction with CSS’s @font-face Rule</a> for information on how the Set may be pre-filled
for <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> objects created by the user agent).</p>
<p>Because font families are loaded only when they are used,
content sometimes needs to understand when the loading of fonts occurs.
Authors can use the events and methods defined here to allow greater control over actions
that are dependent upon the availability of specific fonts.</p>
<p>There are <dfn data-dfn-type=dfn data-noexport="" id=no-pending-font-loads>no pending font loads<a class=self-link href=#no-pending-font-loads></a></dfn> whenever all of the following are true:</p>
<ul>
<li>
The document has finished loading.
<li>
There are no pending stylesheet requests.
<li>
There are no <a data-link-type=dfn href=#available-font-faces title="available font faces">available font faces</a>
with a <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> of "loading".
<li>
There are no pending layout operations which might cause the user agent to request a font.
</ul>
<p>If any of the above conditions are false,
there are <dfn data-dfn-type=dfn data-noexport="" id=possibly-pending-font-loads>possibly pending font loads<a class=self-link href=#possibly-pending-font-loads></a></dfn>.</p>
<p class=issue id=issue-8f48960a><a class=self-link href=#issue-8f48960a></a>The above is wrong; it assumes that you’re only asking about the <a data-link-type=dfn href=#font-source title="font source">font source</a>.
The <code class=idl><a data-link-for=FontFaceSet data-link-type=idl href=#dom-fontfaceset-status title=status>status</a></code> promise needs to pay attention to what <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> it’s attached to.
I guess only the <a data-link-type=dfn href=#font-source title="font source’s">font source’s</a> <code class=idl><a data-link-for=FontFaceSet data-link-type=idl href=#dom-fontfaceset-status title=status>status</a></code> promise should care about pending layout operations.</p>
<h3 class="heading settled" data-level=3.1 id=FontFaceSet-events><span class=secno>3.1 </span><span class=content>
Events</span><a class=self-link href=#FontFaceSet-events></a></h3>
<p>Font load events make it easy to respond to the font-loading behavior of the entire document,
rather than having to listen to each font specifically.
The <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=event data-export="" id=dom-fontfaceset-loading>loading<a class=self-link href=#dom-fontfaceset-loading></a></dfn> event
fires when the document begins loading fonts,
while the <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=event data-export="" id=dom-fontfaceset-loadingdone>loadingdone<a class=self-link href=#dom-fontfaceset-loadingdone></a></dfn>
and <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=event data-export="" id=dom-fontfaceset-loadingerror>loadingerror<a class=self-link href=#dom-fontfaceset-loadingerror></a></dfn> events
fire when the document is done loading fonts,
containing the fonts that successfully loaded
or failed to load,
respectively.</p>
<p>The following are the event handlers (and their corresponding event handler event types)
that must be supported by <code>FontFaceSet</code> objects as IDL attributes:</p>
<table class=data id=eventhandlers>
<thead>
<tr>
<th>Event handler
<th>Event handler event type
<tbody>
<tr>
<th><code class=idl><a data-link-type=idl href=#dom-fontfaceset-onloading title=onloading>onloading</a></code>
<td><code class=idl><a data-link-type=idl href=#dom-fontfaceset-loading title=loading>loading</a></code>
<tr>
<th><code class=idl><a data-link-type=idl href=#dom-fontfaceset-onloadingdone title=onloadingdone>onloadingdone</a></code>
<td><code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadingdone title=loadingdone>loadingdone</a></code>
<tr>
<th><code class=idl><a data-link-type=idl href=#dom-fontfaceset-onloadingerror title=onloadingerror>onloadingerror</a></code>
<td><code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadingerror title=loadingerror>loadingerror</a></code>
</table>
<p>To <dfn data-dfn-type=dfn data-noexport="" id=fire-a-font-load-event>fire a font load event<a class=self-link href=#fire-a-font-load-event></a></dfn> named <var>e</var>
at a <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> <var>target</var>
with optional <var>font faces</var>
means to
<a href=http://www.w3.org/TR/html5/webappapis.html#event-firing>fire a simple event</a> named <var>e</var>
using the <code class=idl><a data-link-type=idl href=#dom-fontfacesetloadevent title=FontFaceSetLoadEvent>FontFaceSetLoadEvent</a></code> interface that also meets these conditions:</p>
<ol>
<li>
The <code class=idl><a data-link-for=FontFaceSetLoadEvent data-link-type=idl href=#dom-fontfacesetloadevent-fontfaces title=fontfaces>fontfaces</a></code> attribute is initialized to the given list of <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects.
</ol>
<p>Whenever one or more <a data-link-type=dfn href=#available-font-faces title="available font faces">available font faces</a> for a given <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>
change their <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "loading",
the user agent must run the following steps:</p>
<ol>
<li>
Let <var>font face set</var> be the given <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>,
and <var>loading fonts</var> be the <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects
that have newly switched to "loading" status,
in the same order as they appear in <var>font face set</var>.
<li>
Set the <code class=idl><a data-link-for=FontFaceSet data-link-type=idl href=#dom-fontfaceset-status title=status>status</a></code> attribute of <var>font face set</var> to "loading".
<li>
If <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadingfonts title=[[LoadingFonts]]>[[LoadingFonts]]</a></code> slot is currently empty,
<a data-link-type=dfn href=#fire-a-font-load-event title="fire a font load event">fire a font load event</a> named <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loading title=loading>loading</a></code> at <var>font face set</var>.
<li>
Append the <var>loading fonts</var> to <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadingfonts title=[[LoadingFonts]]>[[LoadingFonts]]</a></code> slot.
<li>
If <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-readypromise title=[[ReadyPromise]]>[[ReadyPromise]]</a></code> slot currently holds a fulfilled promise,
replace it with a fresh pending promise.
</ol>
<p>Whenever one or more <a data-link-type=dfn href=#available-font-faces title="available font faces">available font faces</a> for a given <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>
change their <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute to "loaded" or "error",
the user agent must run the following steps:</p>
<ol>
<li>
Let <var>font face set</var> be the given <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>,
and <var>loaded fonts</var> be the <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects
that have newly switched to "loaded" or "error" status,
in the same order as they appear in <var>font face set</var>.
<li>
For each font in the <var>loaded fonts</var>,
if their <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute is "loaded",
append them to <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadedfonts title=[[LoadedFonts]]>[[LoadedFonts]]</a></code> slot;
if it’s "error",
append them to <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-failedfonts title=[[FailedFonts]]>[[FailedFonts]]</a></code> slot.
</ol>
<p>Whenever a <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> goes from having <a data-link-type=dfn href=#possibly-pending-font-loads title="possibly pending font loads">possibly pending font loads</a>
to having <a data-link-type=dfn href=#no-pending-font-loads title="no pending font loads">no pending font loads</a>,
user agents must run these steps:</p>
<ol>
<li>
Set <var>font face set’s</var> <code class=idl><a data-link-for=FontFaceSet data-link-type=idl href=#dom-fontfaceset-status title=status>status</a></code> attribute to "loaded".
<li>
<a data-link-type=dfn href=#fire-a-font-load-event title="Fire a font load event">Fire a font load event</a> named <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadingdone title=loadingdone>loadingdone</a></code> at <var>font face set</var>
with the (possibly empty) contents of <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadedfonts title=[[LoadedFonts]]>[[LoadedFonts]]</a></code> slot.
Reset the <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadedfonts title=[[LoadedFonts]]>[[LoadedFonts]]</a></code> slot to an empty list.
<li>
If <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-failedfonts title=[[FailedFonts]]>[[FailedFonts]]</a></code> slots is non-empty,
<a data-link-type=dfn href=#fire-a-font-load-event title="fire a font load event">fire a font load event</a> named <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadingerror title=loadingerror>loadingerror</a></code> at <var>font face set</var>
with the contents of <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-failedfonts title=[[FailedFonts]]>[[FailedFonts]]</a></code> slot.
Reset the <code class=idl><a data-link-type=idl href=#dom-fontfaceset-failedfonts title=[[FailedFonts]]>[[FailedFonts]]</a></code> slot to an empty list.
<li>
Fulfill <var>font face set’s</var> <code class=idl><a data-link-type=idl href=#dom-fontfaceset-readypromise title=[[ReadyPromise]]>[[ReadyPromise]]</a></code> attribute’s value with <var>font face set</var>.
</ol>
<p>If asked to <dfn data-dfn-type=dfn data-export="" id=find-the-matching-font-faces>find the matching font faces<a class=self-link hre 108A8 f=#find-the-matching-font-faces></a></dfn>
from a FontFaceSet <var>source</var>,
for a given font string <var>font</var>
optionally some sample text <var>text</var>,
and optionally an <var>allow system fonts</var> flag,
run the following steps:</p>
<ol>
<li>
Parse <var>font</var>
using the CSS value syntax of the <a class=property data-link-type=propdesc href=http://dev.w3.org/csswg/css-fonts-3/#propdef-font title=font>font</a> property.
If a syntax error occurs,
return a syntax error.
<li>
If <var>text</var> was not explicitly provided,
let it be a string containing a single space character (U+0020 SPACE).
<li>
Let <var>font family list</var> be the list of font families parsed from <var>font</var>,
and <var>font style</var> be the other font style attributes parsed from <var>font</var>.
<li>
Let <var>available font faces</var> be the font faces within <var>source</var>.
If the <var>allow system fonts</var> flag is specified,
add all system fonts to <var>available font faces</var>.
<li>
Let <var>matched font faces</var> initially be an empty list.
<li>
For each family in <var>font family list</var>,
use the font matching rules to select the font faces from <var>available font faces</var>
that match the <var>font style</var>,
and add them to <var>matched font faces</var>.
The use of the <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-unicoderange title=unicodeRange>unicodeRange</a></code> attribute means that this may be more than just a single font face.
<li>
For each font face in <var>matched font faces</var>,
if its defined <a class=property data-link-type=propdesc href=http://dev.w3.org/csswg/css-fonts-3/#descdef-unicode-range title=unicode-range>unicode-range</a> does not include the codepoint of at least one character in <var>text</var>,
remove it from the list.
<li>
Return <var>matched font faces</var>.
</ol>
<h3 class="heading settled" data-level=3.2 id=font-face-set-load><span class=secno>3.2 </span><span class=content>
The <code>load()</code> method</span><a class=self-link href=#font-face-set-load></a></h3>
<p>The {{FontFaceSet/load() method of <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> will determine whether all fonts in the given font list
have been loaded and are available.
If any fonts are downloadable fonts and have not already been loaded,
the user agent will initiate the load of each of these fonts.
It returns a Promise,
which is fulfilled when all of the fonts are loaded and ready to be used,
or rejected if any font failed to load properly.</p>
<p>When the <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-load title=load()>load<a class=self-link href=#dom-fontfaceset-load></a></dfn>(<dfn class=idl-code data-dfn-for=FontFaceSet/load() data-dfn-type=argument data-export="" id=dom-fontfaceset-load-font>font<a class=self-link href=#dom-fontfaceset-load-font></a></dfn>, <dfn class=idl-code data-dfn-for=FontFaceSet/load() data-dfn-type=argument data-export="" id=dom-fontfaceset-load-text>text<a class=self-link href=#dom-fontfaceset-load-text></a></dfn>) method is called,
execute these steps:</p>
<ol>
<li>
Let <var>font face set</var> be the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> object this method was called on.
Let <var>promise</var> be a newly-created promise object.
<li>
Return <var>promise</var>.
Complete the rest of these steps asynchronously.
<li>
<a data-link-type=dfn href=#find-the-matching-font-faces title="Find the matching font faces">Find the matching font faces</a> from <var>font face set</var>
using the <code class=idl><a data-link-for=FontFaceSet/load() data-link-type=idl href=#dom-fontfaceset-load-font title=font>font</a></code> and <code class=idl><a data-link-for=FontFaceSet/load() data-link-type=idl href=#dom-fontfaceset-load-text title=text>text</a></code> arguments passed to the function,
and let <var>font face list</var> be the return value.
If a syntax error was returned,
reject <var>promise</var> with a SyntaxError exception
and terminate these steps.
<li>
Queue a task to run the following steps synchronously:
<ol>
<li>
For all of the font faces in the <var>font face list</var>,
call their <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-load title=load()>load()</a></code> method.
<li>
Resolve <var>promise</var> with the result of
waiting for all of the <code class=idl><a data-link-type=idl href=#dom-fontface-fontstatuspromise title=[[FontStatusPromise]]>[[FontStatusPromise]]</a></code>s of each font face in the <var>font face list</var>, in order.
</ol>
</ol>
<h3 class="heading settled" data-level=3.3 id=font-face-set-check><span class=secno>3.3 </span><span class=content>
The <code>check()</code> method</span><a class=self-link href=#font-face-set-check></a></h3>
<p>The <code class=idl><a data-link-type=idl href=#dom-fontfaceset-check title=check()>check()</a></code> method of <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> will determine whether all fonts in the given font list
have been loaded and are available.
If all fonts are available,
it returns true;
otherwise, it returns false.</p>
<p>When the <dfn class=idl-code data-dfn-for=FontFaceSet data-dfn-type=method data-export="" id=dom-fontfaceset-check title=check()>check<a class=self-link href=#dom-fontfaceset-check></a></dfn>(<dfn class=idl-code data-dfn-for=FontFaceSet/check() data-dfn-type=argument data-export="" id=dom-fontfaceset-check-font>font<a class=self-link href=#dom-fontfaceset-check-font></a></dfn>, <dfn class=idl-code data-dfn-for=FontFaceSet/check() data-dfn-type=argument data-export="" id=dom-fontfaceset-check-text>text<a class=self-link href=#dom-fontfaceset-check-text></a></dfn>) method is called,
execute these steps:</p>
<ol>
<li>
Let <var>font face set</var> be the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> object this method was called on.
<li>
<a data-link-type=dfn href=#find-the-matching-font-faces title="Find the matching font faces">Find the matching font faces</a> from <var>font face set</var>
using the <code class=idl><a data-link-for=FontFaceSet/check() data-link-type=idl href=#dom-fontfaceset-check-font title=font>font</a></code> and <code class=idl><a data-link-for=FontFaceSet/check() data-link-type=idl href=#dom-fontfaceset-check-text title=text>text</a></code> arguments passed to the function,
and including system fonts,
and let <var>font face list</var> be the return value.
If a syntax error was returned,
throw a SyntaxError exception
and terminate these steps.
<li>
If the <var>font face list</var> contains no font faces,
return <code>false</code>.
<li>
If all fonts in the <var>font face list</var> have a <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-status title=status>status</a></code> attribute of "loaded",
or are system fonts,
return <code>true</code>.
Otherwise, return <code>false</code>.
</ol>
<h3 class="heading settled" data-level=3.4 id=font-face-set-ready><span class=secno>3.4 </span><span class=content>
The <code>ready</code> attribute</span><a class=self-link href=#font-face-set-ready></a></h3>
<p>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 <code class=idl><a data-link-for=FontFaceSet data-link-type=idl href=#dom-fontfaceset-ready title=ready>ready</a></code> attribute contains a <code class=idl><a data-link-type=idl href=#dom-promise title=Promise>Promise</a></code> 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.</p>
<p class=note>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 <code class=idl><a data-link-type=idl href=#dom-fontfaceset-loadingdone title=loadingdone>loadingdone</a></code> event to fire,
but the callbacks passed to the <code class=idl><a data-link-for=FontFaceSet data-link-type=idl href=#dom-fontfaceset-ready title=ready>ready</a></code> 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.</p>
<p class=note>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.</p>
<p class=note>Note: Note that the Promise returned by this <code class=idl><a data-link-for=FontFaceSet data-link-type=idl href=#dom-fontfaceset-ready title=ready>ready</a></code> attribute is only ever fulfilled,
never rejected,
unlike the Promise returned by the <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-load title=load()>load()</a></code> method.</p>
<h3 class="heading settled" data-level=3.5 id=font-face-set-css><span class=secno>3.5 </span><span class=content>
Interaction with CSS Font Loading and Matching</span><a class=self-link href=#font-face-set-css></a></h3>
<p>When the font matching algorithm in <a data-biblio-type=informative data-link-type=biblio href=#biblio-css3-fonts title=CSS3-FONTS>[CSS3-FONTS]</a> 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 data-link-type=dfn href=#font-source title="font source">font source</a> for the document,
plus any local font faces.</p>
<p>When a user-agent needs to load a font face,
it must do so by calling the <code class=idl><a data-link-for=FontFace data-link-type=idl href=#dom-fontface-load title=load()>load()</a></code> method
of the corresponding <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object.</p>
<p>(This means it must run the same algorithm,
not literally call the value currently stored in the <code>load</code> property of the object.)</p>
<div class=example>
Fonts are available when they are added to a <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>.
Adding a new <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule to a stylesheet
also adds a new <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> to the <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> of the <code class=idl><a data-link-type=idl href=http://dom.spec.whatwg.org/#document title=Document>Document</a></code> object.
<p>Adding a new <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule:</p>
<pre>document.styleSheets[0].insertRule(
"@font-face { font-family: newfont; src: url(newfont.woff); }", 0);
document.body.style.fontFamily = "newfont, serif";
</pre>
<p>Constructing a new <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> object and adding it to <code>document.fonts</code>:</p>
<pre>var f = new FontFace("newfont", "url(newfont.woff)");
document.fonts.add(f);
document.body.style.fontFamily = "newfont, serif";
</pre>
<p>In both cases, the loading of the font resource “newfont.woff” will be initiated by the layout engine,
just as other <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rule fonts are loaded.</p>
<p>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:</p>
<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>
<p>To explicitly preload a font before using it,
authors can defer the addition of a new <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> to a <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code> until the load has completed:</p>
<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>
<p>In this case, the font resource “newfont.woff” is first downloaded.
Once the download completes,
the font is added to the document’s <code class=idl><a data-link-type=idl href=#dom-fontfaceset title=FontFaceSet>FontFaceSet</a></code>,
the body font is changed,
and the layout engine uses the new font resource.</p>
</div>
<h2 class="heading settled" data-level=4 id=font-face-source><span class=secno>4 </span><span class=content>
The <code>FontFaceSource</code> interface</span><a class=self-link href=#font-face-source></a></h2>
<pre class=idl>[NoInterfaceObject]
interface <dfn class=idl-code data-dfn-type=interface data-export="" data-global-name="" id=dom-fontfacesource>FontFaceSource<a class=self-link href=#dom-fontfacesource></a></dfn> {
readonly attribute <a data-link-type=idl href=#dom 7263 -fontfaceset title=FontFaceSet>FontFaceSet</a> <dfn class=idl-code data-dfn-for=FontFaceSource data-dfn-type=attribute data-export="" data-global-name="FontFaceSource<interface>/fonts<attribute>" data-readonly="" data-type="FontFaceSet " id=dom-fontfacesource-fonts>fonts<a class=self-link href=#dom-fontfacesource-fonts></a></dfn>;
};
<a data-link-type=idl href=http://dom.spec.whatwg.org/#document title=Document>Document</a> implements <a data-link-type=idl href=#dom-fontfacesource title=FontFaceSource>FontFaceSource</a>;
<a data-link-type=idl title=WorkerGlobalScope>WorkerGlobalScope</a> implements <a data-link-type=idl href=#dom-fontfacesource title=FontFaceSource>FontFaceSource</a>;
</pre>
<p>Any document, workers, or other context which can use fonts in some manner must implement the <code class=idl><a data-link-type=idl href=#dom-fontfacesource title=FontFaceSource>FontFaceSource</a></code> interface.
The value of the context’s <code class=idl><a data-link-type=idl href=#dom-fontfacesource-fonts title=fonts>fonts</a></code> attribute is its <dfn data-dfn-type=dfn data-noexport="" id=font-source>font source<a class=self-link href=#font-source></a></dfn>,
which provides all of the fonts used in font-related operations,
unless defined otherwise.
Operations referring to “the font source” must be interpreted as referring to the <a data-link-type=dfn href=#font-source title="font source">font source</a> of the relevant context in which the operation is taking place.</p>
<p>For any font-related operation that takes place within one of these contexts,
the <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects within the <a data-link-type=dfn href=#font-source title="font source">font source</a> are its <dfn data-dfn-type=dfn data-noexport="" id=available-font-faces>available font faces<a class=self-link href=#available-font-faces></a></dfn>.</p>
<h3 class="heading settled" data-level=4.1 id=fontfacesource-workers><span class=secno>4.1 </span><span class=content>
Worker FontFaceSources</span><a class=self-link href=#fontfacesource-workers></a></h3>
<p>Within a Worker document, the <a data-link-type=dfn href=#font-source title="font source">font source</a> is initially empty.</p>
<p class=note>Note: <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects can be constructed and added to it as normal,
which affects CSS font-matching within the worker
(such as, for example, drawing text into a <code class=idl><a data-link-type=idl title=CanvasProxy>CanvasProxy</a></code>).</p>
<h3 class="heading settled" data-level=4.2 id=document-font-face-set><span class=secno>4.2 </span><span class=content>
Interaction with CSS’s <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> Rule</span><a class=self-link href=#document-font-face-set></a></h3>
<p>The set entries for a document’s <a data-link-type=dfn href=#font-source title="font source">font source</a>
must be initially populated with all the <a data-link-type=dfn href=#css-connected title=CSS-connected>CSS-connected</a> <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects
from all of the CSS <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rules in the document’s stylesheets,
in document order.
As <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rules are added or removed from a stylesheet,
or stylesheets containing <a class=css data-link-type=maybe href=http://dev.w3.org/csswg/css-fonts-3/#at-font-face-rule title=@font-face>@font-face</a> rules are added or removed,
the corresponding <a data-link-type=dfn href=#css-connected title=CSS-connected>CSS-connected</a> <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects
must be added or removed from the document’s <a data-link-type=dfn href=#font-source title="font source">font source</a>,
and maintain this ordering.</p>
<p>All non-<a data-link-type=dfn href=#css-connected title=CSS-connected>CSS-connected</a> <code class=idl><a data-link-type=idl href=#dom-fontface title=FontFace>FontFace</a></code> objects must be sorted after the <a data-link-type=dfn href=#css-connected title=CSS-connected>CSS-connected</a> ones,
in insertion order.</p>
<p class=note>Note: It is expected that a future version of this specification
will define ways of interacting with and querying local fonts as well.</p>
<h2 class="heading settled" data-level=5 id=font-load-event-examples><span class=secno>5 </span><span class=content>
API Examples</span><a class=self-link href=#font-load-event-examples></a></h2>
<div class=example>
To show content only after all font loads complete:
<pre>document.fonts.ready().then(function() {
View remainder of file in raw view