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

Overview.src.html

Latest commit

 

History

History
1356 lines (1043 loc) · 54 KB

Overview.src.html

File metadata and controls

1356 lines (1043 loc) · 54 KB
<em>and</em> the associated callback of that media query is the same as
<var title="">mq_callback</var>, terminate these steps.</p></li>
<li><p>Append the tuple of <var title="">parsed_mq_list</var> and
<var title="">mq_callback</var> to the
<span>list of media listeners</span>.</p></li>
</ol>
<p>The
<dfn id="dom-stylemedia-removemedialistener" title="dom-StyleMedia-removeMediaListener"><code>removeMediaListener(<var title="">mq_list</var>, <var title="">mq_callback</var>)</code></dfn>
method <em class="ct">must</em> run these steps:</p>
<ol>
<li><p>Let <var title="">parsed_mq_list</var> be the result of
<span title="parse a list of media queries">parsing</span>
<var title="">mq_list</var>.</p></li>
<li><p>If <span title="compare lists of media queries">comparing</span>
<var title="">parsed_mq_list</var> with any of the media queries in the
<span>list of media listeners</span> returns true <em>and</em> the
associated callback of that media query is the same as
<var title="">mq_callback</var>, remove the tuple of
<var title="">parsed_mq_list</var> and <var title="">mq_callback</var>
from the <span>list of media listeners</span>.</p></li>
</ol>
<p>If one or more lists of media queries in the
<span>list of media listeners</span> changes in evaluation then for
each list of media queries of which the evaluation changes, in the order
of the <span>list of media listeners</span>, <span>queue a task</span>
that invokes the associated callback, passing as argument whether the
list of media queries matches the state of the rendered
<code>Document</code> at the time the <span>task</span> was
<span title="queue a task">queued</span>.</p>
<div class="example">
<p>A simple piece of code that detects changes in the orientation of the
viewport can be written as follows:</p>
<pre><code>function handleOrientationChange(landscape) {
if(landscape)
&hellip;
else
&hellip;
}
styleMedia.addMediaListener("(orientation:landscape)", handleOrientationChange)</code></pre>
<p>A more generic handler for media query changes could be written as
follows:</p>
<pre><code>function handleMediaQueryChange(query, matches) {
&hellip;
}
function addMediaListener(query) {
styleMedia.addMediaListener(
query,
function(matches) { handleMediaQueryChange(query, matches) }
)
}</code></pre>
</div>
<h3 id="the-screen-interface">The <code title="">Screen</code> Interface</h3>
<p>As its name suggests, the <code>Screen</code> interface represents
information about the screen of the output device.</p>
<pre class="idl">interface <dfn id="screen">Screen</dfn> {
readonly attribute unsigned long <span>availWidth</span>;
readonly attribute unsigned long <span>availHeight</span>;
readonly attribute unsigned long <span>width</span>;
readonly attribute unsigned long <span>height</span>;
readonly attribute unsigned long <span>colorDepth</span>;
readonly attribute unsigned long <span>pixelDepth</span>;
};</pre>
<p>The <dfn id="dom-screen-availwidth"><code>availWidth</code></dfn>
attribute <em class="ct">must</em> return the available width of the
rendering surface of the output device.</p>
<p>The <dfn id="dom-screen-availheight"><code>availHeight</code></dfn>
attribute <em class="ct">must</em> return the available height of the
rendering surface of the output device.</p>
<p>The <dfn id="dom-screen-width"><code>width</code></dfn> attribute
<em class="ct">must</em> return the width of the output device.</p>
<p>The <dfn id="dom-screen-height"><code>height</code></dfn> attribute
<em class="ct">must</em> return the height of the output device.</p>
<p>The <dfn id="dom-screen-colordepth"><code>colorDepth</code></dfn> and
<dfn id="dom-screen-pixeldepth"><code>pixelDepth</code></dfn> attributes
<em class="ct">must</em> both return the number of bits allocated to
colors (i.e. excluding the alpha channel) in the output device. If the
output device does not support colors these attributes
<em class="ct">must</em> return zero.</p>
<!-- pixelDepth is not supported by Internet Explorer 7 -->
<h2 id="extensions-to-the-document-interface">Extensions to the <code title="">Document</code> Interface</h2>
<pre class="idl">[Supplemental] interface <span>Document</span> {
Element <span>elementFromPoint</span>(float <var title="">x</var>, float <var title="">y</var>);
<span>CaretPosition</span> <span>caretPositionFromPoint</span>(float <var title="">x</var>, float <var title="">y</var>);
};</pre>
<p>The
<dfn id="dom-document-elementfrompoint" title="elementfrompoint"><code>elementFromPoint(<var title="">x</var>,
<var title="">y</var>)</code></dfn> method, when invoked,
<em class="ct">must</em> return the element at coordinates
<var>x</var>,<var>y</var> in the <span>viewport</span>. The element to be
returned is determined 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 bar (if any), or
<var title="">y</var> is greather than the <span>viewport</span> height
excluding the size of a rendered scroll bar (if any), the method
<em class="ct">must</em> return <code>null</code>. If there is no element
at the given position the method <em class="ct">must</em> return the root
element, if any, or <code>null</code> otherwise.</p>
<p>The
<dfn id="dom-document-caretpositionfrompoint" title="caretpositionfrompoint"><code>caretPositionFromPoint(<var title="">x</var>,
<var title="">y</var>)</code></dfn> method, when invoked,
<em class="ct">must</em> return the result of running these steps:</p>
<ol>
<li><p>If either argument is negative, <var title="">x</var> is greater
than the <span>viewport</span> width excluding the size of a rendered
scroll bar (if any), <var title="">y</var> is greather than the
<span>viewport</span> height excluding the size of a rendered scroll bar
(if any) return null.</p></li>
<li><p>If at the coordinates <var title="">x</var>,<var title="">y</var>
in the <span>viewport</span> no text insertion point indicator would have
been inserted return null.</p></li>
<li>
<p>If at the coordinates <var title="">x</var>,<var title="">y</var>
in the <span>viewport</span> a text insertion point indicator would have
been inserted in a text entry widget which is also a replaced element
return a <span>caret position</span> with its properties set as
follows:</p>
<dl>
<dt><span>caret node</span></dt>
<dd><p>The node corresponding to the text entry widget.</p></dd>
<dt><span>caret offset</span></dt>
<dd><p>The amount of 16-bit units to the left of where the
text insertion point indicator would have inserted.</p></dd>
<dt><span>caret range</span></dt>
<dd><p>null</p></dd>
</dl>
</li>
<li>
<p>Otherwise, return a <span>caret position</span> where the
<span>caret range</span> is a collapsed <code>Range</code> object for
the position where the text insertion point indicator would have been
inserted and the other properties are set as follows:</p>
<dl>
<dt><span>caret node</span></dt>
<dd><p>The <code title="dom-Range-startContainer">startContainer</code>
of the <span>caret range</span>.</p></dd>
<dt><span>caret offset</span></dt>
<dd><p>The <code title="dom-Range-startOffset">startOffset</code> of
the <span>caret range</span>.</p>
</dl>
</li>
</ol>
<p class="note">The specifics of hit testing are out of scope of this
specification and therefore the exact details of
<code>elementFromPoint()</code> and <code>caretPositionFromPoint()</code>
are therefore too. Hit testing will hopefully be defined in a future
revision of CSS or HTML.</p>
<h3 id="the-caretposition-interface">The <code title="">CaretPosition</code> Interface</h3>
<p>A <dfn>caret position</dfn> gives the position of a
text insertion point indicator. It always has an associated
<dfn>caret node</dfn>, <dfn>caret offset</dfn>, and
<dfn>caret range</dfn>. It is represented by a <code>CaretPosition</code>
object.</p>
<pre class="idl">interface <dfn id="caretposition">CaretPosition</dfn> {
readonly attribute <span>Node</span> <span title="dom-CaretPosition-offsetNode">offsetNode</span>;
readonly attribute unsigned long <span title="dom-CaretPosition-offset">offset</span>;
readonly attribute <span>Range</span> <span title="dom-CaretPosition-range">range</span>;
};</pre>
<p>The
<dfn id="dom-caretposition-offsetnode" title="dom-CaretPosition-offsetNode"><code>offsetNode</code></dfn>
attribute <em class="ct">must</em> return the <span>caret node</span>.</p>
<p>The
<dfn id="dom-caretposition-offset" title="dom-CaretPosition-offset"><code>offset</code></dfn>
attribute <em class="ct">must</em> return the <span>caret offset</span>.</p>
<p>The
<dfn id="dom-caretposition-range" title="dom-CaretPosition-range"><code>range</code></dfn>
attribute <em class="ct">must</em> return the <span>caret range</span>.</p>
<!-- https://bugs.webkit.org/show_bug.cgi?id=27046 -->
<h2 id="extensions-to-the-element-interface">Extensions to the <code title="">Element</code> Interface</h2>
<pre class="idl">[Supplemental] interface <span>Element</span> {
<span>ClientRectList</span> <span>getClientRects</span>();
<span>ClientRect</span> <span>getBoundingClientRect</span>();
attribute long <span>scrollTop</span>; // scroll on setting
attribute long <span>scrollLeft</span>; // scroll on setting
readonly attribute long <span>scrollWidth</span>;
readonly attribute long <span>scrollHeight</span>;
readonly attribute long <span>clientTop</span>;
readonly attribute long <span>clientLeft</span>;
readonly attribute long <span>clientWidth</span>;
readonly attribute long <span>clientHeight</span>;
};</pre>
<h3>The <code title="">getClientRects()</code> and
<code title="">getBoundingClientRect()</code> methods</h3>
<p>The <code>getClientRects()</code> and <code>getBoundingClientRect</code>
methods provide information about the position of the border box edges of
an element relative to the viewport. The objects these methods return
<em class="ct">must</em> be static. That is, changes to the underlying
document are not reflected in the objects.</p>
<p>The
<dfn id="dom-element-getclientrects"><code>getClientRects()</code></dfn>
method, when invoked, <em class="ct">must</em> return the result of the
following algorithm:</p>
<ol>
<li><p>If the element on which it was invoked does not have an associated
CSS layout box and is not in the <code>http://www.w3.org/2000/svg</code>
namespace return an empty <code>ClientRectList</code> object and stop
this algorithm.</p></li>
<li><p>If the element does not have an associated CSS layout box and is
in the <code>http://www.w3.org/2000/svg</code> namespace return a
<code>ClientRectList</code> object containing a single
<code>ClientRect</code> object that describes the bounding box of the
element as defined by SVG specification.
[<cite><span>SVG</span></cite>]</p></li>
<li>
<p>Return a <code>ClientRectList</code> object containing a list of
<code>ClientRect</code> objects in content order describing the border
boxes (including those with a height or width of zero) with the
following constraints:</p>
<ul>
<li><p>If the element on which the method was invoked has a computed
value for <code>display</code> property of <code>table</code> or
<code>inline-table</code> include both the table box and the caption
box, if any, but not the anonymous container box.
[<cite><span>CSS21</span></cite>]</p></li>
<li><p>Replace each
<a href="http://www.w3.org/TR/CSS21/visuren.html#anonymous-block-level">anonymous
block box</a> with its child box(es) and repeat this until no anonymous
block boxes are left in the final list.
[<cite><span>CSS21</span></cite>]</p></li>
</ul>
</li>
</ol>
<p>The
<dfn id="dom-element-getboundingclientrect"><code>getBoundingClientRect()</code></dfn>
method, when invoked, <em class="ct">must</em> return the result of the
following algorithm:</p>
<ol>
<li><p>Let <var>list</var> be the result of invoking
<code>getClientRects()</code> on the same element this method was invoked
on.</p></li>
<li><p>If the <var>list</var> is empty return a <code>ClientRect</code>
object whose <code title="dom-clientrect-top">top</code>,
<code title="dom-clientrect-right">right</code>,
<code title="dom-clientrect-bottom">bottom</code> and
<code title="dom-clientrect-left">left</code> members are zero.</p></li>
<li><p>Otherwise, return a <code>ClientRect</code> object describing the
smallest rectangle that includes the first rectangle in <var>list</var>
and all of the remaining rectangles of which the height or width is not
zero.</p></li>
</ol>
<div class="example">
<p>The following snippet gets the dimensions of the first
<code>div</code> element in a document:</p>
<pre><code>var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
var exampleWidth = example.width;
var exampleHeight = example.height;</code></pre>
</div>
<h3 id="scroll-attributes">The <code title="">scrollTop</code>,
<code title="">scrollLeft</code>, <code title="">scrollWidth</code>, and
<code title="">scrollHeight</code> attributes</h3>
<p>The <dfn id="dom-element-scrolltop"><code>scrollTop</code></dfn>
attribute, when called on element <var>A</var>, <em class="ct">must</em>
return the value that is the result of running the following
algorithm:</p>
<ol>
<li><p>If <var>A</var> does not have an associated CSS layout box return
zero and stop this algorithm.</p></li>
<li><p>Return the y-coordinate of the <span>content</span> at the
alignment point with the top of the <span>content edge</span> of
<var>A</var>.</p></li>
</ol>
<p>When setting the <code>scrollTop</code> attribute to
<var title="">y</var> on element <var>A</var> user agents
<em class="ct">must</em> run the
following algorithm:</p>
<ol>
<li><p>If <var>A</var> does not have an associated CSS layout box or
vertical overflow stop this algorithm.</p></li>
<li><p>If <var title="">y</var> is infinite or NaN stop this
algorithm.</p>
<li><p>Let <var title="">y</var> be min(<var title="">y</var>,
<span>content</span> height - <span>content edge</span> height).</p></li>
<li><p>If <var title="">y</var> is negative let it be zero.</p></li>
<li><p>Align <span>content</span> y-coordinate <var title="">y</var> with
the top of the <span>content edge</span> of <var>A</var>.</p></li>
</ol>
<p>The <dfn id="dom-element-scrollleft"><code>scrollLeft</code></dfn>
attribute, when called on element <var>A</var>,
<em class="ct">must</em> return the value that is the result of running the
following algorithm:</p>
<ol>
<li><p>If <var>A</var> does not have an associated CSS layout box return
zero and stop this algorithm.</p></li>
<li><p>Return the x-coordinate of the <span>content</span> at the
alignment point with the left of the <span>content edge</span> of
<var>A</var>.</p></li>
</ol>
<p>When setting the <code>scrollLeft</code> attribute to <var title="">x</var>
on element <var>A</var> user agents <em class="ct">must</em> run the
following algorithm:</p>
<ol>
<li><p>If <var>A</var> does not have an associated CSS layout box or
horizontal overflow stop this algorithm.</p></li>
<li><p>If <var title="">x</var> is infinite or NaN stop this
algorithm.</p>
<li>
<dl>
<dt>If <var>A</var> can have overflow to the right
<dd>
<ol>
<li><p>Let <var title="">x</var> be min(<var title="">x</var>,
<span>content</span> width - <span>content edge</span>
width).</p></li>
<li><p>If <var title="">x</var> is negative let it be zero.</p></li>
</ol>
<dt>If <var>A</var> can have overflow to the left (under right-to-left
conditions)
<dd>
<ol>
<li><p>Let <var title="">x</var> be max(<var title="">x</var>,
<span>content edge</span> width - <span>content</span>
width).</p></li>
<li><p>If <var title="">x</var> is non-negative let it be
zero.</p></li>
</ol>
</dl>
<li><p>Align <span>content</span> x-coordinate <var title="">x</var> with
the left of the <span>content edge</span> of <var>A</var>.</p></li>
</ol>
<p>The <dfn id="dom-element-scrollwidth"><code>scrollWidth</code></dfn>
attribute, when called on element <var>A</var>,
<em class="ct">must</em> return value that is the result of the following
algorithm:</p>
<ol>
<li><p>If <var>A</var> does not have an associated CSS layout box return
zero and stop this algorithm.</p></li>
<li><p>Return the computed value of the <code>padding-left</code> property
of <var>A</var>, plus the computed value of the <code>padding-right</code>
property of <var>A</var>, plus the <span>content</span> width of
<var>A</var>.</p></li>
</ol>
<p>The <dfn id="dom-element-scrollheight"><code>scrollHeight</code></dfn>
attribute, when called on element <var>A</var>,
<em class="ct">must</em> return value that is the result of the following
algorithm:</p>
<ol>
<li><p>If <var>A</var> does not have an associated CSS layout box return
zero and stop this algorithm.</p></li>
<li><p>Return the computed value of the <code>padding-top</code> property
of <var>A</var>, plus the computed value of the
<code>padding-bottom</code> property of <var>A</var>, plus the
<span>content</span> height of <var>A</var>.</p></li>
</ol>
<!-- for inline boxes offsetWidth and offsetHeight are identical to offset* -->
<h3 id="client-attributes">The <code title="">clientTop</code>,
<code title="">clientLeft</code>, <code title="">clientWidth</code>, and
<code title="">clientHeight</code> attributes</h3>
<p>The <dfn id="dom-element-clienttop"><code>clientTop</code></dfn>,
<dfn id="dom-element-clientleft"><code>clientLeft</code></dfn>,
<dfn id="dom-element-clientwidth"><code>clientWidth</code></dfn>, and
<dfn id="dom-element-clientheight"><code>clientHeight</code></dfn>
attributes <em class="ct">must</em> return zero if the element does not
have an associated CSS layout box or if the layout box is inline.
Otherwise, these attributes <em class="ct">must</em> behave as defined in
the remainder of this section.</p>
<p>The <code>clientTop</code> attribute returns the computed value of the
<code>border-top-width</code> property plus the width of any scrollbar
rendered between the top <span>padding edge</span> and the top
<span>border edge</span>.</p>
<p>The <code>clientLeft</code> attribute returns the computed
value of the <code>border-left-width</code> property plus the width of any
scrollbar rendered between the left <span>padding edge</span> and the left
<span>border edge</span>.
<p>The <code>clientWidth</code> attribute returns the
<span>viewport</span> width excluding the size of a rendered scroll bar
(if any) if the element is the root element and the
width of the <span>padding edge</span> (excluding the width of any
rendered scrollbar between the <span>padding edge</span> and the
<span>border edge</span>) otherwise.</p>
<p>The <code>clientHeight</code> attribute returns the
<span>viewport</span> height excluding the size of a rendered scroll bar
(if any) if the element is the root element and the
height of the <span>padding edge</span> (excluding the width of any
rendered scrollbar between the <span>padding edge</span> and the
<span>border edge</span>) otherwise.</p>
<h2 id="extensions-to-the-htmlelement-interface">Extensions to the <code title="">HTMLElement</code> Interface</h2>
<pre class="idl">[Supplemental] interface <span>HTMLElement</span> {
readonly attribute Element <span>offsetParent</span>;
readonly attribute long <span>offsetTop</span>;
readonly attribute long <span>offsetLeft</span>;
readonly attribute long <span>offsetWidth</span>;
readonly attribute long <span>offsetHeight</span>;
};</pre>
<h3 id="offset-attributes">The <code title="">offsetParent</code>,
<code title="">offsetTop</code>, <code title="">offsetLeft</code>,
<code title="">offsetWidth</code>, and <code title="">offsetHeight</code>
attributes</h3>
<p>The
<dfn id="dom-htmlelement-offsetparent"><code>offsetParent</code></dfn>
attribute, when called on element <var>A</var>,
<em class="ct">must</em> return the element determined by the following
algorithm:</p>
<ol>
<li>
<p>If any of the following holds true return <code>null</code> and stop
this algorithm:</p>
<ul>
<li><var>A</var> does not have an associated CSS layout box.</li>
<li><var>A</var> is the root element.</li>
<li><var>A</var> is <span>the HTML <code>body</code>
element</span>.</li>
<li>The computed value of the <code>position</code> property for
element <var>A</var> is <code>fixed</code>.</li>
</ul>
</li>
<li><p>If <var>A</var> is an <code>area</code> <span>HTML element</span>
which has a <code>map</code> <span>HTML element</span> somewhere in the
ancestor chain return the nearest ancestor <code>map</code>
<span>HTML element</span> and stop this algorithm.</p></li>
<li>
<p>Return the nearest ancestor element of <var>A</var> for
which at least one of the following is true and stop this algorithm if
such an ancestor is found:</p>
<ul>
<li>The computed value of the <code>position</code> property is not
<code>static</code>.</li>
<li>It is <span>the HTML <code>body</code> element</span>.</li>
<li>The computed value of the <code>position</code> property of
<var>A</var> is <code>static</code> and the ancestor is one of the
following <span title="HTML element">HTML elements</span>:
<code>td</code>, <code>th</code>, or <code>table</code>.</li>
</ul>
</li>
<li><p>Return <code>null</code>.</p></li>
</ol>
<p>The <dfn id="dom-htmlelement-offsettop"><code>offsetTop</code></dfn>
attribute, when called on element <var>A</var>,
<em class="ct">must</em> return the value that is the result of the
following algorithm:</p>
<ol>
<li><p>If <var>A</var> is <span>the HTML <code>body</code> element</span>
or does not have an associated CSS layout box return zero and stop this
algorithm.</p></li>
<li><p>If the <code>offsetParent</code> of <var>A</var> is
<code>null</code> or <span>the HTML <code>body</code> element</span>
return the y-coordinate of the top <span>border edge</span> of
<var>A</var> and stop this algorithm.</p></li>
<li>
<p>Return the result of subtracting the y-coordinate of the top
<span>padding edge</span> of the <code>offsetParent</code> of
<var>A</var> from the y-coordinate of the top <span>border edge</span>
of <var>A</var>, relative to the <span>initial containing block</span>
origin.</p>
<p>In case of an inline element that consists of multiple line boxes
only the first in content order is to be considered for the purposes of
the above algorithm.</p>
</li>
</ol>
<p>The <dfn id="dom-htmlelement-offsetleft"><code>offsetLeft</code></dfn>
attribute, when called on element <var>A</var>,
<em class="ct">must</em> return the value that is the result of the
following algorithm:</p>
<ol>
<li><p>If element <var>A</var> is <span>the HTML <code>body</code>
element</span> or does not have an associated CSS layout box return zero
and stop this algorithm.</p></li>
<li><p>If the <code>offsetParent</code> of <var>A</var> is
<code>null</code> or <span>the HTML <code>body</code> element</span>
return the x-coordinate of the left <span>border edge</span> of
<var>A</var> and stop this algorithm.</p></li>
<li>
<p>Return the result of subtracting the x-coordinate of the left
View remainder of file in raw view