8000 csswg-drafts/cssom-view/Overview.html at aedd4281591fdc765a07e1556307399f8df4834f · w3c/csswg-drafts · GitHub
Skip to content

Overview.html

Latest commit

 

History

History
1563 lines (1247 loc) · 67.5 KB

Overview.html

File metadata and controls

1563 lines (1247 loc) · 67.5 KB
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang=en-US>
<head>
<title>CSSOM View Module</title>
<style type="text/css">
pre.idl { border:solid thin; background:#eee; color:#000; padding:0.5em }
pre.idl :link, pre.idl :visited { color:inherit; background:transparent }
dfn { font-weight:bold; font-style:normal }
div.example { margin-left:1em; padding-left:1em; border-left:double; color:#222; background:#fcfcfc }
div.example code { color:inherit }
p.note { margin-left:2em; color:green; font-style:italic; font-weight:bold }
p.note::before { content:"Note: " }
.XXX { padding:.5em; border:solid red }
.XXX::before { content:"Issue: " }
em.ct { font-weight:bold; font-style:normal }
code { color:orangered }
code :link, code :visited { color:inherit }
</style>
<link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel=stylesheet>
<body class=draft>
<div class=head> <!--begin-logo-->
<p><a href="http://www.w3.org/"><img alt=W3C height=48
src="http://www.w3.org/Icons/w3c_home" width=72></a> <!--end-logo-->
<h1 id=cssom-view-module>CSSOM View Module</h1>
<h2 class="no-num no-toc" id=w3c-doctype>Editor's Draft 25 May 2010</h2>
<dl>
<dt>This Version:
<dd><a
href="http://www.w3.org/TR/2010/ED-cssom-view-20100525/">http://www.w3.org/TR/2010/ED-cssom-view-20100525/</a>
<dt>Latest Version:
<dd><a
href="http://www.w3.org/TR/cssom-view/">http://www.w3.org/TR/cssom-view/</a>
<dt>Latest Editor Version:
<dd><a
href="http://dev.w3.org/csswg/cssom-view/">http://dev.w3.org/csswg/cssom-view/</a>
<dt>Previous Versions:
<dd><a
href="http://www.w3.org/TR/2009/WD-cssom-view-20090804/">http://www.w3.org/TR/2009/WD-cssom-view-20090804/</a>
<dd><a
href="http://www.w3.org/TR/2008/WD-cssom-view-20080222/">http://www.w3.org/TR/2008/WD-cssom-view-20080222/</a>
<dt>Editor:
<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@opera.com">annevk@opera.com</a>&gt;
</dl>
<!--begin-copyright-->
<p class=copyright><a
href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright"
rel=license>Copyright</a> &copy; 2010 <a
href="http://www.w3.org/"><acronym title="World Wide Web
Consortium">W3C</acronym></a><sup>&reg;</sup> (<a
href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute
of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym
title="European Research Consortium for Informatics and
Mathematics">ERCIM</acronym></a>, <a
href="http://www.keio.ac.jp/">Keio</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>
<!--end-copyright--></div>
<hr>
<h2 class="no-num no-toc" id=abstract>Abstract</h2>
<p>The APIs introduced by this specification provide authors with a way to
inspect and manipulate the visual view of a document. This includes
getting the position of element layout boxes, obtaining the width of the
viewport through script, and also scrolling an element.
<h2 class="no-num no-toc" id=sotd>Status of this Document</h2>
<!--begin-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=%5Bcssom-view%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
&#8220;cssom-view&#8221; in the subject, preferably like this:
&#8220;[<!---->cssom-view<!---->] <em>&hellip;summary of
comment&hellip;</em>&#8221;
<p>This document was produced by the <a href="/Style/CSS/members">CSS
Working Group</a> (part of the <a href="/Style/">Style Activity</a>).
<p>This document was produced by a group operating under the <a
href="/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent
Policy</a>. W3C maintains a <a href="/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="/Consortium/Patent-Policy-20040205/#def-essential">Essential
Claim(s)</a> must disclose the information in accordance with <a
href="/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the
W3C Patent Policy</a>.</p>
<!--end-status-->
<h2 class="no-num no-toc" id=toc>Table of Contents</h2>
<!--begin-toc-->
<ul class=toc>
<li><a href="#background"><span class=secno>1. </span>Background</a>
<li><a href="#conformance"><span class=secno>2. </span>Conformance
Criteria</a>
<ul class=toc>
<li><a href="#webidl"><span class=secno>2.1. </span>Web IDL</a>
<li><a href="#terminology"><span class=secno>2.2. </span>Terminology</a>
<li><a href="#css-pixels"><span class=secno>2.3. </span>CSS pixels</a>
</ul>
<li><a href="#dom-features"><span class=secno>3. </span>DOM Features</a>
<li><a href="#extensions-to-the-window-interface"><span class=secno>4.
</span>Extensions to the <code title="">Window</code> Interface</a>
<ul class=toc>
<li><a href="#the-stylemedia-interface"><span class=secno>4.1.
</span>The <code title="">StyleMedia</code> Interface</a>
<li><a href="#the-screen-interface"><span class=secno>4.2. </span>The
<code title="">Screen</code> Interface</a>
</ul>
<li><a href="#extensions-to-the-document-interface"><span class=secno>5.
</span>Extensions to the <code title="">Document</code> Interface</a>
<li><a href="#the-caretposition-interface"><span class=secno>6. </span>The
<code title="">CaretPosition</code> Interface</a>
<li><a href="#extensions-to-the-element-interface"><span class=secno>7.
</span>Extensions to the <code title="">Element</code> Interface</a>
<ul class=toc>
<li><a href="#the-getclientrects-and-getboundingclient"><span
class=secno>7.1. </span>The <code title="">getClientRects()</code> and
<code title="">getBoundingClientRect()</code> methods</a>
<li><a href="#scroll-attributes"><span class=secno>7.2. </span>The <code
title="">scrollTop</code>, <code title="">scrollLeft</code>, <code
title="">scrollWidth</code>, and <code title="">scrollHeight</code>
attributes</a>
<li><a href="#client-attributes"><span class=secno>7.3. </span>The <code
title="">clientTop</code>, <code title="">clientLeft</code>, <code
title="">clientWidth</code>, and <code title="">clientHeight</code>
attributes</a>
</ul>
<li><a href="#extensions-to-the-htmlelement-interface"><span
class=secno>8. </span>Extensions to the <code title="">HTMLElement</code>
Interface</a>
<ul class=toc>
<li><a href="#offset-attributes"><span class=secno>8.1. </span>The <code
title="">offsetParent</code>, <code title="">offsetTop</code>, <code
title="">offsetLeft</code>, <code title="">offsetWidth</code>, and
<code title="">offsetHeight</code> attributes</a>
</ul>
<li><a href="#extensions-to-the-range-interface"><span class=secno>9.
</span>Extensions to the <code title="">Range</code> Interface</a>
<li><a href="#extensions-to-the-mouseevent-interface"><span
class=secno>10. </span>Extensions to the <code title="">MouseEvent</code>
Interface</a>
<li><a href="#rectangles"><span class=secno>11. </span>Rectangles</a>
<ul class=toc>
<li><a href="#the-clientrectlist-interface"><span class=secno>11.1.
</span>The <code title="">ClientRectList</code> Interface</a>
<li><a href="#the-clientrect-interface"><span class=secno>11.2.
</span>The <code title="">ClientRect</code> Interface</a>
</ul>
<li class=no-num><a href="#references">References</a>
<li class=no-num><a href="#acknowledgments">Acknowledgments</a>
</ul>
<!--end-toc-->
<h2 id=background><span class=secno>1. </span>Background</h2>
<p>Many of the features defined in this specification have been supported
by browsers for a long period of time. The goal of this specification is
to define these features in such a way that they can be implemented by all
browsers in an identical way without differences between quirks, limited
quirks and no quirks mode, as defined by HTML5. [<cite><a
href="#ref-html5">HTML5</a></cite>]
<p>As well as serving as a specification for that "de facto" standard this
specification also obsoletes DOM Level 2 Views by removing the views
concept and the interfaces defined by that specification and relocating
the members of those interfaces to more appropriate places.
<p>Finally, the specification defines a couple of new features that will
hopefully be useful to Web authors. (If they are not you can bug us!)
<h2 id=conformance><span class=secno>2. </span>Conformance Criteria</h2>
<p>Everything in this specification is normative except for diagrams,
examples, notes and sections marked non-normative.</p>
<!--<p>The key word <em class="ct">must</em>, <em class="ct">must not</em>,
<em class="ct">should</em> and <em class="ct">may</em> in this document
are to be interpreted as described in RFC 2119.-->
<p>The key word <em class=ct>must</em> in this document is to be
interpreted as described in RFC 2119. [<cite><a
href="#ref-rfc2119">RFC2119</a></cite>]
<p>A conforming user agent implements all the requirements made by this
specification.
<h3 id=webidl><span class=secno>2.1. </span>Web IDL</h3>
<p>The IDL fragments in this specification <em class=ct>must</em> be
interpreted as required for conforming IDL fragments, as described in the
Web IDL specification. [<cite><a href="#ref-webidl">WebIDL</a></cite>]
<h3 id=terminology><span class=secno>2.2. </span>Terminology</h3>
<p><dfn id=document><code>Document</code></dfn> and <dfn
id=element><code>Element</code></dfn> are defined by DOM Level 3 Core.
[<cite><a href="#ref-dom3core">DOM3Core</a></cite>]
<p><dfn id=range><code>Range</code></dfn> is defined in DOM Level 2
Traversal and Range. [<cite><a href="#ref-dom2tr">DOM2TR</a></cite>]
<p><dfn id=mouseevent><code>MouseEvent</code></dfn> is defined in DOM Level
2 Events. [<cite><a href="#ref-dom2events">DOM2Events</a></cite>]
<p> <dfn id=compare-media-queries>Compare media queries</dfn>, <dfn
id=parse-a-media-query>parse a media query</dfn>, and <dfn
id=serialize-a-media-query>serialize a media query</dfn> are defined by
the CSSOM. [<cite><a href="#ref-cssom">CSSOM</a></cite>]
<p> <dfn id=html-element>HTML element</dfn>, <dfn
id=htmlelement><code>HTMLElement</code></dfn>, <dfn
id=queue-a-task><code>queue a task</code></dfn>, <dfn
id=task><code>task</code></dfn>, and <dfn
id=window><code>Window</code></dfn> are defined by HTML5. [<cite><a
href="#ref-html5">HTML5</a></cite>]
<p><dfn id=the-html-body-element>The HTML <code>body</code> element</dfn>
is the first <code>body</code> <a href="#html-element">HTML element</a>
child of the root <a href="#html-element">HTML element</a>
<code>html</code>.
<p><dfn id=content-edge>Content edge</dfn>, <dfn id=padding-edge>padding
edge</dfn>, <dfn id=border-edge>border edge</dfn>, and <dfn
id=canvas>canvas</dfn> are defined by CSS 2.1. [<cite><a
href="#ref-css21">CSS21</a></cite>]
<p><dfn id=viewport>Viewport</dfn> and <dfn
id=initial-containing-block>initial containing block</dfn> are defined by
CSS 2.1 unless there is an ancestor <code>foreignObject</code> element in
the <code>http://www.w3.org/2000/svg</code> namespace in which case that
element acts as viewport and initial containing block. [<cite><a
href="#ref-css21">CSS21</a></cite>] [<cite><a
href="#ref-svg">SVG</a></cite>]
<p>The term <dfn id=content>content</dfn> refers to the dimensions of the
element's content area, including overflown content. [<cite><a
href="#ref-css21">CSS21</a></cite>]
<p>The term <dfn id=document-content>document content</dfn> refers to the
area on the <a href="#canvas">canvas</a> that is rendered upon, excluding
content on negative axis.
<h3 id=css-pixels><span class=secno>2.3. </span>CSS pixels</h3>
<p>All coordinates and dimensions for the APIs defined in this
specification are in CSS pixels. [<cite><a
href="#ref-css21">CSS21</a></cite>]
<p class=note>This does not apply to e.g. <a
href="#dom-stylemedia-matchmedium"><code
title=dom-StyleMedia-matchMedium>matchMedium()</code></a> as the units are
explicitly given there and defined by the Media Queries specification.
[<cite><a href="#ref-mq">MQ</a></cite>]
<h2 id=dom-features><span class=secno>3. </span>DOM Features</h2>
<p>This specification defines the <a
href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMFeatures">DOM
feature</a> "<code>Views</code>" for versions "<code>2.0</code>" and
"<code>3.0</code>". User agents supporting this specification <em
class=ct>must</em> support that feature and versions. [<cite><a
href="#ref-dom3core">DOM3Core</a></cite>]
<p>Authors are encouraged to stay away from DOM features as user agents
claiming to support the DOM feature might not support the feature you need
and user agents supporting parts of the specification might not claim
support for the DOM feature.
<h2 id=extensions-to-the-window-interface><span class=secno>4.
</span>Extensions to the <code title="">Window</code> Interface</h2>
<pre class=idl>[Supplemental] interface <a href="#window">Window</a> {
readonly attribute <a href="#stylemedia">StyleMedia</a> <a href="#dom-window-stylemedia" title=dom-Window-styleMedia>styleMedia</a>;
readonly attribute <a href="#screen">Screen</a> <a href="#dom-window-screen" title=dom-Window-screen>screen</a>;
// viewport
readonly attribute long <a href="#dom-window-innerwidth">innerWidth</a>;
readonly attribute long <a href="#dom-window-innerheight">innerHeight</a>;
readonly attribute long <a href="#dom-window-pagexoffset">pageXOffset</a>;
readonly attribute long <a href="#dom-window-pageyoffset">pageYOffset</a>;
void <a href="#dom-window-scroll" title=dom-Window-scroll>scroll</a>(long <var title="">x</var>, long <var title="">y</var>);
void <a href="#dom-window-scrollto" title=dom-Window-scrollto>scrollTo</a>(long <var title="">x</var>, long <var title="">y</var>);
void <a href="#dom-window-scrollby" title=dom-Window-scrollby>scrollBy</a>(long <var title="">x</var>, long <var title="">y</var>);
// client
readonly attribute long <a href="#dom-window-screenx">screenX</a>;
readonly attribute long <a href="#dom-window-screeny">screenY</a>;
readonly attribute long <a href="#dom-window-outerwidth">outerWidth</a>;
readonly attribute long <a href="#dom-window-outerheight">outerHeight</a>;
};</pre>
<p>The <dfn id=dom-window-stylemedia
title=dom-Window-styleMedia><code>styleMedia</code></dfn> attribute <em
class=ct>must</em> return the <a
href="#stylemedia"><code>StyleMedia</code></a> object associated with the
<a href="#window"><code>Window</code></a> object. It always returns the
same object.
<p>The <dfn id=dom-window-screen
title=dom-Window-screen><code>screen</code></dfn> attribute <em
class=ct>must</em> return the <a href="#screen"><code>Screen</code></a>
object associated with the <a href="#window"><code>Window</code></a>
object. It always returns the same object.
<p>The <dfn id=dom-window-innerwidth><code>innerWidth</code></dfn>
attribute <em class=ct>must</em> return the <a
href="#viewport">viewport</a> width including the size of a rendered
scroll bar (if any).
<div class=example>
<p>The following snippet shows how to obtain the width of the viewport:</p>
<pre><code>var viewportWidth = innerWidth</code></pre>
</div>
<p>The <dfn id=dom-window-innerheight><code>innerHeight</code></dfn>
attribute <em class=ct>must</em> return the <a
href="#viewport">viewport</a> height including the size of a rendered
scroll bar (if any).
<p>The <dfn id=dom-window-pagexoffset><code>pageXOffset</code></dfn>
attribute <em class=ct>must</em> return the x-coordinate, relative to the
<a href="#initial-containing-block">initial containing block</a> origin,
of the left of the <a href="#viewport">viewport</a>.
<p>The <dfn id=dom-window-pageyoffset><code>pageYOffset</code></dfn>
attribute <em class=ct>must</em> return the y-coordinate, relative to the
<a href="#initial-containing-block">initial containing block</a> origin,
of the top of the <a href="#viewport">viewport</a>.
<p>When the <dfn id=dom-window-scroll
title=dom-Window-scroll><code>scroll(<var title="">x</var>,<var
title="">y</var>)</code></dfn> method is invoked these steps <em
class=ct>must</em> be run:
<ol>
<li>
<p>If either <var title="">x</var> or <var title="">y</var> is infinite
or NaN stop this algorithm.
<li>
<dl>
<dt>If <a href="#document-content">document content</a> can have
overflow to the right
<dd>
<ol>
<li>
<p>Let <var title="">x</var> be min(<var title="">x</var>, <a
href="#content">content</a> width - <a href="#content-edge">content
edge</a> width).
<li>
<p>If <var title="">x</var> is negative let it be zero.
</ol>
<dt>If <a href="#document-content">document content</a> can have
overflow to the left (under right-to-left conditions)
<dd>
<ol>
<li>
<p>Let <var title="">x</var> be max(<var title="">x</var>, <a
href="#content-edge">content edge</a> width - <a
href="#content">content</a> width).
<li>
<p>If <var title="">x</var> is non-negative let it be zero.
</ol>
</dl>
<li>
<p>Let <var title="">y</var> be min(<var title="">y</var>, <a
href="#document-content">document content</a> height - <a
href="#viewport">viewport</a> height excluding the size of a rendered
scroll bar (if any)).
<li>
<p>If <var title="">y</var> is negative let it be zero.
<li>
<p>Align the x-coordinate <var title="">x</var> of the <a
href="#document-content">document content</a> with the left of the <a
href="#viewport">viewport</a> and align the y-coordinate <var
title="">y</var> of the <a href="#document-content">document content</a>
with the top of the <a href="#viewport">viewport</a>.
</ol>
<p>When the <dfn id=dom-window-scrollto
title=dom-Window-scrollto><code>scrollTo(<var title="">x</var>,<var
title="">y</var>)</code></dfn> method is invoked, the user agent <em
class=ct>must</em> act as if the <a href="#dom-window-scroll"><code
title=dom-Window-scroll>scroll()</code></a> method was invoked with the
same arguments.
<p>When the <dfn id=dom-window-scrollby
title=dom-Window-scrollby><code>scrollBy(<var title="">x</var>,<var
title="">y</var>)</code></dfn> method is invoked, the user agent <em
class=ct>must</em> act as if the <a href="#dom-window-scroll"><code
title=dom-Window-scroll>scroll()</code></a> method was invoked with <var
title="">x</var> plus <a
href="#dom-window-pagexoffset"><code>pageXOffset</code></a> as first
argument and <var title="">y</var> plus <a
href="#dom-window-pageyoffset"><code>pageYOffset</code></a> as second
argument.
<p>The <dfn id=dom-window-screenx><code>screenX</code></dfn> attribute <em
class=ct>must</em> return the x-coordinate, relative to the origin of the
screen of the output device, of the top of the client window as number of
pixels, or zero if there is no such thing.
<p>The <dfn id=dom-window-screeny><code>screenY</code></dfn> attribute <em
class=ct>must</em> return the y-coordinate, relative to the origin of the
screen of the output device, of the left of the client window as number of
pixels, or zero if there is no such thing.
<p>The <dfn id=dom-window-outerwidth><code>outerWidth</code></dfn>
attribute <em class=ct>must</em> return the width of the client window. If
there is no client window this attribute <em class=ct>must</em> return
zero.
<p>The <dfn id=dom-window-outerheight><code>outerHeight</code></dfn>
attribute <em class=ct>must</em> return the height of the client window.
If there is no client window this attribute <em class=ct>must</em> return
zero.
<h3 id=the-stylemedia-interface><span class=secno>4.1. </span>The <code
title="">StyleMedia</code> Interface</h3>
<pre class=idl>interface <dfn id=stylemedia>StyleMedia</dfn> {
readonly attribute DOMString <a href="#dom-stylemedia-type" title=dom-StyleMedia-type>type</a>;
boolean <a href="#dom-stylemedia-matchmedium" title=dom-StyleMedia-matchMedium>matchMedium</a>(DOMString <var title="">medium</var>);
void <a href="#dom-StyleMedia-addMediumListener" title=dom-StyleMedia-addMediumListener>addMediumListener</a>(DOMString <var title="">medium</var>, <a href="#mediaquerycallback">MediaQueryCallback</a> <var title="">mediumcallback</var>);
void <a href="#dom-StyleMedia-removeMediumListener" title=dom-StyleMedia-removeMediumListener>removeMediumListener</a>(DOMString <var title="">medium</var>, <a href="#mediaquerycallback">MediaQueryCallback</a> <var title="">mediumcallback</var>);
};
[Callback=FunctionOnly, NoInterfaceObject]
interface <dfn id=mediaquerycallback>MediaQueryCallback</dfn> {
void <span>handleEvent</span>(<a href="#mediaquerychange">MediaQueryChange</a> <var title="">mediaquerychange</var>);
};</pre>
<p>The <dfn id=dom-stylemedia-type
title=dom-StyleMedia-type><code>type</code></dfn> attribute <em
class=ct>must</em> return the string that represents the media type used
for rendering the <a href="#document"><code>Document</code></a>. The media
types are defined by CSS 2.1 (<code title="">screen</code>,
<code>print</code>, et cetera). [<cite><a
href="#ref-css21">CSS21</a></cite>]
<div class=example>
<p>The following snippet determines whether the page is rendered using the
projection media type:</p>
<pre><code>var isProjection = media.type == "projection"</code></pre>
</div>
<p>The <dfn id=dom-stylemedia-matchmedium
title=dom-StyleMedia-matchMedium><code>matchMedium(<var
title="">medium</var>)</code></dfn> method, when invoked, <em
class=ct>must</em> return the result of the following algorithm:</p>
<!-- should use "parse a media query" -->
<ol>
<li>
<p>If <var title="">medium</var> can be parsed according to the rules
given in the Media Queries specification and matches the state of the
rendered <a href="#document"><code>Document</code></a> return
<code>true</code> and terminate this algorithm. [<cite><a
href="#ref-mq">MQ</a></cite>]
<li>
<p>Otherwise, return <code>false</code>.
</ol>
<div class=example>
<p>The following snippet determines whether the device is a color device:</p>
<pre><code>var isColorDevice = styleMedia.matchMedium("(color)")</code></pre>
</div>
<p>Each <a href="#window"><code>Window</code></a> has an associated <dfn
id=list-of-media-query-listeners>list of media query listeners</dfn>. Each
listener consists of a media query and a callback.
<p class=note>Due to the rules for <a
href="#dom-StyleMedia-addMediumListener"><code
title=dom-StyleMedia-addMediumListener>addMediumListener()</code></a>
below each listener is unique. Media queries and callbacks are not
necessarily unique.
<p>The <dfn id=dom-StyleMedia-addMediumListener
title=dom-StyleMedia-addMediumListener>addMediumListener(<var
title="">medium</var>, <var title="">mediumcallback</var>)</dfn> method
<em class=ct>must</em> run these steps:</p>
<!-- based on dom-MediaList-appendMedium -->
<ol>
<li>
<p>Let <var title="">m</var> be the result of <a
href="#parse-a-media-query" title="parse a media query">parsing</a> the
given value.
<li>
<p>If <var title="">m</var> is null terminate these steps.
<li>
<p>If <a href="#compare-media-queries" title="compare media
queries">comparing</a> <var title="">m</var> with any of the media
queries in the <a href="#list-of-media-query-listeners">list of media
query listeners</a> returns true <em>and</em> the associated callback of
that media query is the same as <var title="">mediumcallback</var>,
terminate these steps.
<li>
<p>Append the tuple of <var title="">m</var> and <var
title="">mediumcallback</var> to the <a
href="#list-of-media-query-listeners">list of media query listeners</a>.
</ol>
<p>The <dfn id=dom-StyleMedia-removeMediumListener
title=dom-StyleMedia-removeMediumListener>removeMediumListener(<var
title="">medium</var>)</dfn> method <em class=ct>must</em> run these
steps:
<ol>
<li>
<p>Let <var title="">m</var> be the result of <a
href="#parse-a-media-query" title="parse a media query">parsing</a> the
given value.
<li>
<p>If <var title="">m</var> is null terminate these steps.
<li>
<p>If <a href="#compare-media-queries" title="compare media
queries">comparing</a> <var title="">m</var> with any of the media
queries in the <a href="#list-of-media-query-listeners">list of media
query listeners</a> returns true <em>and</em> the associated callback of
that media query is the same as <var title="">mediumcallback</var>,
remove the tuple of <var title="">m</var> and <var
title="">mediumcallback</var> from the <a
href="#list-of-media-query-listeners">list of media query listeners</a>.
</ol>
<p>If one or more media queries in the <a
href="#list-of-media-query-listeners">list of media query listeners</a>
changes in evaluation then for each media query of which the evaluation
changes, in the order of the <a href="#list-of-media-query-listeners">list
of media query listeners</a>, <a href="#queue-a-task">queue a task</a>
that invokes the associated callback, passing as argument a <a
href="#mediaquerychange"><code>MediaQueryChange</code></a> object.
<pre class=idl>[NoInterfaceObject]
interface <dfn id=mediaquerychange>MediaQueryChange</dfn> {
readonly attribute DOMString <a href="#dom-mediaquerychange-mediatext" title=dom-MediaQueryChange-mediaText>mediaText</a>;
readonly attribute boolean <a href="#dom-mediaquerychange-matches" title=dom-MediaQueryChange-matches>matches</a>;
};</pre>
<p>The <dfn id=dom-mediaquerychange-mediatext
title=dom-MediaQueryChange-mediaText><code>mediaText</code></dfn>
attribute <em class=ct>must</em> return a <a
href="#serialize-a-media-query" title="serialize a media
query">serialization</a> of the media query.
<p>The <dfn id=dom-mediaquerychange-matches
title=dom-MediaQueryChange-matches><code>matches</code></dfn> attribute
<em class=ct>must</em> return whether the media query matches the state of
the rendered <a href="#document"><code>Document</code></a> at the time the
<a href="#task">task</a> was <a href="#queue-a-task" title="queue a
task">queued</a>.
<h3 id=the-screen-interface><span class=secno>4.2. </span>The <code
title="">Screen</code> Interface</h3>
<p>As its name suggests, the <a href="#screen"><code>Screen</code></a>
interface represents information about the screen of the output device.
<pre class=idl>interface <dfn id=screen>Screen</dfn> {
readonly attribute unsigned long <a href="#dom-screen-availwidth">availWidth</a>;
readonly attribute unsigned long <a href="#dom-screen-availheight">availHeight</a>;
readonly attribute unsigned long <a href="#dom-screen-width">width</a>;
readonly attribute unsigned long <a href="#dom-screen-height">height</a>;
readonly attribute unsigned long <a href="#dom-screen-colordepth">colorDepth</a>;
readonly attribute unsigned long <a href="#dom-screen-pixeldepth">pixelDepth</a>;
};</pre>
<p>The <dfn id=dom-screen-availwidth><code>availWidth</code></dfn>
attribute <em class=ct>must</em> return the available width of the
rendering surface of the output device.
<p>The <dfn id=dom-screen-availheight><code>availHeight</code></dfn>
attribute <em class=ct>must</em> return the available height of the
rendering surface of the output device.
<p>The <dfn id=dom-screen-width><code>width</code></dfn> attribute <em
class=ct>must</em> return the width of the output device.
<p>The <dfn id=dom-screen-height><code>height</code></dfn> attribute <em
class=ct>must</em> return the height of the output device.
<p>The <dfn id=dom-screen-colordepth><code>colorDepth</code></dfn> and <dfn
id=dom-screen-pixeldepth><code>pixelDepth</code></dfn> attributes <em
class=ct>must</em> both return the number of bits allocated to colors in
the output device. If the output device does not support colors these
attributes <em class=ct>must</em> return zero.</p>
<!-- pixelDepth is not supported by Internet Explorer 7 -->
<p class=note>Bits allocated to handling transparency are not taken into
account.
<h2 id=extensions-to-the-document-interface><span class=secno>5.
</span>Extensions to the <code title="">Document</code> Interface</h2>
<pre class=idl>[Supplemental] interface <a href="#document">Document</a> {
Element <a href="#dom-document-elementfrompoint">elementFromPoint</a>(float <var title="">x</var>, float <var title="">y</var>);
<a href="#caretposition">CaretPosition</a> <a href="#dom-document-caretpositionfrompoint">caretPositionFromPoint</a>(float <var title="">x</var>, float <var title="">y</var>);
};</pre>
<p>The <dfn id=dom-document-elementfrompoint
title=elementfrompoint><code>elementFromPoint(<var title="">x</var>, <var
title="">y</var>)</code></dfn> method, when invoked, <em
class=ct>must</em> return the element at coordinates
<var>x</var>,<var>y</var> in the <a href="#viewport">viewport</a>. The
element to be returned is determined through hit testing. If either
argument is negative, <var title="">x</var> is greater than the <a
href="#viewport">viewport</a> width excluding the size of a rendered
scroll bar (if any), or <var title="">y</var> is greather than the <a
href="#viewport">viewport</a> height excluding the size of a rendered
scroll bar (if any), the method <em class=ct>must</em> return
<code>null</code>. If there is no element at the given position the method
<em class=ct>must</em> return the root element, if any, or
<code>null</code> otherwise.
<p>The <dfn id=dom-document-caretpositionfrompoint
title=caretpositionfrompoint><code>caretPositionFromPoint(<var
title="">x</var>, <var title="">y</var>)</code></dfn> method, when
invoked, <em class=ct>must</em> return the result of running these steps:
<ol>
<li>
<p>If either argument is negative, <var title="">x</var> is greater than
the <a href="#viewport">viewport</a> width excluding the size of a
rendered scroll bar (if any), <var title="">y</var> is greather than the
<a href="#viewport">viewport</a> height excluding the size of a rendered
scroll bar (if any) return null.
<li>
<p>If at the coordinates <var title="">x</var>,<var title="">y</var> in
the <a href="#viewport">viewport</a> no text insertion point indicator
would have been inserted return null.
<li>
<p>If at the coordinates <var title="">x</var>,<var title="">y</var> in
the <a href="#viewport">viewport</a> a text insertion point indicator
would have been inserted in a text entry widget which is also a replaced
element return a <a href="#caret-position">caret position</a> with its
properties set as follows:</p>
<dl>
<dt><a href="#caret-node">caret node</a>
<dd>
<p>The node corresponding to the text entry widget.
<dt><a href="#caret-offset">caret offset</a>
<dd>
<p>The amount of 16-bit units to the left of where the text insertion
point indicator would have inserted.
<dt><a href="#caret-range">caret range</a>
<dd>
<p>null
</dl>
<li>
<p>Otherwise, return a <a href="#caret-position">caret position</a> where
the <a href="#caret-range">caret range</a> is a collapsed <a
href="#range"><code>Range</code></a> object for the position where the
text insertion point indicator would have been inserted and the other
properties are set as follows:</p>
<dl>
<dt><a href="#caret-node">caret node</a>
<dd>
<p>The <code title=dom-Range-startContainer>startContainer</code> of
the <a href="#caret-range">caret range</a>.
<dt><a href="#caret-offset">caret offset</a>
<dd>
<p>The <code title=dom-Range-startOffset>startOffset</code> of the <a
href="#caret-range">caret range</a>.</p>
</dl>
</ol>
<p class=note>The specifics of hit testing are out of scope of this
specification and therefore the exact details of <a
href="#dom-document-elementfrompoint"><code>elementFromPoint()</code></a>
and <a
href="#dom-document-caretpositionfrompoint"><code>caretPositionFromPoint()</code></a>
are therefore too. Hit testing will hopefully be defined in a future
revision of CSS or HTML.
<h2 id=the-caretposition-interface><span class=secno>6. </span>The <code
title="">CaretPosition</code> Interface</h2>
<p>A <dfn id=caret-position>caret position</dfn> gives the position of a
text insertion point indicator. It always has an associated <dfn
id=caret-node>caret node</dfn>, <dfn id=caret-offset>caret offset</dfn>,
and <dfn id=caret-range>caret range</dfn>. It is represented by a <a
href="#caretposition"><code>CaretPosition</code></a> object.
<pre class=idl>interface <dfn id=caretposition>CaretPosition</dfn> {
readonly attribute <span>Node</span> <a href="#dom-caretposition-offsetnode" title=dom-CaretPosition-offsetNode>offsetNode</a>;
readonly attribute unsigned long <a href="#dom-caretposition-offset" title=dom-CaretPosition-offset>offset</a>;
readonly attribute <a href="#range">Range</a> <a href="#dom-caretposition-range" title=dom-CaretPosition-range>range</a>;
};</pre>
<p>The <dfn id=dom-caretposition-offsetnode
title=dom-CaretPosition-offsetNode><code>offsetNode</code></dfn> attribute
<em class=ct>must</em> return the <a href="#caret-node">caret node</a>.
<p>The <dfn id=dom-caretposition-offset
title=dom-CaretPosition-offset><code>offset</code></dfn> attribute <em
class=ct>must</em> return the <a href="#caret-offset">caret offset</a>.
<p>The <dfn id=dom-caretposition-range
title=dom-CaretPosition-range><code>range</code></dfn> attribute <em
class=ct>must</em> return the <a href="#caret-range">caret range</a>.</p>
<!-- https://bugs.webkit.org/show_bug.cgi?id=27046 -->
<h2 id=extensions-to-the-element-interface><span class=secno>7.
</span>Extensions to the <code title="">Element</code> Interface</h2>
<pre class=idl>[Supplemental] interface <a href="#element">Element</a> {
<a href="#clientrectlist">ClientRectList</a> <a href="#dom-element-getclientrects">getClientRects</a>();
<a href="#clientrect">ClientRect</a> <a href="#dom-element-getboundingclientrect">getBoundingClientRect</a>();
attribute long <a href="#dom-element-scrolltop">scrollTop</a>; // scroll on setting
attribute long <a href="#dom-element-scrollleft">scrollLeft</a>; // scroll on setting
readonly attribute long <a href="#dom-element-scrollwidth">scrollWidth</a>;
readonly attribute long <a href="#dom-element-scrollheight">scrollHeight</a>;
readonly attribute long <a href="#dom-element-clienttop">clientTop</a>;
readonly attribute long <a href="#dom-element-clientleft">clientLeft</a>;
readonly attribute long <a href="#dom-element-clientwidth">clientWidth</a>;
readonly attribute long <a href="#dom-element-clientheight">clientHeight</a>;
};</pre>
<h3 id=the-getclientrects-and-getboundingclient><span class=secno>7.1.
</span>The <code title="">getClientRects()</code> and <code
title="">getBoundingClientRect()</code> methods</h3>
<p>The <a
href="#dom-element-getclientrects"><code>getClientRects()</code></a> and
<a
href="#dom-element-getboundingclientrect"><code>getBoundingClientRect</code></a>
methods provide information about the position of the border box edges of
an element relative to the viewport. The objects these methods return <em
class=ct>must</em> be static. That is, changes to the underlying document
are not reflected in the objects.
<p>The <dfn
id=dom-element-getclientrects><code>getClientRects()</code></dfn> method,
when invoked, <em class=ct>must</em> return the result of the following
algorithm:
<ol>
<li>
<p>If the element on which it was invoked does not have an associated CSS
layout box and is not in the <code>http://www.w3.org/2000/svg</code>
namespace return an empty <a
href="#clientrectlist"><code>ClientRectList</code></a> object and stop
this algorithm.
<li>
<p>If the element does not have an associated CSS layout box and is in
the <code>http://www.w3.org/2000/svg</code> namespace return a <a
href="#clientrectlist"><code>ClientRectList</code></a> object containing
a single <a href="#clientrect"><code>ClientRect</code></a> object that
describes the bounding box of the element as defined by SVG
specification. [<cite><a href="#ref-svg">SVG</a></cite>]
<li>
<p>Return a <a href="#clientrectlist"><code>ClientRectList</code></a>
object containing a list of <a
href="#clientrect"><code>ClientRect</code></a> objects in content order
describing the border boxes (including those with a height or width of
zero) with the following constraints:</p>
6D58 <ul>
<li>
<p>If the element on which the method was invoked has a computed value
for <code>display</code> property of <code>table</code> or
<code>inline-table</code> include both the table box and the caption
box, if any, but not the anonymous container box. [<cite><a
href="#ref-css21">CSS21</a></cite>]
<li>
<p>Replace each <a
href="http://www.w3.org/TR/CSS21/visuren.html#anonymous-block-level">anonymous
block box</a> with its child box(es) and repeat this until no
anonymous block boxes are left in the final list. [<cite><a
href="#ref-css21">CSS21</a></cite>]
</ul>
</ol>
<p>The <dfn
id=dom-element-getboundingclientrect><code>getBoundingClientRect()</code></dfn>
method, when invoked, <em class=ct>must</em> return the result of the
following algorithm:
<ol>
<li>
<p>Let <var>list</var> be the result of invoking <a
href="#dom-element-getclientrects"><code>getClientRects()</code></a> on
the same element this method was invoked on.
<li>
<p>If the <var>list</var> is empty return a <a
href="#clientrect"><code>ClientRect</code></a> object whose <a
href="#dom-clientrect-top"><code
title=dom-clientrect-top>top</code></a>, <a
href="#dom-clientrect-right"><code
title=dom-clientrect-right>right</code></a>, <a
href="#dom-clientrect-bottom"><code
title=dom-clientrect-bottom>bottom</code></a> and <a
href="#dom-clientrect-left"><code
title=dom-clientrect-left>left</code></a> members are zero.
<li>
<p>Otherwise, return a <a href="#clientrect"><code>ClientRect</code></a>
object describing the smallest rectangle that includes the first
rectangle in <var>list</var> and all of the remaining rectangles of
which the height or width is not zero.
</ol>
<div class=example>
<p>The following snippet gets the dimensions of the first <code>div</code>
element in a document:</p>
<pre><code>var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
var exampleWidth = example.width;
var exampleHeight = example.height;</code></pre>
</div>
<h3 id=scroll-attributes><span class=secno>7.2. </span>The <code
title="">scrollTop</code>, <code title="">scrollLeft</code>, <code
title="">scrollWidth</code>, and <code title="">scrollHeight</code>
attributes</h3>
<p>The <dfn id=dom-element-scrolltop><code>scrollTop</code></dfn>
attribute, when called on element <var>A</var>, <em class=ct>must</em>
return the value that is the result of running the following algorithm:
<ol>
<li>
<p>If <var>A</var> does not have an associated CSS layout box return zero
and stop this algorithm.
<li>
<p>Return the y-coordinate of the <a href="#content">content</a> at the
alignment point with the top of the <a href="#content-edge">content
edge</a> of <var>A</var>.
</ol>
<p>When setting the <a
href="#dom-element-scrolltop"><code>scrollTop</code></a> attribute to <var
title="">y</var> on element <var>A</var> user agents <em
class=ct>must</em> run the following algorithm:
<ol>
<li>
<p>If <var>A</var> does not have an associated CSS layout box or vertical
overflow stop this algorithm.
<li>
<p>If <var title="">y</var> is infinite or NaN stop this algorithm.</p>
<li>
<p>Let <var title="">y</var> be min(<var title="">y</var>, <a
href="#content">content</a> height - <a href="#content-edge">content
edge</a> height).
<li>
<p>If <var title="">y</var> is negative let it be zero.
<li>
<p>Align <a href="#content">content</a> y-coordinate <var
title="">y</var> with the top of the <a href="#content-edge">content
edge</a> of <var>A</var>.
</ol>
<p>The <dfn id=dom-element-scrollleft><code 5F5C >scrollLeft</code></dfn>
attribute, when called on element <var>A</var>, <em class=ct>must</em>
return the value that is the result of running the following algorithm:
<ol>
<li>
<p>If <var>A</var> does not have an associated CSS layout box return zero
and stop this algorithm.
<li>
<p>Return the x-coordinate of the <a href="#content">content</a> at the
alignment point with the left of the <a href="#content-edge">content
edge</a> of <var>A</var>.
</ol>
<p>When setting the <a
href="#dom-element-scrollleft"><code>scrollLeft</code></a> attribute to
<var title="">x</var> on element <var>A</var> user agents <em
class=ct>must</em> run the following algorithm:
<ol>
<li>
<p>If <var>A</var> does not have an associated CSS layout box or
horizontal overflow stop this algorithm.
<li>
<p>If <var title="">x</var> is infinite or NaN stop this algorithm.</p>
<li>
<dl>
<dt>If <var>A</var> can have overflow to the right
<dd>
<ol>
<li>
<p>Let <var title="">x</var> be min(<var title="">x</var>, <a
href="#content">content</a> width - <a href="#content-edge">content
edge</a> width).
<li>
<p>If <var title="">x</var> is negative let it be zero.
</ol>
<dt>If <var>A</var> can have overflow to the left (under right-to-left
conditions)
<dd>
<ol>
View remainder of file in raw view