cssom-view/Overview.src.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

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

mercurial