cssom-view/Overview.html@3e45009199b6
cssom-view/Overview.html
Mon, 27 May 2013 15:47:02 +0200
- author
- Simon Pieters <simonp@opera.com>
- date
- Mon, 27 May 2013 15:47:02 +0200
- changeset 8256
- 3e45009199b6
- parent 8255
- 1398c808e617
- child 8257
- fbcf922975d0
- permissions
- -rw-r--r--
[cssom-view] Exclude the scrollbar for element.scrollHeight/Width. http://www.w3.org/mid/815a3b87078b47889a2d8ee6c2ba9b29@BY2PR03MB057.namprd03.prod.outlook.com
1 <!DOCTYPE html><html lang="en-US"><head>
2 <meta charset="utf-8">
3 <title>CSSOM View Module</title>
4 <style>
5 .idl { border:solid thin; background:#eee; color:#000; padding:0.5em }
6 .idl :link, .idl :visited { color:inherit; background:transparent }
7 dfn { font-weight:bold; font-style:normal }
8 .example { margin-left:1em; padding-left:1em; border-left:double; color:#222; background:#fcfcfc }
9 .example table code { color:inherit }
10 td, th { padding:.1em }
11 .note { margin-left:2em; color:green; font-style:italic; font-weight:bold }
12 p.note::before { content:"Note: " }
13 .XXX { padding:.5em; border:solid red }
14 p.XXX::before { content:"Issue: " }
15 dl.switch { padding-left:2em }
16 dl.switch > dt { text-indent:-1.5em }
17 dl.switch > dt:before { content:'\21AA'; padding:0 0.5em 0 0; display:inline-block; width:1em; text-align:right; line-height:0.5em }
18 code { color:orangered }
19 code :link, code :visited { color:inherit }
20 </style>
21 <link href="https://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet">
22 </head>
23 <body class="draft">
24 <div class="head">
26 <!--begin-logo-->
27 <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="https://www.w3.org/Icons/w3c_home" width="72"></a></p>
28 <!--end-logo-->
30 <h1>CSSOM View Module</h1>
32 <h2 class="no-num no-toc" id="w3c-doctype">Editor's Draft 27 May 2013</h2>
34 <dl>
36 <dt>This Version:</dt>
37 <dd class="dontpublish"><a href="http://dev.w3.org/csswg/cssom-view/">http://dev.w3.org/csswg/cssom-view/</a></dd>
38 <dt class="dontpublish">Participate:</dt>
39 <dd class="dontpublish"><a href="mailto:www-style@w3.org?subject==%5Bcssom%5D%20">www-style@w3.org</a>
40 (<a href="http://lists.w3.org/Archives/Public/www-style/">archives</a>)
41 <dd class="dontpublish"><a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?product=CSS&component=CSSOM%20View">File a bug</a>
42 (<a href="https://www.w3.org/Bugs/Public/buglist.cgi?component=CSSOM%20View&product=CSS&resolution=---">open bugs</a>)
43 <script async="" src="https://w3c-test.org/resources.whatwg.org/file-bug.js"></script>
44 <dd class="dontpublish"><a href="irc://irc.w3.org:6665/css">IRC: #css on W3C</a></dd>
46 <dt class="dontpublish">Previous Versions:</dt>
47 <dd class="dontpublish"><a href="http://www.w3.org/TR/2009/WD-cssom-view-20090804/">http://www.w3.org/TR/2009/WD-cssom-view-20090804/</a></dd>
48 <dd class="dontpublish"><a href="http://www.w3.org/TR/2008/WD-cssom-view-20080222/">http://www.w3.org/TR/2008/WD-cssom-view-20080222/</a></dd>
49 <dd class="dontpublish"><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>
51 <dt>Editors:</dt>
52 <dd><a>Simon Pieters</a>
53 (<a href="http://www.opera.com/">Opera Software ASA</a>)
54 <<a href="mailto:simponp@opera.com">simonp@opera.com</a>></dd>
55 <dd><a href="http://www.w3.org/wiki/User:Gadams">Glenn Adams</a>
56 (<a href="http://www.cox.com/">Cox Communications, Inc.</a>)
57 <<a href="mailto:glenn.adams@cox.com">glenn.adams@cox.com</a>></dd>
59 <dt>Previous Editor:</dt>
60 <dd><a href="http://annevankesteren.nl/">Anne van Kesteren</a>
61 (<a href="http://www.opera.com/">Opera Software ASA</a>)
62 <<a href="mailto:annevk@opera.com">annevk@opera.com</a>></dd>
63 </dl>
66 <!--begin-copyright-->
67 <p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2013 <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>
68 <!--end-copyright-->
70 </div>
72 <hr>
74 <h2 class="no-num no-toc" id="abstract">Abstract</h2>
76 <p>The APIs introduced by this specification provide authors with a way to
77 inspect and manipulate the visual view of a document. This includes
78 getting the position of element layout boxes, obtaining the width
79 of the viewport through script, and also scrolling an element.</p>
83 <h2 class="no-num no-toc" id="sotd">Status of This Document</h2>
85 <p><em>This section describes the status of this document at the time of
86 its publication. Other documents may supersede this document. A list of
87 current W3C publications and the latest revision of this technical report
88 can be found in the <a href="http://www.w3.org/TR/">W3C technical reports
89 index at http://www.w3.org/TR/.</a></em>
91 <p>This is the 27 May 2013 Editor's Draft of CSSOM View. Please send
92 comments to
93 <a href="mailto:www-style@w3.org?subject=%5Bcssom-view%5D%20">www-style@w3.org</a>
94 (<a href="http://lists.w3.org/Archives/Public/www-style/">archived</a>)
95 with <samp>[cssom-view]</samp> at the start of the subject line.
97 <p>This document was produced by the <a href="http://www.w3.org/Style/CSS/members">CSS Working Group</a> (part of
98 the <a href="http://www.w3.org/Style/">Style Activity</a>).
100 <p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
101 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
102 connection with the deliverables of the group; that page also includes
103 instructions for disclosing a patent. An individual who has actual
104 knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
105 Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
106 6 of the W3C Patent Policy</a>.</p>
108 <p>Publication as a Working Draft does not imply endorsement by the W3C
109 Membership. This is a draft document and may be updated, replaced or
110 obsoleted by other documents at any time. It is inappropriate to cite this
111 document as other than work in progress.
114 <h2 class="no-num no-toc" id="toc">Table of Contents</h2>
117 <!--begin-toc-->
118 <ol class="toc">
119 <li><a href="#background"><span class="secno">1 </span>Background</a></li>
120 <li><a href="#conformance"><span class="secno">2 </span>Conformance</a>
121 <ol class="toc">
122 <li><a href="#web-idl"><span class="secno">2.1 </span>Web IDL</a></ol></li>
123 <li><a href="#terminology"><span class="secno">3 </span>Terminology</a>
124 <ol class="toc">
125 <li><a href="#css-pixels"><span class="secno">3.1 </span>CSS pixels</a></ol></li>
126 <li><a href="#common-infrastructure"><span class="secno">4 </span>Common Infrastructure</a>
127 <ol class="toc">
128 <li><a href="#scrolling"><span class="secno">4.1 </span>Scrolling</a></ol></li>
129 <li><a href="#extensions-to-the-window-interface"><span class="secno">5 </span>Extensions to the <code title="">Window</code> Interface</a>
130 <ol class="toc">
131 <li><a href="#the-mediaquerylist-interface"><span class="secno">5.1 </span>The <code title="">MediaQueryList</code> Interface</a></li>
132 <li><a href="#the-screen-interface"><span class="secno">5.2 </span>The <code title="">Screen</code> Interface</a></ol></li>
133 <li><a href="#extensions-to-the-document-interface"><span class="secno">6 </span>Extensions to the <code title="">Document</code> Interface</a>
134 <ol class="toc">
135 <li><a href="#the-caretposition-interface"><span class="secno">6.1 </span>The <code title="">CaretPosition</code> Interface</a></ol></li>
136 <li><a href="#extensions-to-the-element-interface"><span class="secno">7 </span>Extensions to the <code title="">Element</code> Interface</a>
137 <ol class="toc">
138 <li><a href="#the-getclientrects-and-getboundingclientrect-methods"><span class="secno">7.1 </span>The <code title="">getClientRects()</code> and
139 <code title="">getBoundingClientRect()</code> methods</a></li>
140 <li><a href="#element-scrolling-members"><span class="secno">7.2 </span><code title="">Element</code> Scrolling Members</a></ol></li>
141 <li><a href="#extensions-to-the-htmlelement-interface"><span class="secno">8 </span>Extensions to the <code title="">HTMLElement</code> Interface</a></li>
142 <li><a href="#extensions-to-the-range-interface"><span class="secno">9 </span>Extensions to the <code title="">Range</code> Interface</a></li>
143 <li><a href="#extensions-to-the-mouseevent-interface"><span class="secno">10 </span>Extensions to the <code title="">MouseEvent</code> Interface</a></li>
144 <li><a href="#rectangles"><span class="secno">11 </span>Rectangles</a>
145 <ol class="toc">
146 <li><a href="#the-clientrectlist-interface"><span class="secno">11.1 </span>The <code title="">ClientRectList</code> Interface</a></li>
147 <li><a href="#the-clientrect-interface"><span class="secno">11.2 </span>The <code title="">ClientRect</code> Interface</a></ol></li>
148 <li><a href="#events"><span class="secno">12 </span>Events</a>
149 <ol class="toc">
150 <li><a href="#resizing-viewports"><span class="secno">12.1 </span>Resizing viewports</a></li>
151 <li><a href="#scrolling-0"><span class="secno">12.2 </span>Scrolling</a></ol></li>
152 <li><a href="#css-properties"><span class="secno">13 </span>CSS properties</a>
153 <ol class="toc">
154 <li><a href="#smooth-scrolling:-the-scroll-behavior-property"><span class="secno">13.1 </span>Smooth Scrolling: The '<code title="">scroll-behavior</code>' Property</a></ol></li>
155 <li><a class="no-num" href="#references">References</a></li>
156 <li><a class="no-num" href="#acknowledgments">Acknowledgments</a></ol>
157 <!--end-toc-->
160 <h2 id="background"><span class="secno">1 </span>Background</h2>
162 <p>Many of the features defined in this specification have been supported
163 by browsers for a long period of time. The goal of this specification is
164 to define these features in such a way that they can be implemented by all
165 browsers in an interoperable manner. The specification also defines a
166 couple of new features that will hopefully be useful to authors. (If they
167 are not you can bug us!)</p>
170 <h2 id="conformance"><span class="secno">2 </span>Conformance</h2>
172 <p>All diagrams, examples, and notes in this specification are
173 non-normative, as are all sections explicitly marked non-normative.
174 Everything else in this specification is normative.
176 <p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
177 NOT",--> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
178 "OPTIONAL" in the normative parts of this document are to be
179 interpreted as described in RFC2119. For readability, these words do
180 not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a>
182 <p>Requirements phrased in the imperative as part of algorithms
183 (such as "strip any leading space characters" or "return false and
184 terminate these steps") are to be interpreted with the meaning of the
185 key word ("must", "should", "may", etc) used in introducing the
186 algorithm.
188 <p>Conformance requirements phrased as algorithms or specific steps
189 may be implemented in any manner, so long as the end result is
190 equivalent. (In particular, the algorithms defined in this
191 specification are intended to be easy to follow, and not intended to
192 be performant.)
194 <p id="hardwareLimitations">User agents may impose
195 implementation-specific limits on otherwise unconstrained inputs,
196 e.g. to prevent denial of service attacks, to guard against running
197 out of memory, or to work around platform-specific limitations.
199 <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
200 e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.
202 <p>Unless otherwise stated, string comparisons are done in a <span>case-sensitive</span> manner.
204 <p>A conforming user agent implements all the requirements made by this
205 specification.</p>
208 <h3 id="web-idl"><span class="secno">2.1 </span>Web IDL</h3>
210 <p>The IDL fragments in this specification must be
211 interpreted as required for conforming IDL fragments, as described in the
212 Web IDL specification. <a href="#refsWEBIDL">[WEBIDL]</a>
215 <h2 id="terminology"><span class="secno">3 </span>Terminology</h2>
217 <p>Terminology used in this specification is from
218 DOM,
219 CSSOM and
220 HTML.
221 <a href="#refsDOM">[DOM]</a>
222 <a href="#refsCSSOM">[CSSOM]</a>
223 <a href="#refsHTML">[HTML]</a>
225 <p class="XXX"><dfn id="mouseevent"><code>MouseEvent</code></dfn> and <dfn id="mouseeventinit"><code>MouseEventInit</code></dfn> are defined in …
227 <p><dfn id="the-html-body-element">The HTML <code>body</code> element</dfn> is the first
228 <code>body</code>
229 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#html-elements" title="HTML elements">HTML element</a> child of the root
230 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#html-elements" title="HTML elements">HTML element</a> <code>html</code>.</p>
232 <p><dfn id="content-edge">Content edge</dfn>,
233 <dfn id="padding-edge">padding edge</dfn>,
234 <dfn id="border-edge">border edge</dfn>,
235 <dfn id="margin-edge">margin edge</dfn> and
236 <dfn id="canvas">canvas</dfn> are defined by CSS.
237 <!--<span data-anolis-ref>CSS</span>-->
239 <p><dfn id="viewport">Viewport</dfn> and
240 <dfn id="initial-containing-block">initial containing block</dfn> are
241 defined by CSS 2.1 unless there is an ancestor <code>foreignObject</code>
242 element in the <code>http://www.w3.org/2000/svg</code> namespace in which
243 case that element acts as viewport and initial containing block.
244 <!--<span data-anolis-ref>CSS</span>-->
246 <p>The term <dfn id="scrolling-area">scrolling area</dfn> refers to a box of an element that has the following edges:
248 <dl>
249 <dt>top edge
250 <dd><p>The element's top padding edge.
251 <dt>right edge
252 <dd><p>The right-most edge of the element's right padding edge and the right margin edge of the element's all descendant boxes, excluding boxes that have an
253 ancestor of element as their containing block.
254 <dt>bottom edge
255 <dd><p>The bottom-most edge of the element's bottom padding edge and the bottom margin edge of the element's all descendant boxes, excluding boxes that have an
256 ancestor of element as their containing block.
257 <dt>left edge
258 <dd><p>The element's left padding edge.
259 </dl>
261 <p>The term <dfn id="document-content">document content</dfn> refers to the area on the
262 <a href="#canvas">canvas</a> that is rendered upon, excluding content on negative
263 axis.</p>
265 <p>The term <dfn id="css-layout-box">CSS layout box</dfn> refers to the same term in CSS. For the purpose
266 of the requirements in this specification, elements that have a computed value of the
267 '<code title="">display</code>' property that is <code>table-column</code> or
268 <code>table-column-group</code> must be considered to have an associated <a href="#css-layout-box">CSS
269 layout box</a> (the column or column group, respectively).</p>
271 <h3 id="css-pixels"><span class="secno">3.1 </span>CSS pixels</h3>
273 <p>All coordinates and dimensions for the APIs defined in this
274 specification are in CSS pixels. <!--<span data-anolis-ref>CSS</span>-->
276 <p class="note">This does not apply to e.g.
277 <code title="dom-Window-matchMedia"><a href="#dom-window-matchmedia">matchMedia()</a></code> as the units
278 are explicitly given there.</p>
282 <h2 id="common-infrastructure"><span class="secno">4 </span>Common Infrastructure</h2>
284 <h3 id="scrolling"><span class="secno">4.1 </span>Scrolling</h3>
286 <p>When a user agent is to <dfn id="perform-a-scroll">perform a scroll</dfn> of a scrolling box <var title="">box</var>, to a given position <var title="">position</var>, with a set of
287 steps <var title="">task</var>, an associated element <var title="">element</var> and a scroll behavior <var title="">behavior</var>, the following steps must be run:
289 <ol>
290 <li><p><a href="#concept-smooth-scroll-aborted" title="concept-smooth-scroll-aborted">Abort</a> any ongoing <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a> for <var title="">box</var>.
291 <li><p>If the user agent honors the '<code><a href="#scroll-behavior">scroll-behavior</a></code>' property and one of the following are true:
292 <ul>
293 <li><p><var title="">behavior</var> is <code title="">auto</code> and <var title="">element</var> is not null and its computed value of the '<code><a href="#scroll-behavior">scroll-behavior</a></code>'
294 property is '<code title="scroll-behavior-smooth"><a href="#scroll-behavior-smooth">smooth</a></code>'
295 <li><p><var title="">behavior</var> is <code title="">smooth</code>
296 </ul>
297 <p>...then follow these substeps:
298 <ol>
299 <li><p>Perform a <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a> of <var title="">box</var> to <var title="">position</var>.
300 <li><p><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">Queue a task</a> to run <var title="">task</var>, unless a <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task" title="concept-task">task</a> to
301 run <var title="">task</var> is in the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task" title="queue a task">queue</a>.
302 <li><p>Repeat the previous step in a user agent-defined interval while the <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a> is ongoing, as well as when
303 the <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a> is <a href="#concept-smooth-scroll-completed" title="concept-smooth-scroll-completed">completed</a> (but not if it is
304 <a href="#concept-smooth-scroll-aborted" title="concept-smooth-scroll-aborted">aborted</a>).
305 </ol>
306 <li><p>Otherwise, follow these substeps:
307 <ol>
308 <li><p>Perform an <span>instant scroll</span> of <var title="">box</var> to <var title="">position</var>.
309 <li><p><a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">Queue a task</a> to run <var title="">task</var>, unless a <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task" title="concept-task">task</a> to
310 run <var title="">task</var> is in the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task" title="queue a task">queue</a>.
311 </ol>
312 </ol>
314 <p>When a user agent is to perform a <dfn id="concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</dfn> of a scrolling box <var title="">box</var> to <var title="">position</var>,
315 it must update the scroll position of <var title="">box</var> in a user agent-defined fashion over a user agent-defined amount of time. When the scroll is
316 <dfn id="concept-smooth-scroll-completed" title="concept-smooth-scroll-completed">completed</dfn>, the scroll position of <var title="">box</var> must be <var title="">position</var>. The scroll can also
317 be <dfn id="concept-smooth-scroll-aborted" title="concept-smooth-scroll-aborted">aborted</dfn>, either by an algorithm or by the user.
319 <p>When a user agent is to perform an <dfn id="concept-instant-scroll" title="concept-instant-scroll">instant scroll</dfn> of a scrolling box <var title="">box</var> to
320 <var title="">position</var>, it must update the scroll position of <var title="">box</var> to <var title="">position</var>.
323 <h2 id="extensions-to-the-window-interface"><span class="secno">5 </span>Extensions to the <code title="">Window</code> Interface</h2>
325 <pre class="idl">enum <dfn id="scrollbehavior">ScrollBehavior</dfn> { "auto", "instant", "smooth" };
327 dictionary <dfn id="scrolloptions">ScrollOptions</dfn> {
328 double x;
329 double y;
330 <a href="#scrollbehavior">ScrollBehavior</a> behavior = "auto";
331 };
333 partial interface <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a> {
334 <a href="#mediaquerylist">MediaQueryList</a> <a href="#dom-window-matchmedia" title="dom-Window-matchMedia">matchMedia</a>(DOMString query);
335 readonly attribute <a href="#screen">Screen</a> <a href="#dom-window-screen" title="dom-Window-screen">screen</a>;
337 // viewport
338 readonly attribute double <a href="#dom-window-innerwidth" title="dom-Window-innerWidth">innerWidth</a>;
339 readonly attribute double <a href="#dom-window-innerheight" title="dom-Window-innerHeight">innerHeight</a>;
341 // viewport scrolling
342 readonly attribute double <a href="#dom-window-scrollx" title="dom-Window-scrollX">scrollX</a>;
343 readonly attribute double <a href="#dom-window-pagexoffset" title="dom-Window-pageXOffset">pageXOffset</a>;
344 readonly attribute double <a href="#dom-window-scrolly" title="dom-Window-scrollY">scrollY</a>;
345 readonly attribute double p<a href="#dom-window-pageyoffset" title="dom-Window-pageYOffset">pageYOffset</a>;
346 void <a href="#dom-window-scroll" title="dom-Window-scroll">scroll</a>(double x, double y, optional <a href="#scrolloptions">ScrollOptions</a> options);
347 void <a href="#dom-window-scrollto" title="dom-Window-scrollTo">scrollTo</a>(double x, double y, optional <a href="#scrolloptions">ScrollOptions</a> options);
348 void <a href="#dom-window-scrollby" title="dom-Window-scrollBy">scrollBy</a>(double x, double y, optional <a href="#scrolloptions">ScrollOptions</a> options);
350 // client
351 readonly attribute double <a href="#dom-window-screenx" title="dom-Window-screenX">screenX</a>;
352 readonly attribute double <a href="#dom-window-screeny" title="dom-Window-screenY">screenY</a>;
353 readonly attribute double <a href="#dom-window-outerwidth" title="dom-Window-outerWidth">outerWidth</a>;
354 readonly attribute double <a href="#dom-window-outerheight" title="dom-Window-outerHeight">outerHeight</a>;
355 };</pre>
357 <p>When the <dfn id="dom-window-matchmedia" title="dom-Window-matchMedia"><code>matchMedia(<var title="">query</var>)</code></dfn> method is invoked these steps must be run:</p>
358 <ol>
359 <li><p>Let <var title="">parsed media query list</var> be the result of
360 <a class="external" href="http://dev.w3.org/csswg/cssom/#parse-a-media-query-list" title="parse a media query list">parsing</a>
361 <var title="">query</var>.</li>
362 <li><p>Return a <em>new</em> <code><a href="#mediaquerylist">MediaQueryList</a></code> object,
363 associated with the <code class="external"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a></code> object, with
364 <var title="">parsed media query list</var> as its associated
365 media query list.</li>
366 </ol>
368 <p>The <dfn id="dom-window-screen" title="dom-Window-screen"><code>screen</code></dfn> attribute must return the <code><a href="#screen">Screen</a></code> object
369 associated with the <code class="external"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a></code> object. It always returns the same
370 object.</p>
371 <p class="note">Accessing <code title="dom-Window-screen"><a href="#dom-window-screen">screen</a></code> through a <code class="external"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#windowproxy">WindowProxy</a></code> object might yield different
372 results when the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is navigated.</p>
374 <p>The <dfn id="dom-window-innerwidth" title="dom-Window-innerWidth"><code>innerWidth</code></dfn> attribute must return the <a href="#viewport">viewport</a> width including the size of a rendered
375 scroll bar (if any), or zero if there is no <a href="#viewport">viewport</a>.</p>
376 <div class="example">
377 <p>The following snippet shows how to obtain the width of the viewport:</p>
378 <pre><code>var viewportWidth = innerWidth</code></pre>
379 </div>
382 <p>The <dfn id="dom-window-innerheight" title="dom-Window-innerHeight"><code>innerHeight</code></dfn> attribute must return the <a href="#viewport">viewport</a> height including the size of a rendered
383 scroll bar (if any), or zero if there is no <a href="#viewport">viewport</a>.</p>
386 <p>The <dfn id="dom-window-scrollx" title="dom-Window-scrollX"><code>scrollX</code></dfn> attribute attribute must return the x-coordinate, relative to the <a href="#initial-containing-block">initial containing
387 block</a> origin, of the left of the <a href="#viewport">viewport</a>, or zero if there is no <a href="#viewport">viewport</a>.</p>
389 <p>The <dfn id="dom-window-pagexoffset" title="dom-Window-pageXOffset"><code>pageXOffset</code></dfn> attribute must return the value returned by the <code>scrollX</code> attribute.</p>
391 <p>The <dfn id="dom-window-scrolly" title="dom-Window-scrollY"><code>scrollY</code></dfn> attribute attribute must return the y-coordinate, relative to the <a href="#initial-containing-block">initial containing
392 block</a> origin, of the top of the <a href="#viewport">viewport</a>, or zero if there is no <a href="#viewport">viewport</a>.</p>
394 <p>The <dfn id="dom-window-pageyoffset" title="dom-Window-pageYOffset"><code>pageYOffset</code></dfn> attribute must return the value returned by the <code>scrollY</code> attribute.</p>
396 <p>When the <dfn id="dom-window-scroll" title="dom-Window-scroll"><code>scroll(<var title="">x</var>, <var title="">y</var>, <var title="">options</var>)</code></dfn> method is invoked these steps must be run:</p>
397 <ol>
398 <li><p>If there is no <a href="#viewport">viewport</a>, abort these steps.
399 <dl>
400 <dt>If <a href="#document-content">document content</a> can have overflow to the right
401 <dd><p>Let <var title="">x</var> be max(0, min(<var title="">x</var>,
402 <a href="#scrolling-area">scrolling area</a> width - <a href="#padding-edge">padding edge</a>
403 width)).</dd>
404 <dt>If <a href="#document-content">document content</a> can have overflow to the left
405 (under right-to-left conditions)
406 <dd><p>Let <var title="">x</var> be min(0, max(<var title="">x</var>,
407 <a href="#padding-edge">padding edge</a> width - <a href="#scrolling-area">scrolling area</a>
408 width)).</dd>
409 </dl>
410 </li>
411 <li><p>Let <var title="">y</var> be max(0, min(<var title="">y</var>,
412 <a href="#document-content">document content</a> height - <a href="#viewport">viewport</a>
413 height excluding the size of a rendered scroll bar (if any))).</li>
414 <li><p>Let <var title="">position</var> be the scroll position the <a href="#viewport">viewport</a> would have by aligning the x-coordinate <var title="">x</var> of the
415 <a href="#document-content">document content</a> with the left of the <a href="#viewport">viewport</a> and aligning the y-coordinate <var title="">y</var> of the <a href="#document-content">document content</a>
416 with the top of the <a href="#viewport">viewport</a>.
417 <li><p>If <var title="">position</var> is the same as the <a href="#viewport">viewport</a>'s current scroll position, and the <a href="#viewport">viewport</a> does not have an ongoing
418 <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a>, abort these steps.
419 <li><p>Let <var title="">task</var> be these steps:
420 <ol>
421 <li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named <code title="event-scroll">scroll</code> that bubbles at the
422 <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> object.
423 </ol>
424 <li><p><a href="#perform-a-scroll">Perform a scroll</a> of the <a href="#viewport">viewport</a> to <var title="">position</var>, with the set of steps <var title="">task</var>, and the
425 <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code>'s root element as the associated element, if there is one, or <code>null</code> otherwise, and the scroll behavior being the value of the <code title="">behavior</code> dictionary member of <var title="">options</var>.
426 </ol>
428 <p>When the <dfn id="dom-window-scrollto" title="dom-Window-scrollTo"><code>scrollTo(<var title="">x</var>, <var title="">y</var>, <var title="">options</var>)</code></dfn> method is invoked, the user agent must act as if
429 the <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> method was invoked with the same arguments.</p>
431 <p>When the <dfn id="dom-window-scrollby" title="dom-Window-scrollBy"><code>scrollBy(<var title="">x</var>, <var title="">y</var>, <var title="">options</var>)</code></dfn> method is invoked, the user agent must act as if
432 the <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> method was invoked with
433 <var title="">x</var> plus <code title="dom-Window-scrollX"><a href="#dom-window-scrollx">scrollX</a></code>
434 as first argument and <var title="">y</var> plus
435 <code title="dom-Window-scrollY"><a href="#dom-window-scrolly">scrollY</a></code> as second argument.</p>
437 <p>The <dfn id="dom-window-screenx" title="dom-Window-screenX"><code>screenX</code></dfn> attribute must return the x-coordinate,
438 relative to the origin of the screen of the output device, of the left of
439 the client window as number of pixels, or zero if there is no such
440 thing.</p>
442 <p>The <dfn id="dom-window-screeny" title="dom-Window-screenY"><code>screenY</code></dfn> attribute must return the y-coordinate,
443 relative to the origin of the screen of the output device, of the top of
444 the client window as number of pixels, or zero if there is no such
445 thing.</p>
447 <p>The <dfn id="dom-window-outerwidth" title="dom-Window-outerWidth"><code>outerWidth</code></dfn> attribute must return the width of the
448 client window. If there is no client window this
449 attribute must return zero.</p>
451 <p>The <dfn id="dom-window-outerheight" title="dom-Window-outerHeight"><code>outerHeight</code></dfn> attribute must return the height of the
452 client window. If there is no client window this
453 attribute must return zero.</p>
456 <h3 id="the-mediaquerylist-interface"><span class="secno">5.1 </span>The <code title="">MediaQueryList</code> Interface</h3>
458 <p>A <code><a href="#mediaquerylist">MediaQueryList</a></code> object has an associated media query list set on creation and an associated
459 <dfn id="list-of-media-query-list-listeners">list of media query list listeners</dfn>, which is initially empty.</p>
460 <p>If the associated media query list changes in evaluation then, for each
461 listener in the <a href="#list-of-media-query-list-listeners">list of media query list listeners</a> — in
462 appending order, <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> that invokes the listener,
463 passing as argument the <code><a href="#mediaquerylist">MediaQueryList</a></code> object.</p>
464 <div class="example">
465 <p>A simple piece of code that detects changes in the orientation of the viewport can be written as follows:</p>
466 <pre><code>function handleOrientationChange(mql) {
467 if(mql.matches) // landscape
468 …
469 else
470 …
471 }
472 var mql = matchMedia("(orientation:landscape)")
473 mql.addListener(handleOrientationChange)</code></pre>
474 </div>
476 <pre class="idl">interface <dfn id="mediaquerylist">MediaQueryList</dfn> {
477 readonly attribute DOMString <a href="#dom-mediaquerylist-media" title="dom-MediaQueryList-media">media</a>;
478 readonly attribute boolean <a href="#dom-mediaquerylist-matches" title="dom-MediaQueryList-matches">matches</a>;
479 void <a href="#dom-mediaquerylist-addlistener" title="dom-MediaQueryList-addListener">addListener</a>(<a href="#mediaquerylistlistener">MediaQueryListListener</a> listener);
480 void <a href="#dom-mediaquerylist-removelistener" title="dom-MediaQueryList-removeListener">removeListener</a>(<a href="#mediaquerylistlistener">MediaQueryListListener</a> listener);
481 };
483 callback <dfn id="mediaquerylistlistener">MediaQueryListListener</dfn> = void (<a href="#mediaquerylist">MediaQueryList</a> list);</pre>
485 <p>The <dfn id="dom-mediaquerylist-media" title="dom-MediaQueryList-media"><code>media</code></dfn> attribute must return the
486 <a class="external" href="http://dev.w3.org/csswg/cssom/#serialize-a-media-query-list" title="serialize a media query list">serialized</a> form of the associated media query list.</p>
488 <p>The <dfn id="dom-mediaquerylist-matches" title="dom-MediaQueryList-matches"><code>matches</code></dfn> attribute must return true if the associated media query list
489 matches the state of the rendered <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> and false if it does not.</p>
491 <p>When the <dfn id="dom-mediaquerylist-addlistener" title="dom-MediaQueryList-addListener"><code>addListener(<var title="">listener</var>)</code></dfn> method is invoked <var title="">listener</var> must
492 be appended to the <a href="#list-of-media-query-list-listeners">list of media query list listeners</a>, unless
493 it is already in the <a href="#list-of-media-query-list-listeners">list of media query list listeners</a>.</p>
495 <p>When the <dfn id="dom-mediaquerylist-removelistener" title="dom-MediaQueryList-removeListener"><code>removeListener(<var title="">listener</var>)</code></dfn> method is invoked
496 <var title="">listener</var> must be removed from the <a href="#list-of-media-query-list-listeners">list of media query list listeners</a>.</p>
498 <h3 id="the-screen-interface"><span class="secno">5.2 </span>The <code title="">Screen</code> Interface</h3>
500 <p>As its name suggests, the <code><a href="#screen">Screen</a></code> interface represents information about the screen of the output device.</p>
502 <pre class="idl">interface <dfn id="screen">Screen</dfn> {
503 readonly attribute double <a href="#dom-screen-availwidth" title="dom-Screen-availWidth">availWidth</a>;
504 readonly attribute double <a href="#dom-screen-availwidth" title="dom-Screen-availWidth">availHeight</a>;
505 readonly attribute double <a href="#dom-screen-availwidth" title="dom-Screen-availWidth">width</a>;
506 readonly attribute double <a href="#dom-screen-availwidth" title="dom-Screen-availWidth">height</a>;
507 readonly attribute unsigned long <a href="#dom-screen-availwidth" title="dom-Screen-availWidth">colorDepth</a>;
508 readonly attribute unsigned long <a href="#dom-screen-availwidth" title="dom-Screen-availWidth">pixelDepth</a>;
509 };</pre>
511 <p>The <dfn id="dom-screen-availwidth" title="dom-Screen-availWidth"><code>availWidth</code></dfn> attribute must return the available width of the rendering surface of the output
512 device.</p>
514 <p>The <dfn id="dom-screen-availheight" title="dom-Screen-availHeight"><code>availHeight</code></dfn> attribute must return the available height of the rendering surface of the output
515 device.</p>
517 <p>The <dfn id="dom-screen-width" title="dom-Screen-width"><code>width</code></dfn> attribute must return the width of the output device.</p>
519 <p>The <dfn id="dom-screen-height" title="dom-Screen-height"><code>height</code></dfn> attribute must return the height of the output device.</p>
521 <p>The <dfn id="dom-screen-colordepth" title="dom-Screen-colorDepth"><code>colorDepth</code></dfn> attribute must return the number of bits allocated to
522 colors (i.e. excluding the alpha channel) in the output device. If no
523 bits are allocated to colors in the output device this attribute
524 must return zero.</p>
526 <p>The <dfn id="dom-screen-pixeldepth" title="dom-Screen-pixelDepth"><code>pixelDepth</code></dfn> attribute must return the value returned by the <code>colorDepth</code> attributed.</p>
529 <h2 id="extensions-to-the-document-interface"><span class="secno">6 </span>Extensions to the <code title="">Document</code> Interface</h2>
531 <pre class="idl">partial interface <a class="external" href="http://dom.spec.whatwg.org/#document">Document</a> {
532 Element? elementFromPoint(double x, double y);
533 CaretPosition? caretPositionFromPoint(double x, double y);
534 };</pre>
536 <p>The <dfn id="dom-document-elementfrompoint" title="dom-Document-elementFromPoint"><code>elementFromPoint(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must return the element at
537 coordinates <var title="">x</var>,<var title="">y</var> in the <a href="#viewport">viewport</a>. The element to be returned is determined
538 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
539 bar (if any), or <var title="">y</var> is greater than the <a href="#viewport">viewport</a> height excluding the size of a rendered scroll bar (if any), the method must
540 return null. If there is no element at the given position the method must return the root element, if any, or null otherwise. If there is no
541 <a href="#viewport">viewport</a> associated with the document, the method must return null.</p>
543 <p>The <dfn id="dom-document-caretpositionfrompoint" title="dom-Document-caretPositionFromPoint"><code>caretPositionFromPoint(<var title="">x</var>, <var title="">y</var>)</code></dfn> method must return the
544 result of running these steps:</p>
545 <ol>
546 <li><p>If there is no <a href="#viewport">viewport</a> associated with the document, return null.
547 <li><p>If either argument is negative, <var title="">x</var> is greater
548 than the <a href="#viewport">viewport</a> width excluding the size of a rendered
549 scroll bar (if any), <var title="">y</var> is greather than the
550 <a href="#viewport">viewport</a> height excluding the size of a rendered scroll bar
551 (if any) return null.</li>
552 <li><p>If at the coordinates <var title="">x</var>,<var title="">y</var>
553 in the <a href="#viewport">viewport</a> no text insertion point indicator would have
554 been inserted return null.</li>
555 <li>
556 <p>If at the coordinates <var title="">x</var>,<var title="">y</var>
557 in the <a href="#viewport">viewport</a> a text insertion point indicator would have
558 been inserted in a text entry widget which is also a replaced element
559 return a <a href="#caret-position">caret position</a> with its properties set as
560 follows:</p>
561 <dl>
562 <dt><a href="#caret-node">caret node</a></dt>
563 <dd><p>The node corresponding to the text entry widget.</dd>
564 <dt><a href="#caret-offset">caret offset</a></dt>
565 <dd><p>The amount of 16-bit units to the left of where the
566 text insertion point indicator would have inserted.</dd>
567 <dt><a href="#caret-range">caret range</a></dt>
568 <dd><p>null</dd>
569 </dl>
570 </li>
571 <li>
572 <p>Otherwise, return a <a href="#caret-position">caret position</a> where the
573 <a href="#caret-range">caret range</a> is a collapsed
574 <code class="external"><a href="http://dom.spec.whatwg.org/#range">Range</a></code> object for the position
575 where the text insertion point indicator would have been inserted and
576 the other properties are set as follows:</p>
577 <dl>
578 <dt><a href="#caret-node">caret node</a></dt>
579 <dd><p>The <code class="external" title="dom-Range-startContainer"><a href="http://dom.spec.whatwg.org/#dom-range-startcontainer">startContainer</a></code>
580 of the <a href="#caret-range">caret range</a>.</dd>
581 <dt><a href="#caret-offset">caret offset</a></dt>
582 <dd><p>The <code class="external" title="dom-Range-startOffset"><a href="http://dom.spec.whatwg.org/#dom-range-startoffset">startOffset</a></code> of
583 the <a href="#caret-range">caret range</a>.</p>
584 </dl>
585 </li>
586 </ol>
587 <p class="note">The specifics of hit testing are out of scope of this
588 specification and therefore the exact details of
589 <code title="dom-Document-elementFromPoint"><a href="#dom-document-elementfrompoint">elementFromPoint()</a></code> and
590 <code title="dom-Document-caretPositionFromPoint"><a href="#dom-document-caretpositionfrompoint">caretPositionFromPoint()</a></code>
591 are therefore too. Hit testing will hopefully be defined in a future
592 revision of CSS or HTML.</p>
594 <h3 id="the-caretposition-interface"><span class="secno">6.1 </span>The <code title="">CaretPosition</code> Interface</h3>
596 <p>A <dfn id="caret-position">caret position</dfn> gives the position of a text insertion point indicator. It always has an associated
597 <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 <code><a href="#caretposition">CaretPosition</a></code> object.</p>
599 <pre class="idl">interface <dfn id="caretposition">CaretPosition</dfn> {
600 readonly attribute Node offsetNode;
601 readonly attribute unsigned long offset;
602 ClientRect? getClientRect();
603 };</pre>
605 <p>The <dfn id="dom-caretposition-offsetnode" title="dom-CaretPosition-offsetNode"><code>offsetNode</code></dfn> attribute must return the <a href="#caret-node">caret node</a>.</p>
607 <p>The <dfn id="dom-caretposition-offset" title="dom-CaretPosition-offset"><code>offset</code></dfn> attribute must return the <a href="#caret-offset">caret offset</a>.</p>
609 <p>The <dfn id="dom-caretposition-getclientrect" title="dom-CaretPosition-getClientRect"><code>getClientRect()</code></dfn> method must follow these steps, aborting on the first step that
610 returns a value:</p>
611 <ol>
612 <li>
613 <p>If <a href="#caret-range">caret range</a> is not null:
614 <ol>
615 <li><p>Let <var title="">list</var> be the result of invoking the
616 <code title="dom-Range-getClientRects"><a href="#dom-range-getclientrects">getClientRects()</a></code> method on the
617 range.
618 <li><p>If <var title="">list</var> is empty, return null.
619 <li><p>Return the <code><a href="#clientrect">ClientRect</a></code> object in <var title="">list</var> at index 0.
620 </ol>
621 <li><p>If <a href="#caret-node">caret node</a> is a text entry widget that is a replaced element,
622 and that is in the document, return a <code><a href="#clientrect">ClientRect</a></code> object for the caret
623 in the widget as represented by the <a href="#caret-offset">caret offset</a> value.
624 <li><p>Return null.
625 </ol>
627 <h2 id="extensions-to-the-element-interface"><span class="secno">7 </span>Extensions to the <code title="">Element</code> Interface</h2>
629 <pre class="idl">partial interface <a class="external" href="http://dom.spec.whatwg.org/#element">Element</a> {
630 <a href="#clientrectlist">ClientRectList</a> <a href="#dom-element-getclientrects" title="dom-Element-getClientRects">getClientRects</a>();
631 <a href="#clientrect">ClientRect</a> <a href="#dom-element-getboundingclientrect" title="dom-Element-getBoundingClientRect">getBoundingClientRect</a>();
632 void <a href="#dom-element-scrollintoview" title="dom-Element-scrollIntoView">scrollIntoView</a>(optional boolean top, optional <a href="#scrolloptions">ScrollOptions</a> options);
633 attribute (double or <a href="#scrolloptions">ScrollOptions</a>) <a href="#dom-element-scrolltop" title="dom-Element-scrollTop">scrollTop</a>;
634 attribute (double or <a href="#scrolloptions">ScrollOptions</a>) <a href="#dom-element-scrollleft" title="dom-Element-scrollLeft">scrollLeft</a>;
635 readonly attribute double <a href="#dom-element-scrollwidth" title="dom-Element-scrollWidth">scrollWidth</a>;
636 readonly attribute double <a href="#dom-element-scrollheight" title="dom-Element-scrollHeight">scrollHeight</a>;
637 readonly attribute double <a href="#dom-element-clienttop" title="dom-Element-clientTop">clientTop</a>;
638 readonly attribute double <a href="#dom-element-clientleft" title="dom-Element-clientLeft">clientLeft</a>;
639 readonly attribute double <a href="#dom-element-clientwidth" title="dom-Element-clientWidth">clientWidth</a>;
640 readonly attribute double <a href="#dom-element-clientheight" title="dom-Element-clientHeight">clientHeight</a>;
641 };</pre>
643 <p>The <dfn id="dom-element-getclientrects" title="dom-Element-getClientRects"><code>getClientRects()</code></dfn> method, when invoked, must return the result of the following algorithm:</p>
644 <ol>
645 <li><p>If the element on which it was invoked does not have an associated
646 <a href="#css-layout-box">CSS layout box</a> and is not in the <code>http://www.w3.org/2000/svg</code>
647 namespace return an empty <code><a href="#clientrectlist">ClientRectList</a></code> object and stop
648 this algorithm.</li>
649 <li><p>If the element does not have an associated <a href="#css-layout-box">CSS layout box</a> and is
650 in the <code>http://www.w3.org/2000/svg</code> namespace return a
651 <code><a href="#clientrectlist">ClientRectList</a></code> object containing a single
652 <code><a href="#clientrect">ClientRect</a></code> object that describes the bounding box of the
653 element as defined by the SVG specification.
654 <a href="#refsSVG">[SVG]</a></li>
655 <li>
656 <p>Return a <code><a href="#clientrectlist">ClientRectList</a></code> object containing a list of
657 <code><a href="#clientrect">ClientRect</a></code> objects in content order describing the border
658 boxes (including those with a height or width of zero) with the
659 following constraints:</p>
660 <ul>
661 <li><p>If the element on which the method was invoked has a computed
662 value for <code>display</code> property of <code>table</code> or
663 <code>inline-table</code> include both the table box and the caption
664 box, if any, but not the anonymous container box.</li>
665 <li><p>Replace each
666 <a href="http://www.w3.org/TR/CSS21/visuren.html#anonymous-block-level">anonymous
667 block box</a> with its child box(es) and repeat this until no anonymous
668 block boxes are left in the final list.</li>
669 </ul>
670 </li>
671 </ol>
673 <p>The <dfn id="dom-element-getboundingclientrect" title="dom-Element-getBoundingClientRect"><code>getBoundingClientRect()</code></dfn> method, when invoked, must return the result of the following
674 algorithm:</p>
675 <ol>
676 <li><p>Let <var title="">list</var> be the result of invoking
677 <code title="dom-Element-getClientRects"><a href="#dom-element-getclientrects">getClientRects()</a></code> on the
678 same element this method was invoked on.</li>
679 <li><p>If the <var title="">list</var> is empty return a <code><a href="#clientrect">ClientRect</a></code>
680 object whose <code title="dom-ClientRect-top"><a href="#dom-clientrect-top">top</a></code>,
681 <code title="dom-ClientRect-right"><a href="#dom-clientrect-right">right</a></code>,
682 <code title="dom-ClientRect-bottom"><a href="#dom-clientrect-bottom">bottom</a></code> and
683 <code title="dom-ClientRect-left"><a href="#dom-clientrect-left">left</a></code> members are zero.</li>
684 <li><p>Otherwise, return a <code><a href="#clientrect">ClientRect</a></code> object describing the
685 smallest rectangle that includes the first rectangle in <var title="">list</var>
686 and all of the remaining rectangles of which the height or width is not
687 zero.</li>
688 </ol>
689 <div class="example">
690 <p>The following snippet gets the dimensions of the first
691 <code>div</code> element in a document:</p>
692 <pre><code>var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
694 var exampleWidth = example.width;
696 var exampleHeight = example.height;</code></pre>
697 </div>
699 <p>The <dfn id="dom-element-scrollintoview" title="dom-Element-scrollIntoView"><code>scrollIntoView(<var title="">top</var>, <var title="">options</var>)</code></dfn> method must run these steps:</p>
700 <ol>
701 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a> terminate these steps.</li>
702 <li><p><a href="#scroll-an-element-into-view" title="scroll an element into view">Scroll the element into view</a> with the
703 <i title="">align to top flag</i> set if <var title="">top</var> is true or omitted, and the scroll behavior being the value of the <code title="">behavior</code>
704 dictionary member of <var title="">options</var>.</li>
705 </ol>
707 <p>The <dfn id="dom-element-scrolltop" title="dom-Element-scrollTop"><code>scrollTop</code></dfn> attribute must return the result of running these steps:</p>
708 <ol>
709 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a> or the
710 element is the root element and the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in
711 <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a> return zero and terminate these steps.</li>
712 <li><p>If the element is the root element return the value of
713 <code title="dom-Window-scrollY"><a href="#dom-window-scrolly">scrollY</a></code>.</li>
714 <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>,
715 the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, and the element
716 does not have any overflow, return the value of
717 <code title="dom-Window-scrollY"><a href="#dom-window-scrolly">scrollY</a></code>.</li>
718 <li><p>Return the y-coordinate of the <a href="#scrolling-area">scrolling area</a> at the
719 alignment point with the top of the <a href="#padding-edge">padding edge</a> of the
720 element.</li>
721 </ol>
722 <p>When setting the <code title="dom-Element-scrollTop"><a href="#dom-element-scrolltop">scrollTop</a></code> attribute these steps must be run:</p>
723 <ol>
724 <li><p>If the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, and the <code title="">y</code> dictionary member is not present, abort these steps.
725 <li><p>If the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, let <var title="">y</var> be the value of the <code title="">y</code> dictionary member. Otherwise,
726 let <var title="">y</var> be the given value.</li>
727 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a>, the
728 element is the root element and the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in
729 <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, or the element has no overflow, terminate these
730 steps.</li>
731 <li><p>If the element is the root element invoke
732 <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> with zero as first
733 argument and <var title="">y</var> as second, and, if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, the given value as the third argument.</li>
734 <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>,
735 the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, and the element
736 does not have any vertical overflow, invoke
737 <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> with
738 <code title="dom-Window-scrollX"><a href="#dom-window-scrollx">scrollX</a></code> as first
739 argument and <var title="">y</var> as second, and, if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, the given value as the third argument.</li>
740 <li><p><a href="#scroll-an-element" title="scroll an element">Scroll the element</a> to
741 <code title="dom-Element-scrollLeft"><a href="#dom-element-scrollleft">scrollLeft</a></code>,<var title="">y</var>, with the scroll behavior being the value of the <code title="">behavior</code> dictionary
742 member if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, or <code title="">auto</code> otherwise.
743 </ol>
745 <p>The <dfn id="dom-element-scrollleft" title="dom-Element-scrollLeft"><code>scrollLeft</code></dfn> attribute must return the result of running these steps:</p>
746 <ol>
747 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a> or the
748 element is the root element and the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in
749 <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a> return zero and terminate these steps.</li>
750 <li><p>If the element is the root element return the value of
751 <code title="dom-Window-scrollX"><a href="#dom-window-scrollx">scrollX</a></code>.</li>
752 <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>,
753 the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, and the element
754 does not have any overflow, return the value of
755 <code title="dom-Window-scrollX"><a href="#dom-window-scrollx">scrollX</a></code>.</li>
756 <li><p>Return the x-coordinate of the <a href="#scrolling-area">scrolling area</a> at the
757 alignment point with the left of the <a href="#padding-edge">padding edge</a> of the
758 element.</li>
759 </ol>
760 <p>When setting the <code title="dom-Element-scrollLeft"><a href="#dom-element-scrollleft">scrollLeft</a></code> attribute these steps must be run:</p>
761 <ol>
762 <li><p>If the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, and the <code title="">x</code> dictionary member is not present, abort these steps.
763 <li><p>If the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, let <var title="">x</var> be the value of the <code title="">x</code> dictionary member. Otherwise,
764 let <var title="">x</var> be the given value.</li>
765 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a>, the
766 element is the root element and the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in
767 <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, or the element has no overflow, terminate these
768 steps.</li>
769 <li><p>If the element is the root element invoke
770 <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> with
771 <var title="">x</var> as first argument and zero as second, and, if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, the given value as the third
772 argument.</li>
773 <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>,
774 the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>, and the element
775 does not have any vertical overflow, invoke
776 <code title="dom-Window-scroll"><a href="#dom-window-scroll">scroll()</a></code> with
777 <var title="">x</var> as first argument and
778 <code title="dom-Window-scrollY"><a href="#dom-window-scrolly">scrollY</a></code> as second, and, if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, the given value as the third
779 argument.</li>
780 <li><p><a href="#scroll-an-element" title="Scroll an element">Scroll the element</a> to
781 <var title="">x</var>,<code title="dom-Element-scrollTop"><a href="#dom-element-scrolltop">scrollTop</a></code>, with the scroll behavior being the value of the <code title="">behavior</code> dictionary
782 member if the given value is a <code><a href="#scrolloptions">ScrollOptions</a></code> object, or <code title="">auto</code> otherwise.
783 </ol>
785 <p>The <dfn id="dom-element-scrollwidth" title="dom-Element-scrollWidth"><code>scrollWidth</code></dfn> attribute must return the result of running these steps:</p>
786 <ol>
787 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a> return
788 zero and terminate these steps.</li>
789 <li><p>Let <var title="">viewport width</var> be the width of the <a href="#viewport">viewport</a> excluding the width of the scroll bar, if any, or zero if there is no
790 <a href="#viewport">viewport</a>.
791 <li><p>If the element is the root element and the
792 <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is not in
793 <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>
794 return max(<a href="#document-content">document content</a> width, <var title="">viewport width</var>).</li>
795 <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>
796 and the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in
797 <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>
798 return max(<a href="#document-content">document content</a> width, <var title="">viewport width</var>).</li>
799 <li><p>Return the width of the element's <a href="#scrolling-area">scrolling area</a>.</li>
800 </ol>
802 <p>The <dfn id="dom-element-scrollheight" title="dom-Element-scrollHeight"><code>scrollHeight</code></dfn> attribute must return the result of running these steps:</p>
803 <ol>
804 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a> return
805 zero and terminate these steps.</li>
806 <li><p>Let <var title="">viewport height</var> be the height of the <a href="#viewport">viewport</a> excluding the height of the scroll bar, if any, or zero if there is no
807 <a href="#viewport">viewport</a>.
808 <li><p>If the element is the root element and the
809 <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is not in
810 <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>
811 return max(<a href="#document-content">document content</a> height, <var title="">viewport height</var>).</li>
812 <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>
813 and the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> is in
814 <a class="external" href="http://dom.spec.whatwg.org/#concept-document-quirks" title="concept-document-quirks">quirks mode</a>
815 return max(<a href="#document-content">document content</a> height, <var title="">viewport height</var>).</li>
816 <li><p>Return the height of the element's <a href="#scrolling-area">scrolling area</a>.</li>
817 </ol>
819 <p>The <dfn id="dom-element-clienttop" title="dom-Element-clientTop"><code>clientTop</code></dfn> attribute must run these steps:
820 <ol>
821 <li><p>If the element has no associated <a href="#css-layout-box">CSS layout box</a> or if the <a href="#css-layout-box">CSS layout box</a> is inline, return zero.
822 <li><p>Return the computed value of the '<code>border-top-width</code>' property plus the height of any scrollbar rendered between the top <a href="#padding-edge">padding
823 edge</a> and the top <a href="#border-edge">border edge</a>.
824 </ol>
826 <p>The <dfn id="dom-element-clientleft" title="dom-Element-clientLeft"><code>clientLeft</code></dfn> attribute must run these steps:
827 <ol>
828 <li><p>If the element has no associated <a href="#css-layout-box">CSS layout box</a> or if the <a href="#css-layout-box">CSS layout box</a> is inline, return zero.
829 <li><p>Return the computed value of the '<code>border-left-width</code>' property plus the width of any scrollbar rendered between the left <a href="#padding-edge">padding
830 edge</a> and the left <a href="#border-edge">border edge</a>.
831 </ol>
833 <p>The <dfn id="dom-element-clientwidth" title="dom-Element-clientWidth"><code>clientWidth</code></dfn> attribute must run these steps:
834 <ol>
835 <li><p>If the element has no associated <a href="#css-layout-box">CSS layout box</a> or if the <a href="#css-layout-box">CSS layout box</a> is inline, return zero.
836 <li><p>If the element is the root element and the element's document's <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#browsing-context">browsing context</a> is a
837 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#top-level-browsing-context">top-level browsing context</a>, return the <a href="#viewport">viewport</a> width excluding the size of a rendered scroll bar (if
838 any).
839 <li><p>Return the width of the <a href="#padding-edge">padding edge</a> excluding the width of any rendered scrollbar between the <a href="#padding-edge">padding edge</a> and the
840 <a href="#border-edge">border edge</a>.
841 </ol>
843 <p>The <dfn id="dom-element-clientheight" title="dom-Element-clientHeight"><code>clientHeight</code></dfn> attribute must run these steps:
844 <ol>
845 <li><p>If the element has no associated <a href="#css-layout-box">CSS layout box</a> or if the <a href="#css-layout-box">CSS layout box</a> is inline, return zero.
846 <li><p>If the element is the root element and the element's document's <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#browsing-context">browsing context</a> is a
847 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#top-level-browsing-context">top-level browsing context</a>, return the <a href="#viewport">viewport</a> height excluding the size of a rendered scroll bar (if any).
848 <li><p>Return the height of the <a href="#padding-edge">padding edge</a> excluding the height of any rendered scrollbar between the <a href="#padding-edge">padding edge</a> and the
849 <a href="#border-edge">border edge</a>.
850 </ol>
852 <h3 id="the-getclientrects-and-getboundingclientrect-methods"><span class="secno">7.1 </span>The <code title="">getClientRects()</code> and
853 <code title="">getBoundingClientRect()</code> methods</h3>
855 <p>The <code title="dom-Element-getClientRects"><a href="#dom-element-getclientrects">getClientRects()</a></code> and <code title="dom-Element-getBoundingClientRect"><a href="#dom-element-getboundingclientrect">getBoundingClientRect()</a></code>
856 methods provide information about the position of the border box edges of
857 an element relative to the viewport. The objects these methods return
858 must be static. That is, changes to the underlying
859 document are not reflected in the objects.</p>
861 <h3 id="element-scrolling-members"><span class="secno">7.2 </span><code title="">Element</code> Scrolling Members</h3>
863 <p>To <dfn id="scroll-an-element-into-view">scroll an element into view</dfn>, optionally with an
864 <i title="">align to top flag</i> set, and with a scroll behavior <var title="">behavior</var>, means to run these steps for each
865 ancestor element or <a href="#viewport">viewport</a> that establishes a
866 scrolling box <var title="">box</var>, in order of innermost to outermost scrolling box:</p>
868 <ol>
869 <li><p>If the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> associated
870 with the element to be
871 scrolled into view is not <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/origin-0.html#same-origin">same origin</a> with the
872 <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> associated with the element or
873 <a href="#viewport">viewport</a> associated with <var title="">box</var>, terminate these
874 steps.</li>
876 <li><p>Let <var title="">position</var> be the scroll position <var title="">box</var> would have by following these steps:
878 <ol>
879 <li><p>If the <i title="">align to top flag</i> is set align the top of
880 the border box of the element to be scrolled into view with the top of
881 <var title="">box</var>.</li>
883 <li><p>Otherwise, if the <i title="">align to top flag</i> is not set
884 align the bottom of the border box of the element to be scrolled into
885 view with the bottom of <var title="">box</var>.</li>
887 <li><p>Align the left of the border box of the element to be scrolled
888 into view with the left of <var title="">box</var>.</li>
889 <!-- RTL is not special cased in implementations?! -->
890 </ol>
892 <li><p>If <var title="">position</var> is the same as <var title="">box</var>'s current scroll position, and <var title="">box</var> does not have an ongoing
893 <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a>, abort these steps.
895 <li>
896 <dl class="switch">
897 <dt>If <var title="">box</var> is associated with an element</dt>
898 <dd>
899 <p>Let <var title="">element</var> be the element.
900 <p>Let <var title="">task</var> be these steps:
901 <ol>
902 <li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a>
903 named <code title="event-scroll">scroll</code> at the element
904 associated <var title="">box</var>.</p>
905 </ol>
906 </dd>
908 <dt>If <var title="">box</var> is associated with a <a href="#viewport">viewport</a></dt>
909 <dd>
910 <p>Let <var title="">element</var> be the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code>'s root element as the associated element, if there is one, or
911 <code>null</code> otherwise.
912 <p>Let <var title="">task</var> be these steps:
913 <ol>
914 <li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a>
915 named <code title="event-scroll">scroll</code> that bubbles at the
916 <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> object associated with the <a href="#viewport">viewport</a>.</p>
917 </ol>
918 </dd>
919 </dl>
920 </li>
921 <li><p><a href="#perform-a-scroll">Perform a scroll</a> of <var title="">box</var> to <var title="">position</var>, with the set of steps <var title="">task</var>,
922 <var title="">element</var> as the associated element and <var title="">behavior</var> as the scroll behavior.
924 </ol>
926 <p>To <dfn id="scroll-an-element">scroll an element</dfn> to <var title="">x</var>,<var title="">y</var> with a scroll behavior <var title="">behavior</var> means to:</p>
928 <ol>
929 <li><p>Let <var title="">element</var> be the element.
930 <li><p>Let <var title="">box</var> be <var title="">element</var>'s associated scrolling box.
931 <li>
932 <dl class="switch">
933 <dt>If <var title="">element</var> can have overflow to the right</dt>
935 <dd><p>Let <var title="">x</var> be max(0, min(<var title="">x</var>,
936 <a href="#scrolling-area">scrolling area</a> width -
937 <a href="#padding-edge">padding edge</a> width)).</dd>
939 <dt>If <var title="">element</var> can have overflow to the left (under right-to-left
940 conditions)</dt>
942 <dd><p>Let <var title="">x</var> be min(0, max(<var title="">x</var>,
943 <a href="#padding-edge">padding edge</a> width -
944 <a href="#scrolling-area">scrolling area</a> width)).</dd>
945 </dl>
946 </li>
948 <li><p>Let <var title="">y</var> be max(0, min(<var title="">y</var>,
949 <a href="#scrolling-area">scrolling area</a> height - <a href="#padding-edge">padding edge</a> height)).</li>
951 <li><p>Let <var title="">position</var> be the scroll position <var title="">box</var> would have by aligning <a href="#scrolling-area">scrolling area</a> x-coordinate
952 <var title="">x</var> with the left of <var title="">box</var> and aligning <a href="#scrolling-area">scrolling area</a> y-coordinate <var title="">y</var> with
953 the top of <var title="">box</var>.
955 <li><p>If <var title="">position</var> is the same as <var title="">box</var>'s current scroll position, and <var title="">box</var> does not have an ongoing
956 <a href="#concept-smooth-scroll" title="concept-smooth-scroll">smooth scroll</a>, abort these steps.
958 <li><p>Let <var title="">task</var> be these steps:
959 <ol>
960 <li><p><a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">Fire an event</a> named
961 <code title="event-scroll">scroll</code> at the element.</li>
962 </ol>
964 <li><p><a href="#perform-a-scroll">Perform a scroll</a> of <var title="">box</var> to <var title="">position</var>, with the set of steps <var title="">task</var>,
965 <var title="">element</var> as the associated element and <var title="">behavior</var> as the scroll behavior.
967 </ol>
970 <h2 id="extensions-to-the-htmlelement-interface"><span class="secno">8 </span>Extensions to the <code title="">HTMLElement</code> Interface</h2>
972 <pre class="idl">partial interface <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#htmlelement">HTMLElement</a> {
973 readonly attribute <a class="external" href="http://dom.spec.whatwg.org/#element">Element</a> <a href="#dom-htmlelement-offsetparent" title="dom-HTMLElement-offsetParent">offsetParent</a>;
974 readonly attribute double <a href="#dom-htmlelement-offsettop" title="dom-HTMLElement-offsetTop">offsetTop</a>;
975 readonly attribute double <a href="#dom-htmlelement-offsetleft" title="dom-HTMLElement-offsetLeft">offsetLeft</a>;
976 readonly attribute double <a href="#dom-htmlelement-offsetwidth" title="dom-HTMLElement-offsetWidth">offsetWidth</a>;
977 readonly attribute double <a href="#dom-htmlelement-offsetheight" title="dom-HTMLElement-offsetHeight">offsetHeight</a>;
978 };</pre>
980 <p>The <dfn id="dom-htmlelement-offsetparent" title="dom-HTMLElement-offsetParent"><code>offsetParent</code></dfn> attribute must return the result of running these steps:</p>
981 <ol>
982 <li>
983 <p>If any of the following holds true return null and terminate this
984 algorithm:</p>
985 <ul>
986 <li>The element does not have an associated <a href="#css-layout-box">CSS layout box</a>.</li>
987 <li>The element is the root element.</li>
988 <li>The element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>.</li>
989 <li>The element's computed value of the '<code>position</code>' property is <code>fixed</code>.</li>
990 </ul>
991 </li>
992 <li>
993 <p>Return the nearest ancestor element of the element for which at least
994 one of the following is true and terminate this algorithm if such an
995 ancestor is found:</p>
996 <ul>
997 <li>The computed value of the '<code>position</code>' property is not <code>static</code>.</li>
998 <li>It is <a href="#the-html-body-element">the HTML <code>body</code> element</a>.</li>
999 <li>The computed value of the '<code>position</code>' property of
1000 the element is <code>static</code> and the ancestor is one of the
1001 following <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#html-elements" title="HTML elements">HTML elements</a>:
1002 <code>td</code>, <code>th</code>, or <code>table</code>.</li>
1003 </ul>
1004 </li>
1005 <li><p>Return null.</li>
1006 </ol>
1008 <p>The <dfn id="dom-htmlelement-offsettop" title="dom-HTMLElement-offsetTop"><code>offsetTop</code></dfn> attribute must return the result of running these steps:</p>
1009 <ol>
1010 <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code> element</a>
1011 or does not have any associated <a href="#css-layout-box">CSS layout box</a> return zero and terminate
1012 this algorithm.</li>
1013 <li><p>If the <code title="dom-HTMLElement-offsetParent"><a href="#dom-htmlelement-offsetparent">offsetParent</a></code> of the element is null return the
1014 y-coordinate of the top <a href="#border-edge">border edge</a> of the first
1015 <a href="#css-layout-box">CSS layout box</a> associated with the element, relative to the
1016 <a href="#initial-containing-block">initial containing block</a> origin, and terminate this
1017 algorithm.</li>
1018 <li>
1019 <p>Return the result of subtracting the y-coordinate of the top
1020 <a href="#padding-edge">padding edge</a> of the first <a href="#css-layout-box">CSS layout box</a> associated with
1021 the <code title="dom-HTMLElement-offsetParent"><a href="#dom-htmlelement-offsetparent">offsetParent</a></code> of the element from the y-coordinate of
1022 the top <a href="#border-edge">border edge</a> of the first <a href="#css-layout-box">CSS layout box</a> associated
1023 with the element, relative to the <a href="#initial-containing-block">initial containing block</a>
1024 origin.</p>
1025 <p class="note">An inline element that consists of multiple line boxes
1026 will only have its first <a href="#css-layout-box">CSS layout box</a> considered.</p>
1027 </li>
1028 </ol>
1030 <p>The <dfn id="dom-htmlelement-offsetleft" title="dom-HTMLElement-offsetLeft"><code>offsetLeft</code></dfn> attribute must return the result of running these steps:</p>
1031 <ol>
1032 <li><p>If the element is <a href="#the-html-body-element">the HTML <code>body</code>
1033 element</a> or does not have any associated <a href="#css-layout-box">CSS layout box</a> return zero
1034 and terminate this algorithm.</li>
1035 <li><p>If the <code title="dom-HTMLElement-offsetParent"><a href="#dom-htmlelement-offsetparent">offsetParent</a></code> of the element is null return the
1036 x-coordinate of the left <a href="#border-edge">border edge</a> of the first
1037 <a href="#css-layout-box">CSS layout box</a> associated with the element, relative to the
1038 <a href="#initial-containing-block">initial containing block</a> origin, and terminate this
1039 algorithm.</li>
1040 <li>
1041 <p>Return the result of subtracting the x-coordinate of the left
1042 <a href="#padding-edge">padding edge</a> of the first <a href="#css-layout-box">CSS layout box</a> associated with
1043 the <code title="dom-HTMLElement-offsetParent"><a href="#dom-htmlelement-offsetparent">offsetParent</a></code> of the element from the x-coordinate of
1044 the left <a href="#border-edge">border edge</a> of the first <a href="#css-layout-box">CSS layout box</a> associated
1045 with the element, relative to the <a href="#initial-containing-block">initial containing block</a>
1046 origin.</p>
1047 </li>
1048 </ol>
1050 <p>The <dfn id="dom-htmlelement-offsetwidth" title="dom-HTMLElement-offsetWidth"><code>offsetWidth</code></dfn> attribute must return the result of running these steps:</p>
1051 <ol>
1052 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a> return zero and terminate this algorithm.</li>
1053 <li><p>Return the <a href="#border-edge">border edge</a> width of the first <a href="#css-layout-box">CSS layout box</a> associated with the element.</li>
1054 </ol>
1056 <p>The <dfn id="dom-htmlelement-offsetheight" title="dom-HTMLElement-offsetHeight"><code>offsetHeight</code></dfn> attribute must return the result of running these steps:</p>
1057 <ol>
1058 <li><p>If the element does not have any associated <a href="#css-layout-box">CSS layout box</a> return zero and terminate this algorithm.</li>
1059 <li><p>Return the <a href="#border-edge">border edge</a> height of the first <a href="#css-layout-box">CSS layout box</a> associated with the element.</li>
1060 </ol>
1062 <h2 id="extensions-to-the-range-interface"><span class="secno">9 </span>Extensions to the <code title="">Range</code> Interface</h2>
1064 <p>The objects the methods described below return must
1065 be static.</p>
1067 <pre class="idl">partial interface <a class="external" href="http://dom.spec.whatwg.org/#range">Range</a> {
1068 ClientRectList getClientRects();
1069 ClientRect getBoundingClientRect();
1070 };</pre>
1072 <p>The <dfn id="dom-range-getclientrects" title="dom-Range-getClientRects"><code>getClientRects()</code></dfn> method, when invoked, must return an empty
1073 <code><a href="#clientrectlist">ClientRectList</a></code> object if the range is not in the document and
1074 otherwise a <code><a href="#clientrectlist">ClientRectList</a></code> object containing a list of
1075 <code><a href="#clientrect">ClientRect</a></code> objects in content order that matches the
1076 following constraints:</p>
1077 <ul>
1078 <li>For each element selected by the range, whose parent is not selected
1079 by the range, include the border boxes returned by invoking
1080 <code title="dom-Element-getClientRects"><a href="#dom-element-getclientrects">getClientRects()</a></code> on the
1081 element.</li>
1082 <li>For each <code>Text</code> node selected or partially selected by the
1083 range (including when the boundary-points are identical), include a
1084 <code><a href="#clientrect">ClientRect</a></code> object (for the part that is selected, not the
1085 whole line box). The bounds of these <code><a href="#clientrect">ClientRect</a></code> objects are
1086 computed using font metrics; thus, for horizontal writing, the vertical
1087 dimension of each box is determined by the font ascent and descent, and
1088 the horizontal dimension by the text advance width.</li>
1089 </ul>
1091 <p>The <dfn id="dom-range-getboundingclientrect" title="dom-Range-getBoundingClientRect"><code>getBoundingClientRect()</code></dfn> method, when invoked, must return the result of the following
1092 algorithm:</p>
1093 <ol>
1094 <li><p>Let <var title="">list</var> be the result of invoking
1095 <code title="dom-Range-getClientRects"><a href="#dom-range-getclientrects">getClientRects()</a></code> on the
1096 same range this method was invoked on.</li>
1097 <li><p>If <var title="">list</var> is empty return a
1098 <code><a href="#clientrect">ClientRect</a></code> object whose
1099 <code title="dom-ClientRect-top"><a href="#dom-clientrect-top">top</a></code>,
1100 <code title="dom-ClientRect-right"><a href="#dom-clientrect-right">right</a></code>,
1101 <code title="dom-ClientRect-bottom"><a href="#dom-clientrect-bottom">bottom</a></code> and
1102 <code title="dom-ClientRect-left"><a href="#dom-clientrect-left">left</a></code> members are zero.</li>
1103 <li><p>Otherwise, return a <code><a href="#clientrect">ClientRect</a></code> object describing the
1104 smallest rectangle that includes the first rectangle in <var title="">list</var>
1105 and all of the remaining rectangles of which the height or width is not
1106 zero.</li>
1107 </ol>
1109 <h2 id="extensions-to-the-mouseevent-interface"><span class="secno">10 </span>Extensions to the <code title="">MouseEvent</code> Interface</h2>
1111 <p class="XXX">The object IDL fragment redefines some members. Can we
1112 resolve this somehow?</p>
1114 <!-- x/y do not match IE in the position:relative case but do match other
1115 browsers -->
1117 <pre class="idl">partial interface <a href="#mouseevent">MouseEvent</a> {
1118 readonly attribute double <a href="#dom-mouseevent-screenx" title="dom-MouseEvent-screenX">screenX</a>;
1119 readonly attribute double <a href="#dom-mouseevent-screeny" title="dom-MouseEvent-screenY">screenY</a>;
1120 readonly attribute double <a href="#dom-mouseevent-pagex" title="dom-MouseEvent-pageX">pageX</a>;
1121 readonly attribute double <a href="#dom-mouseevent-pagey" title="dom-MouseEvent-pageY">pageY</a>;
1122 readonly attribute double <a href="#dom-mouseevent-clientx" title="dom-MouseEvent-clientX">clientX</a>;
1123 readonly attribute double <a href="#dom-mouseevent-clienty" title="dom-MouseEvent-clientY">clientY</a>;
1124 readonly attribute double <a href="#dom-mouseevent-x" title="dom-MouseEvent-x">x</a>;
1125 readonly attribute double <a href="#dom-mouseevent-y" title="dom-MouseEvent-y">y</a>;
1126 readonly attribute double <a href="#dom-mouseevent-offsetx" title="dom-MouseEvent-offsetX">offsetX</a>;
1127 readonly attribute double <a href="#dom-mouseevent-offsety" title="dom-MouseEvent-offsetY">offsetY</a>;
1128 };
1130 partial dictionary <a href="#mouseeventinit">MouseEventInit</a> {
1131 double screenX = 0;
1132 double screenY = 0;
1133 double pageX = 0;
1134 double pageY = 0;
1135 double clientX = 0;
1136 double clientY = 0;
1137 double x = 0;
1138 double y = 0;
1139 double offsetX = 0;
1140 double offsetY = 0;
1141 };</pre>
1143 <p>The <dfn id="dom-mouseevent-screenx" title="dom-MouseEvent-screenX"><code>screenX</code></dfn> attribute must return the x-coordinate of
1144 the position where the event occurred relative to the origin of the
1145 screen.</p>
1147 <p>The <dfn id="dom-mouseevent-screeny" title="dom-MouseEvent-screenY"><code>screenY</code></dfn> attribute must return the y-coordinate of
1148 the position where the event occurred relative to the origin of the
1149 screen.</p>
1151 <p>The <dfn id="dom-mouseevent-pagex" title="dom-MouseEvent-pageX"><code>pageX</code></dfn> attribute must return the horizontal coordinate of
1152 the position where the event occurred relative to
1153 the origin of the <a href="#initial-containing-block">initial containing block</a>.</p>
1155 <p>The <dfn id="dom-mouseevent-pagey" title="dom-MouseEvent-pageY"><code>pageY</code></dfn> attribute must return the y-coordinate of the
1156 position where the event occurred relative to the origin of the
1157 <a href="#initial-containing-block">initial containing block</a>.</p>
1159 <p>The <dfn id="dom-mouseevent-clientx" title="dom-MouseEvent-clientX"><code>clientX</code></dfn> attribute must return the x-coordinate of
1160 the position where the event occurred relative to the origin of the
1161 <a href="#viewport">viewport</a>.</p>
1163 <p>The <dfn id="dom-mouseevent-clienty" title="dom-MouseEvent-clientY"><code>clientY</code></dfn> attribute must return the y-coordinate of
1164 the position where the event occurred relative to the origin of the
1165 <a href="#viewport">viewport</a>.</p>
1167 <p>The <dfn id="dom-mouseevent-x" title="dom-MouseEvent-x"><code>x</code></dfn> attribute must return the value of <code title="dom-MouseEvent-clientX"><a href="#dom-mouseevent-clientx">clientX</a></code>.</p>
1169 <p>The <dfn id="dom-mouseevent-y" title="dom-MouseEvent-y"><code>y</code></dfn> attribute must return the value of <code title="dom-MouseEvent-clientY"><a href="#dom-mouseevent-clienty">clientY</a></code>.</p>
1171 <p>The <dfn id="dom-mouseevent-offsetx" title="dom-MouseEvent-offsetX"><code>offsetX</code></dfn> attribute must return the x-coordinate of
1172 the position where the event occurred relative to the origin of the
1173 <a href="#padding-edge">padding edge</a> of the target node.</p>
1175 <p>The <dfn id="dom-mouseevent-offsety" title="dom-MouseEvent-offsetY"><code>offsetY</code></dfn> attribute must return the y-coordinate of
1176 the position where the event occurred relative to the origin of the
1177 <a href="#padding-edge">padding edge</a> of the target node.</p>
1179 <h2 id="rectangles"><span class="secno">11 </span>Rectangles</h2>
1182 <h3 id="the-clientrectlist-interface"><span class="secno">11.1 </span>The <code title="">ClientRectList</code> Interface</h3>
1184 <p>The <code><a href="#clientrectlist">ClientRectList</a></code> interface consists of an ordered list of <code><a href="#clientrect">ClientRect</a></code> objects.</p>
1186 <pre class="idl">interface <dfn id="clientrectlist">ClientRectList</dfn> {
1187 readonly attribute unsigned long <a href="#dom-clientrectlist-length" title="dom-ClientRectList-length">length</a>;
1188 getter <a href="#clientrect">ClientRect</a> <a href="#dom-clientrectlist-item" title="dom-ClientRectList-item">item</a>(unsigned long index);
1189 };</pre>
1191 <p>The <dfn id="dom-clientrectlist-length" title="dom-ClientRectList-length"><code>length</code></dfn> attribute must return the total number of <code><a href="#clientrect">ClientRect</a></code> objects associated with
1192 the object.</p>
1194 <p>The <dfn id="dom-clientrectlist-item" title="dom-ClientRectList-item"><code>item(<var title="">index</var>)</code></dfn> method, when invoked, must throw an
1195 <code class="external"><a href="http://dom.spec.whatwg.org/#indexsizeerror">IndexSizeError</a></code> exception when <var title="">index</var> is
1196 greater than the number of <code><a href="#clientrect">ClientRect</a></code> objects associated with the object. Otherwise, the <code><a href="#clientrect">ClientRect</a></code> object at
1197 <var title="">index</var> must be returned.</p>
1199 <h3 id="the-clientrect-interface"><span class="secno">11.2 </span>The <code title="">ClientRect</code> Interface</h3>
1201 <p>Objects implementing the <code><a href="#clientrect">ClientRect</a></code> interface represent a rectangular box. The type of box is specified by the method that returns a
1202 <code><a href="#clientrect">ClientRect</a></code> object.</p>
1204 <pre class="idl">interface <dfn id="clientrect">ClientRect</dfn> {
1205 readonly attribute double <a href="#dom-clientrect-top" title="dom-ClientRect-top">top</a>;
1206 readonly attribute double <a href="#dom-clientrect-top" title="dom-ClientRect-top">right</a>;
1207 readonly attribute double <a href="#dom-clientrect-top" title="dom-ClientRect-top">bottom</a>;
1208 readonly attribute double <a href="#dom-clientrect-top" title="dom-ClientRect-top">left</a>;
1209 readonly attribute double <a href="#dom-clientrect-top" title="dom-ClientRect-top">width</a>;
1210 readonly attribute double <a href="#dom-clientrect-top" title="dom-ClientRect-top">height</a>;
1211 };</pre>
1213 <p>The <dfn id="dom-clientrect-top" title="dom-ClientRect-top"><code>top</code></dfn> attribute must return the y-coordinate, relative to the <a href="#viewport">viewport</a> origin, of the top of
1214 the rectangle box.</p>
1216 <p>The <dfn id="dom-clientrect-right" title="dom-ClientRect-right"><code>right</code></dfn> attribute must return the x-coordinate, relative to the <a href="#viewport">viewport</a> origin, of the
1217 right of the rectangle box.</p>
1219 <p>The <dfn id="dom-clientrect-bottom" title="dom-ClientRect-bottom"><code>bottom</code></dfn> attribute must return the y-coordinate, relative to the <a href="#viewport">viewport</a> origin, of the
1220 bottom of the rectangle box.</p>
1222 <p>The <dfn id="dom-clientrect-left" title="dom-ClientRect-left"><code>left</code></dfn> attribute must return the x-coordinate, relative to the <a href="#viewport">viewport</a> origin, of the left
1223 of the rectangle box.</p>
1225 <p>The <dfn id="dom-clientrect-width" title="dom-ClientRect-width"><code>width</code></dfn> attribute must return the width of the rectangle box.</p>
1226 <p class="note">This is identical to <code title="dom-ClientRect-right"><a href="#dom-clientrect-right">right</a></code> minus <code title="dom-ClientRect-left"><a href="#dom-clientrect-left">left</a></code>.</p>
1228 <p>The <dfn id="dom-clientrect-height" title="dom-ClientRect-height"><code>height</code></dfn> attribute must return the height of the rectangle box.</p>
1229 <p class="note">This is identical to <code title="dom-ClientRect-bottom"><a href="#dom-clientrect-bottom">bottom</a></code> minus <code title="dom-ClientRect-top"><a href="#dom-clientrect-top">top</a></code>.</p>
1232 <h2 id="events"><span class="secno">12 </span>Events</h2>
1234 <h3 id="resizing-viewports"><span class="secno">12.1 </span>Resizing viewports</h3>
1236 <p>Whenever a <a href="#viewport">viewport</a> has its width or height changed (e.g. as a result of the user resizing the browser window, or zooming in, or an
1237 <code>iframe</code> element's dimensions are changed), the user agent must <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> to
1238 <a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">fire an event</a> event named
1239 <code>resize</code> at the <code class="external"><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/browsers.html#window">Window</a></code> object associated with that
1240 <a href="#viewport">viewport</a>. If such a resize is ongoing over a period of time, the user agent must <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task" title="queue a task">queue</a> that
1241 task at a user agent-defined interval while the resize is ongoing.
1243 <h3 id="scrolling-0"><span class="secno">12.2 </span>Scrolling</h3>
1245 <p>Whenever a <a href="#viewport">viewport</a> gets scrolled in response to user interaction, the user agent must <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> to
1246 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/infrastructure.html#concept-event-fire" title="concept-event-fire">fire an event</a> named
1247 <code>scroll</code> that bubbles at the <code class="external"><a href="http://dom.spec.whatwg.org/#document">Document</a></code> object associated with that <a href="#viewport">viewport</a>. If such a scroll is
1248 ongoing over a period of time, the user agent must <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task" title="queue a task">queue</a> that task at a user agent-defined interval
1249 while the scroll is ongoing.
1251 <p>Whenever an element gets scrolled in response to user interaction, the user agent must <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task">queue a task</a> to
1252 <a class="external" href="http://dom.spec.whatwg.org/#concept-event-fire" title="concept-event-fire">fire an event</a> named
1253 <code>scroll</code> at the element. If such a scroll is ongoing over a period of time, the user agent must
1254 <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#queue-a-task" title="queue a task">queue</a> that task at a user agent-defined interval while the scroll is ongoing.
1257 <h2 id="css-properties"><span class="secno">13 </span>CSS properties</h2>
1259 <p class="XXX">The features in this section should be moved to some other specification.
1261 <h3 id="smooth-scrolling:-the-scroll-behavior-property"><span class="secno">13.1 </span>Smooth Scrolling: The '<code title="">scroll-behavior</code>' Property</h3>
1263 <pre class="propdef">Name: <dfn id="scroll-behavior">scroll-behavior</dfn>
1264 Value: instant | smooth
1265 Initial: instant
1266 Applies to: scrolling boxes
1267 Inherited: no
1268 Computed value: specified value
1269 Media: visual
1270 Animatable: no
1271 Canonical Order: per grammar
1272 </pre>
1274 <p>The '<code><a href="#scroll-behavior">scroll-behavior</a></code>' property specifies the scrolling behavior for a scrolling box, when scrolling happens due to navigation or CSSOM scrolling
1275 APIs. Scrolls that are performed by the user are not affected by this property. When this property is specified on the root element, it applies to the
1276 <a href="#viewport">viewport</a> instead.
1278 <dl>
1279 <dt>'<dfn id="scroll-behavior-instant" title="scroll-behavior-instant"><code>instant</code></dfn>'
1280 <dd><p>The scrolling box is scrolled in an instant fashion.
1282 <dt>'<dfn id="scroll-behavior-smooth" title="scroll-behavior-smooth"><code>smooth</code></dfn>'
1283 <dd><p>The scrolling box is scrolled in a smooth fashion using a user agent-defined timing function over a user agent-defined period of time. User agents
1284 should follow platform convensions, if any.
1285 </dl>
1287 <p>User agents may ignore this property.
1289 <h2 class="no-num" id="references">References</h2>
1290 <div id="anolis-references"><dl><dt id="refsCSSOM">[CSSOM]
1291 <dd><cite><a href="http://dev.w3.org/csswg/cssom/">CSS Object Model (CSSOM)</a></cite>, Glenn Adams and Simon Pieters. W3C.
1293 <dt id="refsDOM">[DOM]
1294 <dd><cite><a href="http://dom.spec.whatwg.org/">DOM</a></cite>, Anne van Kesteren, Aryeh Gregor and Ms2ger. WHATWG.
1296 <dt id="refsHTML">[HTML]
1297 <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/">HTML</a></cite>, Ian Hickson. WHATWG.
1299 <dt id="refsRFC2119">[RFC2119]
1300 <dd><cite><a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></cite>, Scott Bradner. IETF.
1302 <dt id="refsSVG">[SVG]
1303 <dd><cite><a href="http://www.w3.org/TR/SVG/">Scalable Vector Graphics (SVG)</a></cite>, O. Andersson, R. Berjon, E. Dahlström et al.. W3C.
1305 <dt id="refsWEBIDL">[WEBIDL]
1306 <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web IDL</a></cite>, Cameron McCormack. W3C.
1308 </dl></div>
1310 <h2 class="no-num" id="acknowledgments">Acknowledgments</h2>
1312 <p>The editors would like to thank
1314 Alexey Feldgendler,
1315 Björn Höhrmann,
1316 Dan Bates,
1317 David Vest,
1318 Garrett Smith,
1319 Hallvord R. M. Steen,
1320 Leif Arne Storset,
1321 Luiz Agostini,
1322 Maciej Stachowiak,
1323 Michael Dyck,
1324 Mike Wilson,
1325 Morten Stenshorne,
1326 Peter-Paul Koch,
1327 Rachel Kmetz,
1328 Robert O'Callahan,
1329 Sam Weinig,
1330 <!--Simon Pieters,-->
1331 Scott Johnson,
1332 Sylvain Galineau,
1333 Tarquin Wilton-Jones,
1334 Thomas Moore, and
1335 Xiaomei Ji<!-- should actually use real name here -->
1337 for their contributions to this document.</p>
1339 <p>Special thanks to the Microsoft employees who first implemented many of
1340 the features specified in this draft, which were first widely deployed by
1341 the Windows Internet Explorer browser.</p>
