8000 csswg-drafts/cssom/Overview.src.html at 2d125e98bb9489b0dabd1277e63b1fa40f7d64a9 · w3c/csswg-drafts · GitHub
Skip to content

Overview.src.html

Latest commit

 

History

History
3292 lines (2617 loc) · 168 KB

Overview.src.html

File metadata and controls

3292 lines (2617 loc) · 168 KB
<!doctype html>
<html lang="en-US">
<head>
<meta charset=utf-8>
<title>CSS Object Model (CSSOM)</title>
<link rel=stylesheet href=../default.css>
<link rel="stylesheet" href="https://www.w3.org/StyleSheets/TR/W3C-[STATUS]">
</head>
<body class="draft">
<div class="head">
<!--logo-->
<h1>CSS Object Model (CSSOM)</h1>
<h2 class="no-num no-toc" id="w3c-doctype">[LONGSTATUS] [DATE: 3 August 2002]</h2>
<dl>
<dt>This Version:</dt>
<dd class=dontpublish><a href="http://dev.w3.org/csswg/cssom/">http://dev.w3.org/csswg/cssom/</a></dd>
<dd class=publish><a href="[VERSION]">[VERSION]</a></dd>
<dt class=dontpublish>Participate:</dt>
<dd class=dontpublish><a href="mailto:www-style@w3.org?subject=%5Bcssom%5D%20">www-style@w3.org</a>
(<a href="http://lists.w3.org/Archives/Public/www-style/">archives</a>)</dd>
<dd class=dontpublish><a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?product=CSS&amp;component=CSSOM">File a bug</a>
(<a href="https://www.w3.org/Bugs/Public/buglist.cgi?component=CSSOM&amp;product=CSS&amp;resolution=---">open bugs</a>)
<script async="" src="https://w3c-test.org/resources.whatwg.org/file-bug.js"></script></dd>
<dd class=dontpublish><a href="irc://irc.w3.org:6665/css">IRC: #css on W3C</a></dd>
<dt class=publish>Latest Version:</dt>
<dd class=publish><a href="[LATEST]">[LATEST]</a></dd>
<dt class=publish>Latest Editor's draft:</dt>
<dd class=publish><a href="http://dev.w3.org/csswg/cssom/">http://dev.w3.org/csswg/cssom/</a></dd>
<dt>Previous Versions:</dt>
<dd><a href="http://www.w3.org/TR/2011/WD-cssom-20110712/">http://www.w3.org/TR/2011/WD-cssom-20110712/</a></dd>
<dd><a href="http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113/">http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113/</a></dd>
<dt>Editors:</dt>
<dd>Simon Pieters
(<a href="http://www.opera.com/">Opera Software ASA</a>)
&lt;<a href="mailto:simonp@opera.com">simonp@opera.com</a>&gt;</dd>
<dd><a href="http://www.w3.org/wiki/User:Gadams">Glenn Adams</a>
(<a href="http://www.cox.com/">Cox Communications, Inc.</a>)
&lt;<a href="mailto:glenn.adams@cox.com">glenn.adams@cox.com</a>&gt;</dd>
<dt>Previous Editor:</dt>
<dd><a href="http://annevankesteren.nl/">Anne van Kesteren</a>
(<a href="http://www.opera.com/">Opera Software ASA</a>)
&lt;<a href="mailto:annevk@annevk.nl">annevk@annevk.nl</a>&gt;</dd>
</dl>
<!--copyright-->
</div>
<hr class="top">
<h2 class="no-num no-toc">Abstract</h2>
8096
<p>CSSOM defines APIs (including generic parsing and serialization rules)
for Media Queries, Selectors, and of course CSS itself.</p>
<h2 class="no-num no-toc" id="sotd">Status of This Document</h2>
<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 or by the CSS Working Group. Don't cite
this document other than as work in progress.</p>
<p class="note">Implementers should note well that this specification is an ongoing effort to sort out
what has been widely implemented and deployed from <span data-anolis-ref class=informative>DOM2STYLE</span> as well as common extensions thereto, some details
of which are currently interoperable and others which are not currently interoperable. As this specification moves
forward, it is hoped that these differences will be resolved and an unambiguous and adequate consensus-based
specification will emerge.</p>
<p><em>This section describes the status of this document at the time of
its publication. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical report
can be found in the
<a href="http://www.w3.org/TR/">W3C technical reports index at http://www.w3.org/TR/.</a></em>
<p class="dontpublish">This is the [DATE: 3 August 2002] [LONGSTATUS] of CSSOM. Please send comments to
<a href="mailto:www-style@w3.org?subject=%5Bcssom%5D%20">www-style@w3.org</a>
(<a href="http://lists.w3.org/Archives/Public/www-style/">archived</a>)
with <samp>[cssom]</samp> at the start of the subject line.
<p class="publish">This is the [DATE] First Public Working Draft of CSSOM, 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>).
<!--XXX remove "First Public" after initial publication -->
<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>.</p>
<h2 class="no-num no-toc" id="toc">Table of Contents</h2>
<!--toc-->
<h2>Introduction</h2>
<p>This document formally specifies the core features of the CSS Object Model (CSSOM). Other documents in the CSSOM family of specifications
as well as other CSS related specifications define extensions to these core features.</p>
<p>The core features of the CSSOM are oriented towards providing basic capabilities to author-defined scripts to permit access to
and manipulation of style related state information and processes.</p>
<p>The features defined below are fundamentally based on prior specifications of the W3C DOM Working Group, primarily
<span data-anolis-ref class=informative>DOM2STYLE</span>. The purposes of the present document are (1) to improve on that prior work by providing
more technical specificity (so as to improve testability and interoperability), (2) to deprecate or remove certain less-widely implemented
features no longer considered to be essential in this context, and (3) to newly specify certain extensions that have been
or expected to be widely implemented.</p>
<!--<p>A full list of the changes to API signatures can be found in <a href="#changes-from-dom-2-style"><cite>Changes from DOM-2 Style</cite></a>.</p>-->
<h2>Conformance</h2>
<p>All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
Everything else in this specification is normative.
<p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
NOT",--> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in the normative parts of this document are to be
interpreted as described in RFC2119. For readability, these words do
not appear in all uppercase letters in this specification.
<span data-anolis-ref>RFC2119</span>
<p>Requirements phrased in the imperative as part of algorithms
(such as "strip any leading space characters" or "return false and
terminate these steps") are to be interpreted with the meaning of the
key word ("must", "should", "may", etc) used in introducing the
algorithm.
<p>Conformance requirements phrased as algorithms or specific steps
may be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this
specification are intended to be easy to follow, and not intended to
be performant.)
<p id="hardwareLimitations">User agents may impose
implementation-specific limits on otherwise unconstrained inputs,
e.g. to prevent denial of service attacks, to guard against running
out of memory, or to work around platform-specific limitations. <!--fingerprint-->
<p>When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that
e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.
<p>Unless otherwise stated, string comparisons are done in a
<span data-anolis-spec=dom>case-sensitive</span> manner.
<h2>Terminology</h2>
<p>This specification employs certain terminology from the following documents:
<cite>DOM</cite>,
<cite>HTML</cite>,
<cite>CSS Syntax</cite>,
<cite>Encoding</cite>,
<cite>URL</cite>,
<cite>Fetch</cite>,
<cite>Associating Style Sheets with XML documents</cite>
and
<cite>XML</cite>.
<span data-anolis-ref>DOM</span>
<span data-anolis-ref>HTML</span>
<span data-anolis-ref>CSSSYNTAX</span>
<span data-anolis-ref>ENCODING</span>
<span data-anolis-ref>URL</span>
<span data-anolis-ref>FETCH</span>
<span data-anolis-ref>XMLSS</span>
<span data-anolis-ref>XML</span>
<p>When this specification talks about object
<code title><var>A</var></code> where <code title><var>A</var></code> is actually an interface, it generally means an object implementing interface
<code title><var>A</var></code>.</p>
<p>The terms <dfn>whitespace</dfn> and <dfn>ignored</dfn> are defined in CSS. <span data-anolis-ref>CSS</span>
<p>The terms <dfn>cascaded value</dfn>, <dfn>computed value</dfn> and <dfn>used value</dfn> are defined in CSS Cascade and Inheritance.
<span data-anolis-ref>CSSCASCADE</span>
<p>The terms <dfn>simple selector</dfn>, <dfn>sequence of simple selectors</dfn>, <dfn>universal selector</dfn> and <dfn>group of selectors</dfn> are defined in
Selectors. <span data-anolis-ref>SELECTORS</span>
<p>The terms <dfn>namespace prefix</dfn> and <dfn>default namespace</dfn> are defined in CSS Namespaces Module. <span data-anolis-ref>CSSNAMESPACES</span>
<p>The term <dfn>list of CSS page selectors</dfn> refers to the comma-separated list of page selectors, as defined in CSS Paged Media Module.
<span data-anolis-ref>CSSPAGE</span>
<p>The terms <dfn>set</dfn> and <dfn>unset</dfn> to refer to the true and
false values of binary flags or variables, respectively. These terms are also used as verbs in which case they refer to
mutating some value to make it true or false, respectively.</p>
<p>The term <dfn>supported styling language</dfn> refers to CSS.
<p class=note>If another styling language becomes supported in user agents, this specification is expected to be updated as necessary.
<p>The term <dfn>supported CSS property</dfn> refers to a CSS property that the user agent implements, and that is defined to be a case-insensitive property in
the CSS specification. A <span>supported CSS property</span> must be in its lowercase form for the purpose of comparisons this specification.
<p>The term <dfn>author-defined CSS property</dfn> refers to <code title>var-*</code> properties as defined in CSS Custom Properties for Cascading Variables,
and are case-sensitive. <span data-anolis-ref>CSSVARIABLES</span>
<p>The terms <dfn>::before pseudo-element</dfn> and <dfn>::after pseudo-element</dfn> refer to the :before and :after pseudo-elements in CSS, except in this
specification the pseudo-elements are assumed to exist for all elements even if no box is generated for them. <span data-anolis-ref>CSS</span>
<p>The term <dfn>environment encoding</dfn> is defined in CSS Syntax Module. <span data-anolis-ref>CSSSYNTAX</span>
<p>The algorithm <dfn>get an encoding</dfn> is defined in the Encoding standard. <span data-anolis-ref>ENCODING</span>
<p>The term <dfn>document's character encoding</dfn> is defined in DOM. <span data-anolis-ref>DOM</span>
<h3>Common Serializing Idioms</h3>
<p>To <dfn>escape a character</dfn> means to create a string of
"<code title>\</code>" (U+005C), followed by the character.</p>
<p>To <dfn>escape a character as code point</dfn> means to create a
string of "<code title>\</code>" (U+005C), followed by the Unicode code point as
the smallest possible number of hexadecimal digits in the range 0-9 a-f
(U+0030 to U+0039 and U+0061 to U+0066) to represent the code point in
base 16, followed by a single SPACE (U+0020).</p>
<p>To <dfn>serialize an identifier</dfn> means to create a string represented
by the concatenation of, for each character of the identifier:</p>
<ul>
<li>If the character is NULL (U+0000), then <span data-anolis-spec=dom title=concept-throw>throw</span> an
<code data-anolis-spec=dom>InvalidCharacterError</code> exception and terminate these steps.</li>
<li>If the character is in the range [\1-\1f] (U+0001 to U+001F) or
[\7f-\9f] (U+007F to U+009F), then the character
<span title="escape a character as code point">escaped as code point</span>.</li>
<li>If the character is the first character and is in the range [0-9]
(U+0030 to U+0039), then the character
<span title="escape a character as code point">escaped as code point</span>.</li>
<li>If the character is the second character and is in the range [0-9]
(U+0030 to U+0039) and the first character is a "<code title>-</code>"
(U+002D), then the character
<span title="escape a character as code point">escaped as code point</span>.</li>
<li>If the character is the second character and is "<code title>-</code>"
(U+002D) and the first character is "<code title>-</code>" as well, then the
<span title="escape a character">escaped</span> character.</li>
<li>If the character is not handled by one of the above rules and is
greater than or equal to U+0080, is "<code title>-</code>" (U+002D) or
"<code title>_</code>" (U+005F), or is in one of the ranges [0-9] (U+0030 to
U+0039), [A-Z] (U+0041 to U+005A), or [a-z] (U+0061 to U+007A), then the character
itself.</li>
<li>Otherwise, the <span title="escape a character">escaped</span>
character.</li>
</ul>
<p>To <dfn>serialize a string</dfn> means to create a string represented
by '"' (U+0022), followed by the result of applying the rules
below to each character of the given string, followed by
'"' (U+0022):</p>
<ul>
<li>If the character is NULL (U+0000), then <span data-anolis-spec=dom title=concept-throw>throw</span> an
<code data-anolis-spec=dom>InvalidCharacterError</code> exception and terminate these steps.</li>
<li>If the character is in the range [\1-\1f] (U+0001 to U+001F) or [\7f-\9f] (U+007F to
U+009F), the character <span title="escape a character as code point">escaped as code point</span>.</li>
<li>If the character is '"' (U+0022) or "<code title>\</code>"
(U+005C), the <span title="escape a character">escaped</span> character.</li>
<li>Otherwise, the character itself.</li>
</ul>
<p class="note">"<code title>'</code>" (U+0027) is not escaped because strings
are always serialized with '"' (U+0022).</p>
<p>To <dfn>serialize a URL</dfn> means to create a string represented by
"<code title>url(</code>", followed by the
<span title="serialize a string">string escaped</span> value of the given
string, followed by "<code title>)</code>".</p>
<p>To <dfn>serialize a comma-separated list</dfn> concatenate all items of
the list in list order while separating them by "<code title>, </code>", i.e.,
COMMA (U+002C) followed by a single SPACE (U+0020).</p>
<p>To <dfn>serialize a whitespace-separated list</dfn> concatenate all
items of the list in list order while separating them by "<code title> </code>", i.e.,
a single SPACE (U+0020).</p>
<p class="note">When serializing a list according to the above rules,
extraneous whitespace is not inserted prior to the first item or subsequent to
the last item. Unless otherwise specified, an empty list is serialized as the
empty string.</p>
<h2>Media Queries</h2>
<p>Media queries are defined by the Media Queries specification. This
section defines various concepts around media queries, including their API
and serialization form.</p>
<!-- XXX ref -->
<h3>Parsing Media Queries</h3>
<p>To
<dfn>parse a media query list</dfn> for a
given string <var>s</var> into a media query list is defined in
the Media Queries specification. Return the list of one or more media
queries that the algorithm defined there gives.</p> <!-- XXX ref -->
<p class="note">A media query that ends up being "ignored" will turn
into "<code title>not all</code>".</p>
<p>To
<dfn>parse a media query</dfn> for a given string
<var>s</var> means to follow the
<span>parse a media query list</span> steps and return null if more
than one media query is returned or a media query if a
single media query is returned.</p>
<p class="note">Again, a media query that ends up being "ignored" will
turn into "<code title>not all</code>".</p>
<h3>Serializing Media Queries</h3>
<p>To
<dfn>serialize a media query list</dfn>
run these steps:</p>
<ol>
<li><p>If the media query list is empty return the empty string and
terminate these steps.</p></li>
<li><p><span title="serialize a media query">Serialize</span> each media query in the list of media queries, in the same order as they appear in the list of
media queries, and then <span title="serialize a comma-separated list">serialize</span> the list.</p></li>
</ol>
<p>To
<dfn>serialize a media query</dfn> let
<var>s</var> be the empty string, run the steps below, and
finally return <var>s</var>:</p>
<ol>
<li><p>If the media query is negated append "<code title>not</code>", followed
by a single SPACE (U+0020), to <var>s</var>.</p></li>
<li><p>Let <var>type</var> be the media type of the media query,
<span title="serialize an identifier">escaped</span> and
<span data-anolis-spec=dom>converted to ASCII lowercase</span>.</p></li>
<li><p>If the media query does not contain media features append
<var>type</var>, to <var>s</var>,
then return <var>s</var> and terminate this algorithm.</p></li>
<li><p>If <var>type</var> is not "<code title>all</code>" or if the
media query is negated append <var>type</var>, followed by a
single SPACE (U+0020), followed by "<code title>and</code>", followed by a single SPACE
(U+0020), to <var>s</var>.</p></li>
<li><p>Sort the media features in lexicographical order.</p></li>
<li>
<p>Then, for each media feature:</p>
<ol>
<li><p>Append a "<code title>(</code>" (U+0028), followed by the media feature
name, <span data-anolis-spec=dom>converted to ASCII lowercase</span>,
to <var>s</var>.</p></li>
<li><p>If a value is given append a "<code title>:</code>" (U+003A), followed
by a single SPACE (U+0020), followed by the
<span title="serialize a media feature value">serialized media feature value</span>,
to <var>s</var>.</p></li>
<li><p>Append a "<code title>)</code>" (U+0029) to
<var>s</var>.</p></li>
<li><p>If this is not the last media feature append a single SPACE (U+0020),
followed by "<code title>and</code>", followed by a single SPACE (U+0020), to
<var>s</var>.</p></li>
</ol>
</li>
</ol>
<div class="example">
<p>Here are some examples of input (first column) and output (second
column):</p>
<table class="complex data">
<thead>
<tr><th>Input<th>Output
<tbody>
<tr>
<td><pre>not screen and (min-WIDTH:5px) AND (max-width:40px)</pre>
<td><pre>not screen and (max-width: 40px) and (min-width: 5px)</pre>
<tr>
<td><pre>all and (color) and (color)</pre>
<td><pre>(color)</pre>
</table>
</div>
<h4>Serializing Media Feature Values</h4>
<p class="issue">This should probably be done in terms of mapping it to
serializing CSS values as media features are defined in terms of CSS
values after all.</p>
<p>To <dfn>serialize a media feature value</dfn>
named <var>v</var> locate <var>v</var> in the first
column of the table below and use the serialization format described in
the second column:</p>
<table class="complex data">
<thead>
<tr>
<th>Media Feature
<th>Serialization
<tbody>
<tr>
<td>'width'
<td>...
<tr>
<td>'height'
<td>...
<tr>
<td>'device-width'
<td>...
<tr>
<td>'device-height'
<td>...
<tr>
<td>'orientation'
<td>
<p>If the value is 'portrait': "<code title>portrait</code>".</p>
<p>If the value is 'landscape': "<code title>landscape</code>".</p>
<tr>
<td>'aspect-ratio'
<td>...
<tr>
<td>'device-aspect-ratio'
<td>...
<tr>
<td>'color'
<td>...
<tr>
<td>'color-index'
<td>...
<tr>
<td>'monochrome'
<td>...
<tr>
<td>'resolution'
<td>...
<tr>
<td>'scan'
<td>
<p>If the value is 'progressive': "<code title>progressive</code>".</p>
<p>If the value is 'interlace': "<code title>interlace</code>".</p>
<tr>
<td>'grid'
<td>...
</table>
<p>Other specifications can extend this table and vendor-prefixed media
features can have custom serialization formats as well.</p>
<h3>Comparing Media Queries</h3>
<p>To
<dfn>compare media queries</dfn>
<var>m1</var> and <var>m2</var> means to
<span title="serialize a media query">serialize</span> them both and
return true if they are a
<span data-anolis-spec=dom>case-sensitive</span> match and false if they
are not.</p>
<h3>The <code title>MediaList</code> Interface</h3>
<!--
//
// All members defined since DOM-2 Style. The only differences are:
//
// 1. addition of stringifier qualifier on mediaText
// 2. addition of getter qualifier on item
// 3. removal of raises(DOMException) from {append,delete}Medium
//
-->
<p>An object that implements the <code>MediaList</code> interface has an associated <dfn>collection of media queries</dfn>.</p>
<pre class=idl>[ArrayClass]
interface <dfn>MediaList</dfn> {
[TreatNullAs=EmptyString] stringifier attribute DOMString <span title=dom-MediaList-mediaText>mediaText</span>;
readonly attribute unsigned long <span title=dom-MediaList-length>length</span>;
getter DOMString? <span title=dom-MediaList-item>item</span>(unsigned long index);
void <span title=dom-MediaList-appendMedium>appendMedium</span>(DOMString medium);
void <span title=dom-MediaList-deleteMedium>deleteMedium</span>(DOMString medium);
};</pre>
<p>The object's <span data-anolis-spec=webidl>supported property indices</span> are the numbers in the range zero to one less than the number of media queries
in the <span>collection of media queries</span> represented by the collection. If there are no such media queries, then there are no
<span data-anolis-spec=webidl>supported property indices</span>.
<p>To <dfn>create a <code>MediaList</code> object</dfn> with a string <var>text</var>, run the following steps:
<ol>
<li><p>Create a new <code>MediaList</code> object.</p></li>
<li><p>Set its <code title='dom-MediaList-mediaText'>mediaText</code> attribute to <var>text</var>.</p></li>
<li><p>Return the newly created <code>MediaList</code> object.</p></li>
</ol>
<p>The <dfn title=dom-MediaList-mediaText><code>mediaText</code></dfn> attribute, on getting, must return a
<span title='serialize a media query list'>serialization</span> of the <span>collection of media queries</span>.</p>
<p>Setting the <code title=dom-MediaList-mediaText>mediaText</code> attribute must run these steps:
<ol>
<li><p>Empty the <span>collection of media queries</span>.</p></li>
<li><p>If the given value is the empty string terminate these steps.</p></li>
<li><p>Append all the media queries as a result of <span title='parse a media query list'>parsing</span> the given
value to the <span>collection of media queries</span>.</p></li>
</ol>
<p>The <dfn title=dom-MediaList-item><code>item(<var>index</var>)</code></dfn> method must return the media query in the <span>collection of media
queries</span> given by <var>index</var>, or null, if <var>index</var> is greater than or equal to the number of media queries in the
<span>collection of media queries</span>.</p>
<p>The <dfn title=dom-MediaList-length><code>length</code></dfn> attribute must return the number of media queries in the <span>collection of media
queries</span>.</p>
<p>The <dfn title=dom-MediaList-appendMedium><code>appendMedium(<var>medium</var>)</code></dfn> method must run these steps:</p>
<ol>
<li><p>Let <var>m</var> be the result of <span title='parse a media query'>parsing</span> the given value.</p></li>
<li><p>If <var>m</var> is null terminate these steps.</p></li>
<li><p>If <span title='compare media queries'>comparing</span> <var>m</var> with any of the media queries in the
<span>collection of media queries</span> returns true terminate these steps.</p></li>
<li><p>Append <var>m</var> to the <span>collection of media queries</span>.</p></li>
</ol>
<p>The <dfn title=dom-MediaList-deleteMedium><code>deleteMedium(<var>medium</var>)</code></dfn> method must run these steps:</p>
<ol>
<li><p>Let <var>m</var> be the result of <span title='parse a media query'>parsing</span> the given value.</p></li>
<li><p>If <var>m</var> is null terminate these steps.</p></li>
<li><p>Remove any media query from the <span>collection of media queries</span> for which
<span title='compare media queries'>comparing</span> the media query with <var>m</var> returns true.</p></li>
</ol>
<h2>Selectors</h2>
<p>Selectors are defined in the Selectors specification. This section
mainly defines how to serialize them.</p> <!-- XXX ref -->
<!-- XXX ref universal selector etc? some are in <span> some not -->
<h3>Parsing Selectors</h3>
<p>To
<dfn>parse a group of selectors</dfn>
means to parse the value using the <code title>selectors_group</code>
production defined in the Selectors specification and return either a
group of selectors if parsing did not fail or null if parsing did
fail.</p> <!-- XXX ref -->
<h3>Serializing Selectors</h3>
<!-- http://dump.testsuite.org/2009/cssom/serializing-selectors.htm -->
<p>To
<dfn>serialize a group of selectors</dfn>
<span title="serialize a selector">serialize</span> each selector in the
group of selectors and then
<span title="serialize a comma-separated list">serialize</span> the
group.</p>
<p>To <dfn>serialize a selector</dfn> let
<var>s</var> be the empty string, run the steps below for each
part of the chain of the selector, and finally return
<var>s</var>:</p>
<ol>
<li><p>If there is only one <span>simple selector</span> in the
<span>sequence of simple selectors</span> which is a
<span>universal selector</span>, append the result of
<span title="serialize a simple selector">serializing</span> the
<span>universal selector</span> to <var>s</var>.</p></li>
<li><p>Otherwise, for each <span>simple selector</span> in the
<span>sequence of simple selectors</span> that is not a
universal selector of which the
<span>namespace prefix</span> maps to a namespace that is not the
<span>default namespace</span>
<span title="serialize a simple selector">serialize</span> the
<span>simple selector</span> and append the result to
<var>s</var>.</p></li>
<li><p>If this is not the last part of the chain of the selector append a
single SPACE (U+0020), followed by the combinator
"<code title>></code>",
"<code title>+</code>", or
"<code title>~</code>"
as appropriate, followed by another single SPACE (U+0020) if the combinator was
not whitespace, to <var>s</var>.</p></li>
<li><p>If this is the last part of the chain of the selector and there is
a pseudo-element, append "<code title>::</code>" followed by the name of the
pseudo-element, to <var>s</var>.</p></li>
</ol>
<p>To
<dfn>serialize a simple selector</dfn>
let <var>s</var> be the empty string, run the steps below, and
finally return <var>s</var>:</p>
<dl class="switch">
<dt>type selector</dt>
<dt>universal selector</dt>
<dd>
<ol>
<li><p>If the <span>namespace prefix</span> maps to a namespace that is
not the <span>default namespace</span> and is not the
null namespace (not in a namespace) append the
<span title="serialize an identifier">escaped</span>
<span>namespace prefix</span>, followed by a "<code title>|</code>" (U+007C)
to <var>s</var>.</p></li>
<li><p>If the <span>namespace prefix</span> maps to a namespace that is
the null namespace (not in a namespace) append
"<code title>|</code>" (U+007C) to <var>s</var>.</p></li>
<!-- This includes |* -->
<li><p>If this is a type selector append the
<span title="serialize an identifier">escaped</span> element name to
<var>s</var>.</p></li>
<li><p>If this is a universal selector append "<code title>*</code>" (U+002A)
to <var>s</var>.</p></li>
</ol>
</dd>
<dt>attribute selector</dt>
<dd>
<ol>
<li><p>Append "<code title>[</code>" (U+005B) to
<var>s</var>.</p></li>
<li><p>If the <span>namespace prefix</span> maps to a namespace that is
not the null namespace (not in a namespace) append the
<span title="serialize an identifier">escaped</span>
<span>namespace prefix</span>, followed by a "<code title>|</code>" (U+007C)
to <var>s</var>.</p></li>
<li><p>Append the <span title="serialize an identifier">escaped</span>
attribute name to <var>s</var>.</p></li>
<li><p>If there is an attribute value specified, append
"<code title>=</code>",
"<code title>~=</code>",
"<code title>|=</code>",
"<code title>^=</code>",
"<code title>$=</code>", or
"<code title>*=</code>"
as appropriate (depending on the type of attribute selector), followed
by the <span title="serialize a string">string escaped</span>
attribute value, to <var>s</var>.</p></li>
<li><p>Append "<code title>]</code>" (U+005D) to
<var>s</var>.</p></li>
</ol>
</dd>
<dt>class selector</dt>
<dd><p>Append a "<code title>.</code>" (U+002E), followed by the
<span title="serialize an identifier">escaped</span> class name to
<var>s</var>.</p></dd>
<dt>ID selector</dt>
<dd><p>Append a "<code title>#</code>" (U+0023), followed by the
<span title="serialize an identifier">escaped</span> ID to
<var>s</var>.</p></dd>
<dt>pseudo-class</dt>
<dd>
<p>If the pseudo-class does not accept arguments append
"<code title>:</code>" (U+003A), followed by the name of the pseudo-class, to
<var>s</var>.</p>
<p>Otherwise, append "<code title>:</code>" (U+003A), followed by the name of
the pseudo-class, followed by "<code title>(</code>" (U+0028), followed by the
value of the pseudo-class argument determined as per below, followed by
"<code title>)</code>" (U+0029), to <var>s</var>.</p>
<dl class="switch">
<dt><code title>:lang()</code></dt>
<dd><p>The <span title="serialize an identifier">escaped</span>
value.</p></dd>
<dt><code title>:nth-child()</code></dt>
<dt><code title>:nth-last-child()</code></dt>
<dt><code title>:nth-of-type()</code></dt>
<dt><code title>:nth-last-of-type()</code></dt>
<dd><p>The result of serializing the value using the rules for <span data-anolis-spec=csssyntax>serializing &lt;an+b></span>.
<dt><code title>:not()</code></dt>
<dd><p>The result of serializing the value using the rules for
<span title="serialize a group of selectors">serializing a group of selectors</span>.</p></dd>
</dl>
</dd>
</dl>
<h2>CSS</h2>
<h3>CSS Style Sheets</h3>
<p>A <dfn>CSS style sheet</dfn> is an abstract concept that
represents a style sheet as defined by the CSS specification. In the CSSOM a
<span>CSS style sheet</span> is represented as a <code>CSSStyleSheet</code> object. A
<span>CSS style sheet</span> has a number of associated state items:</p>
<dl>
<dt><dfn title=concept-css-style-sheet-type>type</dfn></dt>
<dd><p>The literal string "<code title>text/css</code>".</p></dd>
<dt><dfn title=concept-css-style-sheet-location>location</dfn></dt>
<dd><p>Specified when created. The <span data-anolis-spec=url title=concept-absolute-url>absolute URL</span> of the first request of the
<span>CSS style sheet</span> or null if the <span>CSS style sheet</span> was
embedded. Does not change during the lifetime of the <span>CSS style sheet</span>.</p></dd>
<dt><dfn title=concept-css-style-sheet-parent-css-style-sheet>parent CSS style sheet</dfn></dt>
<dd><p>Specified when created. The <span>CSS style sheet</span> that is the parent of the
<span>CSS style sheet</span> or null if there is no associated parent.</p></dd>
<dt><dfn title=concept-css-style-sheet-owner-node>owner node</dfn></dt>
<dd><p>Specified when created. The DOM node associated with the <span>CSS style sheet</span> or
null if there is no associated DOM node.</p></dd>
<dt><dfn title=concept-css-style-sheet-owner-css-rule>owner CSS rule</dfn></dt>
<dd><p>Specified when created. The <span>CSS rule</span> in the <span title=concept-css-style-sheet-parent-css-style-sheet>parent CSS style sheet</span>
that caused the inclusion of the <span>CSS style sheet</span> or null if
there is no associated rule.</p></dd>
<dt><dfn title=concept-css-style-sheet-media>media</dfn></dt>
<dd>
<p>Specified when created. The <code>MediaList</code> object associated with the
<span>CSS style sheet</span>.</p>
<p>If this property is specified to a string, the <span title=concept-css-style-sheet-media>media</span> must be set to the return value of invoking
<span>create a <code>MediaList</code> object</span> steps for that string.</p>
<p>If this property is specified to an attribute of the <span title=concept-css-style-sheet-owner-node>owner node</span>, the
<span title=concept-css-style-sheet-media>media</span> must be set to the return value of invoking <span>create a <code>MediaList</code> object</span> steps
for the value of that attribute. Whenever the attribute is set, changed or removed, the <span title=concept-css-style-sheet-media>media</span>'s
<code title=dom-MediaList-mediaText>mediaText</code> attribute must be set to the new value of the attribute, or to null if the attribute is absent.
<p class=note>Changing the <span title=concept-css-style-sheet-media>media</span>'s <code title=dom-MediaList-mediaText>mediaText</code> attribute does not
change the corresponding attribute on the <span title=concept-css-style-sheet-owner-node>owner node</span>.
</dd>
<dt><dfn title=concept-css-style-sheet-title>title</dfn></dt>
<dd>
<p>Specified when created. The title of the <span>CSS style sheet</span>, which can be the empty string.</p>
<div class="example">
<p>In the following, the <span title=concept-css-style-sheet-title>title</span> is non-empty
for the first style sheet, but is empty for the second and third style sheets.</p>
<pre>&lt;style title="papaya whip">
body { background: #ffefd5; }
&lt;/style></pre>
<pre>&lt;style title="">
body { background: orange; }
&lt;/style></pre>
<pre>&lt;style>
body { background: brown; }
&lt;/style></pre>
</div>
<p>If this property is specified to an attribute of the <span title=concept-css-style-sheet-owner-node>owner node</span>, the
<span title=concept-css-style-sheet-title>title</span> must be set to the value of that attribute. Whenever the attribute is set, changed or removed, the
<span title=concept-css-style-sheet-title>title</span> must be set to the new value of the attribute, or to the empty string if th 788C e attribute is absent.
</dd>
<dt><dfn title=concept-css-style-sheet-alternate-flag>alternate flag</dfn></dt>
<dd>
<p>Specified when created. Either set or unset. Unset by default.</p>
<div class="example">
<p>The following <span title="CSS style sheet">CSS style sheets</span> have
their <span title=concept-css-style-sheet-alternate-flag>alternate flag</span> set:</p>
<pre>&lt;?xml-stylesheet alternate="yes" title="x" href="data:text/css,&hellip;"?></pre>
<pre>&lt;link rel="alternate stylesheet" title="x" href="data:text/css,&hellip;"></pre>
</div>
</dd>
<dt><dfn title=concept-css-style-sheet-disabled-flag>disabled flag</dfn></dt>
<dd>
<p>Either set or unset. Unset by default.</p>
<p class="note">Even when unset it does not necessarily mean that the
<span>CSS style sheet</span> is actually used for rendering.</p>
</dd>
<dt><dfn title=concept-css-style-sheet-css-rules>CSS rules</dfn></dt>
<dd><p>The <span title="CSS rule">CSS rules</span> associated with the
<span>CSS style sheet</span>.</p></dd>
<dt><dfn title=concept-css-style-sheet-origin-clean-flag>origin-clean flag</dfn>
<dd><p>Specified when created. Either set or unset. If it is set, the API allows reading and modifying of the <span title=concept-css-style-sheet-css-rules>CSS
rules</span>.
</dl>
<h4>The <code title>StyleSheet</code> Interface</h4>
<!--
//
// All members defined since DOM-2 Style. Only difference
// is addition of [PutForwards=mediaText], which is presently
// not defined in CSSOM draft.
//
-->
<p>The <code>StyleSheet</code> interface represents an abstract, base style sheet.</p>
<pre class=idl>interface <dfn>StyleSheet</dfn> {
readonly attribute DOMString <span title=dom-StyleSheet-type>type</span>;
readonly attribute DOMString? <span title=dom-StyleSheet-href>href</span>;
readonly attribute (<span data-anolis-spec=dom>Element</span> or <span data-anolis-spec=dom>ProcessingInstruction</span>)? <!--
--><span title=dom-StyleSheet-ownerNode>ownerNode</span>;
readonly attribute <span>StyleSheet</span>? <span title=dom-StyleSheet-parentStyleSheet>parentStyleSheet</span>;
readonly attribute DOMString? <span title=dom-StyleSheet-title>title</span>;
[SameObject, PutForwards=<span title=dom-MediaList-mediaText>mediaText</span>] readonly attribute <span>MediaList</span> <!--
--><span title=dom-StyleSheet-media>media</span>;
attribute boolean <span title=dom-StyleSheet-disabled>disabled</span>;
};</pre>
<p>The <dfn title=dom-StyleSheet-type><code>type</code></dfn> attribute must return the <span title=concept-css-style-sheet-type>type</span>.</p>
<p>The <dfn title=dom-StyleSheet-href><code>href</code></dfn> attribute must return the <span title=concept-css-style-sheet-location>location</span>.</p>
<p>The <dfn title=dom-StyleSheet-ownerNode><code>ownerNode</code></dfn> attribute must return the <span title=concept-css-style-sheet-owner-node>owner
node</span>.</p>
<p>The <dfn title=dom-StyleSheet-parentStyleSheet><code>parentStyleSheet</code></dfn> attribute must return the
<span title=concept-css-style-sheet-parent-css-style-sheet>parent CSS style sheet</span>.</p>
<p>The <dfn title=dom-StyleSheet-title><code>title</code></dfn> attribute must return the <span title=concept-css-style-sheet-title>title</span> or null if
<span title=concept-css-style-sheet-title>title</span> is the empty string.</p>
<p>The <dfn title=dom-StyleSheet-media><code>media</code></dfn> attribute must return the <span title=concept-css-style-sheet-media>media</span>.</p>
<p>The <dfn title=dom-StyleSheet-disabled><code>disabled</code></dfn> attribute, on getting, must return true if the
<span title=concept-css-style-sheet-disabled-flag>disabled flag</span>
is set, or false otherwise. On setting, the <code title=dom-StyleSheet-disabled>disabled</code> attribute must set the
<span title=concept-css-style-sheet-disabled-flag>disabled flag</span> if the new value is true, or unset the
<span title=concept-css-style-sheet-disabled-flag>disabled flag</span> otherwise.</p>
<h4>The <code title>CSSStyleSheet</code> Interface</h4>
<!--
//
// All members defined since DOM-2 Style. The only differences are:
//
// 1. removal of raises(DOMException) on {insert,delete}Rule operations.
//
-->
<p>The <code>CSSStyleSheet</code> interface represents a <span>CSS style sheet</span>.</p>
<pre class=idl>interface <dfn>CSSStyleSheet</dfn> : <span>StyleSheet</span> {
readonly attribute <span>CSSRule</span>? <span title=dom-CSSStyleSheet-ownerRule>ownerRule</span>;
[SameObject] readonly attribute <span>CSSRuleList</span> <span title=dom-CSSStyleSheet-cssRules>cssRules</span>;
unsigned long <span title=dom-CSSStyleSheet-insertRule>insertRule</span>(DOMString rule, unsigned long index);
void <span title=dom-CSSStyleSheet-deleteRule>deleteRule</span>(unsigned long index);
};</pre>
<p>The <dfn title=dom-CSSStyleSheet-ownerRule><code>ownerRule</code></dfn> attribute must return the <span title=concept-css-style-sheet-owner-css-rule>owner
CSS rule</span>. If a value other than null is ever returned, then that same value must always be returned on each get access.</p>
<p>The <dfn title=dom-CSSStyleSheet-cssRules><code>cssRules</code></dfn> attribute must follow these steps:
<ol>
<li><p>If the <span title=concept-css-style-sheet-origin-clean-flag>origin-clean flag</span> is unset,
<span title=concept-throw data-anolis-spec=dom>throw</span> a <code data-anolis-spec=dom>SecurityError</code> exceptio 9334 n.
<li><p>Return a read-only, live <code>CSSRuleList</code> object representing
the <span title=concept-css-style-sheet-css-rules>CSS rules</span>.</p>
<p class='note'>Even though the returned <code>CSSRuleList</code> object is read-only (from the perspective of
client-authored script), it can nevertheless change over time due to its liveness status. For example, invoking
the <code title=dom-CSSStyleSheet-insertRule>insertRule()</code> or <code title=dom-CSSStyleSheet-deleteRule>deleteRule()</code> methods can result in
mutations reflected in the returned object.</p>
</ol>
<p>The <dfn title=dom-CSSStyleSheet-insertRule><code>insertRule(<var>rule</var>, <var>index</var>)</code></dfn> method must run the following steps:
<ol>
<li><p>If the <span title=concept-css-style-sheet-origin-clean-flag>origin-clean flag</span> is unset,
<span title=concept-throw data-anolis-spec=dom>throw</span> a <code data-anolis-spec=dom>SecurityError</code> exception.
<li><p>Return the result of invoking <span>insert a CSS rule</span> <var>rule</var> in the <span title=concept-css-style-sheet-css-rules>CSS rules</span>
at <var>index</var>.
</ol>
<p>The <dfn title=dom-CSSStyleSheet-deleteRule><code>deleteRule(<var>index</var>)</code></dfn> method must run the following steps:
<ol>
<li><p>If the <span title=concept-css-style-sheet-origin-clean-flag>origin-clean flag</span> is unset,
<span title=concept-throw data-anolis-spec=dom>throw</span> a <code data-anolis-spec=dom>SecurityError</code> exception.
<li><p><span>Remove a CSS rule</span> in the <span title=concept-css-style-sheet-css-rules>CSS rules</span> at <var>index</var>.
</ol>
<h3>CSS Style Sheet Collections</h3>
<p>Below various new concepts are defined that are associated with each
<code data-anolis-spec=dom>Document</code> object.</p>
<p>Each <code data-anolis-spec=dom>Document</code> has an associated list of zero or more
<span title="CSS style sheet">CSS style sheets</span>, named the
<dfn>document CSS style sheets</dfn>. This is
an ordered list that contains all
<span title="CSS style sheet">CSS style sheets</span> associated with the
<code data-anolis-spec=dom>Document</code>, in
<span data-anolis-spec=dom title=concept-tree-order>tree order</span>, with
<span title="CSS style sheet">CSS style sheets</span> created from HTTP
<code title>Link</code> headers first, if any, in header
order.</p>
<p>To <dfn>create a CSS style sheet</dfn>, run these
steps:</p>
<ol>
<li><p>Create a new <span>CSS style sheet</span> object and set its
properties as specified.</p></li>
<li>
<p>Then run the <span>add a CSS style sheet</span> steps for the newly created <span>CSS style sheet</span>.
<p class=warning>If the <span title=concept-css-style-sheet-origin-clean-flag>origin-clean flag</span> is unset, this can expose information from the user's
intranet.
</ol>
<p>To <dfn>add a CSS style sheet</dfn>, run these
steps:</p>
<ol>
<li><p>Add the <span>CSS style sheet</span> to the list of
<span>document CSS style sheets</span> at the appropriate location. The
remainder of these steps deal with the
<span title=concept-css-style-sheet-disabled-flag>disabled flag</span>.</p></li>
<li><p>If the <span title=concept-css-style-sheet-disabled-flag>disabled flag</span> is set, terminate
these steps.</p></li>
<li><p>If the <span title=concept-css-style-sheet-title>title</span> is not the empty string, the
<span title=concept-css-style-sheet-alternate-flag>alternate flag</span> is unset, and
<span>preferred CSS style sheet set name</span> is the empty string
<span>change the preferred CSS style sheet set name</span> to the
<span title=concept-css-style-sheet-title>title</span>.</p></li>
<li>
<p>If any of the following is true unset the
<span title=concept-css-style-sheet-disabled-flag>disabled flag</span> and terminate these steps:
<ul>
<li><p>The <span title=concept-css-style-sheet-title>title</span> is the empty string.</p></li>
<li><p>The <span>last CSS style sheet set name</span> is null and the
<span title=concept-css-style-sheet-title>title</span> is a
<span data-anolis-spec=dom>case-sensitive</span> match
for the <span>preferred CSS style sheet set name</span>.</p></li>
<li><p>The <span title=concept-css-style-sheet-title>title</span> is a
<span data-anolis-spec=dom>case-sensitive</span> match for the
<span>last CSS style sheet set name</span>.</p></li>
</ul>
</li>
<li><p>Set the <span title=concept-css-style-sheet-disabled-flag>disabled flag</span>.</li>
</ol>
<p>To <dfn>remove a CSS style sheet</dfn>, run these steps:</p>
<ol>
View remainder of file in raw view