Title: CSSOM View Module ED: http://dev.w3.org/csswg/cssom-view/ TR: http://www.w3.org/TR/cssom-view/ Previous Version: http://www.w3.org/TR/2009/WD-cssom-view-20090804/ Previous Version: http://www.w3.org/TR/2008/WD-cssom-view-20080222/ Previous Version: http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113/ Group: CSSWG Status: WD Work Status: Revising Shortname: cssom-view Level: 1 Editor: Simon Pieters, Opera Software ASA http://www.opera.com, simonp@opera.com Editor: Glenn Adams, Cox Communications, Inc. http://www.cox.com, glenn.adams@cos.com, http://www.w3.org/wiki/User:Gadams Former Editor: Anne van Kesteren, Opera Software ASA http://www.opera.com, annevk@annevk.nl, https://annevankesteren.nl/ !Issues list: Bugzilla (file a bug) Abstract: The APIs introduced by this specification provide authors with a way to inspect and manipulate the visual view of a document. This includes getting the position of element layout boxes, obtaining the width of the viewport through script, and also scrolling an element. Ignored Terms: open(), EventTarget, EventListener, Event, EventInit, Element, Range, Node, Text
urlPrefix: https://html.spec.whatwg.org/multipage/
urlPrefix: infrastructure.html
type: dfn; text: html elements
urlPrefix: browsers.html
type: interface; text: WindowProxy
type: dfn
text: browsing context
text: auxiliary browsing context
text: familiar with
text: associated Document; url: concept-document-window
text: same origin
text: active document
urlPrefix: webappapis.html
type: dfn
text: responsible browsing context
text: incumbent settings object
text: event handler
text: event handler event type
text: event handler IDL attributes
urlPrefix: infrastructure.html
type: dfn
text: split a string on commas
text: skip whitespace
text: collect a sequence of characters
text: space character
text: converted to ascii lowercase
text: rules for parsing integers
urlPrefix: http://dev.w3.org/csswg/cssom/
type: dfn
text: parse a media query list
text: serialize a media query list
urlPrefix: https://dom.spec.whatwg.org/#concept-
type: dfn
text: context object
text: dispatch; url: event-dispatch
text: event
text: event listener
text: quirks mode; url: document-quirks
text: fire an event; url: event-fire
text: node document
urlPrefix: https://dom.spec.whatwg.org/
type: attribute;
for: Event; urlPrefix: #dom-Event-
text: type
text: isTrusted
for: Range; urlPrefix: #dom-Range-
text: startContainer
text: startOffset
type: dfn; text: dispatch flag
urlPrefix: http://www.w3.org/TR/CSS21/visuren.html
type: dfn; text: anonymous block box; url: #anonymous-block-level
urlPrefix: http://heycam.github.io/webidl/
type: interface; urlPrefix: #idl-
text: double
text: long
type: dfn; text: converted to an IDL value; url: dfn-convert-ecmascript-to-idl-value
url: http://www.w3.org/TR/DOM-Level-3-Events/#interface-MouseEvent; type: interface; text: MouseEvent
spec:dom-ls; type:method; text:addEventListener() spec:css-display-3; type:value; for:display; text:table spec:css-position-3; type:property; text:positionBackground {#background} ======================== Many of the features defined in this specification have been supported by browsers for a long period of time. The goal of this specification is to define these features in such a way that they can be implemented by all browsers in an interoperable manner. The specification also defines a couple of new features that will hopefully be useful to authors. (If they are not you can bug us!) Terminology {#terminology} ========================== Terminology used in this specification is from DOM, CSSOM and HTML. [[!DOM]] [[!CSSOM]] [[!HTML]] The HTML
body element is the first
body
HTML element child of the root
HTML element html.
Content edge, padding edge, border edge, margin edge, and viewport are defined by CSS.
Elements and viewports have an associated scrolling box if has a scrolling mechanism or it overflows
its content area and the used value of the 'overflow-x' or 'overflow-y' property is ''overflow/hidden''. [[!CSS3-BOX]]
An element is potentially scrollable if all of the following conditions are true:
* The element has an associated CSS layout box.
* The element is not the HTML body element, or it is and
the root element's used value of the 'overflow-x' or 'overflow-y' properties is not ''overflow/visible''.
* The element's used value of the 'overflow-x' or 'overflow-y' properties is not ''overflow/visible''.
Note: An element that is potentially scrollable might not have a scrolling box.
For instance, it could have 'overflow' set to ''overflow/auto'' but not have its content overflowing its content area.
A scrolling box of a viewport or element has two overflow directions, depending on the viewport’s or
element's block flow direction and inline base direction, as follows:
| If the overflow directions are… | For a viewport | For an element |
|---|---|---|
| rightward and downward |
|
|
| leftward and downward |
|
|
| leftward and upward |
|
|
| rightward and upward |
|
|
The terms CSS layout box and SVG layout box are not currently defined by CSS or SVG.
The term layout box refers to either a CSS layout box or an SVG layout box.
The term transforms refers to SVG transforms and CSS transforms. [[!SVG]] [[!CSS-TRANSFORMS-1]]
When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that
e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.
Unless otherwise stated, string comparisons are done in a case-sensitive manner.
CSS pixels {#css-pixels}
------------------------
All coordinates and dimensions for the APIs defined in this
specification are in CSS pixels, unless otherwise specified.
Note: This does not apply to e.g. {{matchMedia()}} as the units are explicitly given there.
Zooming {#zooming}
------------------
There are two kinds of zoom, page zoom which affects the size of the initial viewport, and pinch zoom which acts like
a magnifying glass and does not affect the initial viewport or actual viewport. [[!CSS-DEVICE-ADAPT]]
Common Infrastructure {#common-infrastructure}
==============================================
Scrolling {#scrolling}
----------------------
When a user agent is to perform a scroll of a scrolling box box,
to a given position position,
an associated element element and optionally a scroll behavior behavior
(which is "auto" if omitted),
the following steps must be run:
"auto" and element is not null and its computed value of the
'scroll-behavior' property is ''smooth''
smooth
#top fragment identifier, as defined in HTML. [[!HTML]]
WebIDL values {#webidl-values}
------------------------------
When asked to normalize non-finite values for a value x,
if x is one of the three special floating point literal values
(Infinity, -Infinity or NaN),
then x must be changed to the value 0. [[!WEBIDL]]
Extensions to the {{Window}} Interface {#extensions-to-the-window-interface}
============================================================================
enum ScrollBehavior { "auto", "instant", "smooth" };
dictionary ScrollOptions {
ScrollBehavior behavior = "auto";
};
dictionary ScrollToOptions : ScrollOptions {
unrestricted double left;
unrestricted double top;
};
partial interface Window {
[NewObject] MediaQueryList matchMedia(DOMString query);
[SameObject, Replaceable] readonly attribute Screen screen;
// browsing context
void moveTo(long x, long y);
void moveBy(long x, long y);
void resizeTo(long x, long y);
void resizeBy(long x, long y);
// viewport
[Replaceable] readonly attribute long innerWidth;
[Replaceable] readonly attribute long innerHeight;
// viewport scrolling
[Replaceable] readonly attribute double scrollX;
[Replaceable] readonly attribute double pageXOffset;
[Replaceable] readonly attribute double scrollY;
[Replaceable] readonly attribute double pageYOffset;
void scroll(optional ScrollToOptions options);
void scroll(unrestricted double x, unrestricted double y);
void scrollTo(optional ScrollToOptions options);
void scrollTo(unrestricted double x, unrestricted double y);
void scrollBy(optional ScrollToOptions options);
void scrollBy(unrestricted double x, unrestricted double y);
// client
[Replaceable] readonly attribute long screenX;
[Replaceable] readonly attribute long screenY;
[Replaceable] readonly attribute long outerWidth;
[Replaceable] readonly attribute long outerHeight;
[Replaceable] readonly attribute double devicePixelRatio;
};
When the matchMedia(query) method is invoked these steps must be run:
Document
as the document,
with parsed media query list as its associated media query list.
var viewportWidth = innerWidth
=" (U+003D).
Let name be the collected characters, converted to ASCII lowercase.
1. If name is in parsed features or if name is not a supported open() feature name,
continue token loop.
1. Skip whitespace.
1. If the character at position is not "=" (U+003D), continue token loop.
1. Advance position by one.
1. If position is past the end of input, continue token loop.
1. Collect a sequence of characters that are any characters. Let raw value be the collected characters.
1. Let value be the result of invoking the rules for parsing integers on raw value.
1. If value is an error, continue token loop.
1. Set name in parsed features to value.
1. If left is present in parsed features, follow these substeps:
1. Let x be the value of left.
1. Optionally, clamp x in a user-agent-defined manner so that the window does not move outside the available space.
1. Optionally, move target's window such that the window's left edge is at the horizontal coordinate x relative to the left edge of
the output device, measured in CSS pixels of target. The positive axis is rightward.
1. If top is present in parsed features, follow these substeps:
1. Let y be the value of top.
1. Optionally, clamp y in a user-agent-defined manner so that the window does not move outside the available space.
1. Optionally, move target's window such that the window's top edge is at the vertical coordinate y relative to the top edge of
the output device, measured in CSS pixels of target. The positive axis is downward.
1. If width is present in parsed features, follow these substeps:
1. Let x be the value of width.
1. Optionally, clamp x in a user-agent-defined manner so that the window does not get too small or bigger than the available space.
1. Optionally, size target's window by moving its right edge such that the distance between the left and right edges of the viewport are
x CSS pixels of target.
1. Optionally, move target's window in a user-agent-defined manner so that it does not grow outside the available space.
1. If height is present in parsed features, follow these substeps:
1. Let y be the value of height.
1. Optionally, clamp y in a user-agent-defined manner so that the window does not get too small or bigger than the available space.
1. Optionally, size target's window by moving its bottom edge such that the distance between the top and bottom edges of the viewport are
y CSS pixels of target.
1. Optionally, move target's window in a user-agent-defined manner so that it does not grow outside the available space.
A supported open() feature name is one of the following:
change,
its {{Event/isTrusted}} attribute initialized to true,
its {{MediaQueryList/media}} attribute initialized to target's media,
and its {{MediaQueryListEvent/matches}} attribute initialized to target's matches state.
function handleOrientationChange(event) {
if(event.matches) // landscape
…
else
…
}
var mql = matchMedia("(orientation:landscape)");
mql.onchange = handleOrientationChange;
interface MediaQueryList : EventTarget {
readonly attribute DOMString media;
readonly attribute boolean matches;
void addListener(EventListener? listener);
void removeListener(EventListener? listener);
attribute EventHandler onchange;
};
The media attribute must return
the associated media.
The matches attribute must return
the associated matches state.
The addListener(listener) method must run these steps:
1. If listener is null, terminate these steps.
1. Append an event listener to the associated list of event listeners
with type set to change,
callback set to listener,
and capture set to false,
unless there already is an event listener in that list
with the same type, callback, and capture.
The removeListener(listener) method must run these steps:
1. Remove an event listener from the associated list of event listeners,
whose type is change,
callback is listener,
and capture is false.
Note: This specification initially had a custom callback mechanism with {{addListener()}} and
{{removeListener()}}, and the callback was invoked with the associated media query list as argument.
Now the normal event mechanism is used instead.
For backwards compatibility, the {{addListener()}} and {{removeListener()}} methods
are basically aliases for {{addEventListener()}} and {{removeEventListener()}}, respectively,
and the change event masquerades as a {{MediaQueryList}}.
The following are the event handlers
(and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the {{MediaQueryList}} interface:
| Event handler | Event handler event type |
|---|---|
| onchange | change |
[Constructor(DOMString type, optional MediaQueryListEventInit eventInitDict)]
interface MediaQueryListEvent : Event {
readonly attribute DOMString media;
readonly attribute boolean matches;
};
dictionary MediaQueryListEventInit : EventInit {
DOMString media = "";
boolean matches = false;
};
The media attribute must return the value it was initialized to.
The matches attribute must return the value it was initialized to.
The {{Screen}} Interface {#the-screen-interface}
------------------------------------------------
As its name suggests, the {{Screen}} interface represents information about the screen of the output device.
interface Screen {
readonly attribute long availWidth;
readonly attribute long availHeight;
readonly attribute long width;
readonly attribute long height;
readonly attribute unsigned long colorDepth;
readonly attribute unsigned long pixelDepth;
};
The availWidth attribute must return the available width of the rendering surface of the output device,
in CSS pixels.
The availHeight attribute must return the available height of the rendering surface of the output
device, in CSS pixels.
The width attribute must return the width of the output device, in CSS pixels.
The height attribute must return the height of the output device, in CSS pixels.
The colorDepth attribute must return 24.
The pixelDepth attribute must return 24.
Note: The {{colorDepth}} and {{pixelDepth}} attributes are useless but are
included for compatibility.
Extensions to the {{Document}} Interface {#extensions-to-the-document-interface}
================================================================================
partial interface Document {
Element? elementFromPoint(double x, double y);
sequence<Element> elementsFromPoint(double x, double y);
CaretPosition? caretPositionFromPoint(double x, double y);
readonly attribute Element? scrollingElement;
};
The elementFromPoint(x, y) method must follow these steps:
1. If either argument is negative, x is greater than the viewport width excluding the size of a rendered scroll bar (if any), or
y is greater than the viewport height excluding the size of a rendered scroll bar (if any), or there is no viewport
associated with the document, return null and terminate these steps.
1. If there is a layout box in the viewport that would be a target for hit testing at coordinates x,y,
when applying the transforms that apply to the descendants of the viewport, return the associated element and terminate these steps.
1. If the document has a root element, return the root element and terminate these steps.
1. Return null.
Note: The {{elementFromPoint()}} method does not necessarily return the top-most painted element. For
instance, an element can be excluded from being a target for hit testing by using the 'pointer-events' CSS property.
The elementsFromPoint(x, y) method must follow these steps: 1. Let sequence be a new empty sequence. 1. If either argument is negative, x is greater than the viewport width excluding the size of a rendered scroll bar (if any), or y is greater than the viewport height excluding the size of a rendered scroll bar (if any), or there is no viewport associated with the document, return sequence and terminate these steps. 1. For each layout box in the viewport, in paint order, starting with the topmost box, that would be a target for hit testing at coordinates x,y even if nothing would be overlapping it, when applying the transforms that apply to the descendants of the viewport, append the associated element to sequence. 1. If the document has a root element, and the last item in sequence is not the root element, append the root element to sequence. 1. Return sequence. The caretPositionFromPoint(x, y) method must return the result of running these steps: 1. If there is no viewport associated with the document, return null. 1. If either argument is negative, x is greater than the viewport width excluding the size of a rendered scroll bar (if any), y is greather than the viewport height excluding the size of a rendered scroll bar (if any) return null. 1. If at the coordinates x,y in the viewport no text insertion point indicator would have been inserted when applying the transforms that apply to the descendants of the viewport, return null. 1. If at the coordinates x,y in the viewport a text insertion point indicator would have been inserted in a text entry widget which is also a replaced element, when applying the transforms that apply to the descendants of the viewport, return a caret position with its properties set as follows:
The scrollingElement attribute, on getting, must run these steps:
1. If the {{Document}} is in quirks mode, follow these substeps:
1. If the HTML body element exists, and it is not potentially scrollable, return the HTML body element and abort these steps.
1. Return null and abort these steps.
1. If there is a root element, return the root element and abort these steps.
1. Return null.
Note: For non-conforming user agents that always use the quirks mode behavior for {{Element/scrollTop}}
and {{Element/scrollLeft}}, the {{Document/scrollingElement}} attribute is expected to also always return
the HTML body element (or null if it does not exist).
This API exists so that Web developers can use it to get the right element to use for scrolling APIs,
without making assumptions about a particular user agent's behavior
or having to invoke a scroll to see which element scrolls the viewport.
Note: The HTML body element is different from HTML's document.body
in that the latter can return a frameset element.
The {{CaretPosition}} Interface {#the-caretposition-interface}
--------------------------------------------------------------
A caret position gives the position of a text insertion point indicator. It always has an associated
caret node, caret offset, and caret range. It is represented by a {{CaretPosition}} object.
interface CaretPosition {
readonly attribute Node offsetNode;
readonly attribute unsigned long offset;
DOMRect? getClientRect();
};
The offsetNode attribute must return the caret node.
The offset attribute must return the caret offset.
The getClientRect() method must follow these steps,
aborting on the first step that returns a value:
1. If caret range is not null:
1. Let list be the result of invoking the {{Range/getClientRects()}} method on the range.
1. If list is empty, return null.
1. Return the {{DOMRect}} object in list at index 0.
1. If caret node is a text entry widget that is a replaced element,
and that is in the document,
return a {{DOMRect}} object for the caret in the widget
as represented by the caret offset value.
The transforms that apply to the element and its ancestors are applied.
1. Return null.
Extensions to the {{Element}} Interface {#extension-to-the-element-interface}
=============================================================================
enum ScrollLogicalPosition { "start", "end" };
dictionary ScrollIntoViewOptions : ScrollOptions {
ScrollLogicalPosition block = "start";
};
partial interface Element {
DOMRectList getClientRects();
DOMRect getBoundingClientRect();
void scrollIntoView();
void scrollIntoView((boolean or object) arg);
void scroll(optional ScrollToOptions options);
void scroll(unrestricted double x, unrestricted double y);
void scrollTo(optional ScrollToOptions options);
void scrollTo(unrestricted double x, unrestricted double y);
void scrollBy(optional ScrollToOptions options);
void scrollBy(unrestricted double x, unrestricted double y);
attribute unrestricted double scrollTop;
attribute unrestricted double scrollLeft;
readonly attribute long scrollWidth;
readonly attribute long scrollHeight;
readonly attribute long clientTop;
readonly attribute long clientLeft;
readonly attribute long clientWidth;
readonly attribute long clientHeight;
};
The getClientRects() method, when invoked, must return the result of the following algorithm:
1. If the element on which it was invoked does not have an associated layout box return an empty {{DOMRectList}} object and stop this algorithm.
1. If the element has an associated SVG layout box return a {{DOMRectList}} object containing a single {{DOMRect}} object that describes the bounding box of the element as defined by the SVG specification, applying the transforms that apply to the element and its ancestors.
1. Return a {{DOMRectList}} object containing a list of {{DOMRect}} objects in content order describing the bounding border boxes (including those with a height or width of zero) with the following constraints:
* Apply the transforms that apply to the element and its ancestors.
* If the element on which the method was invoked has a computed value for the 'display' property of ''table'' or ''inline-table'' include both the table box and the caption box, if any, but not the anonymous container box.
* Replace each anonymous block box with its child box(es) and repeat this until no anonymous block boxes are left in the final list.
The getBoundingClientRect() method, when invoked, must return the result of the following
algorithm:
1. Let list be the result of invoking {{Element/getClientRects()}} on the same element this method was invoked on.
1. If the list is empty return a {{DOMRect}} object
whose {{DOMRect/x}}, {{DOMRect/y}}, {{DOMRect/width}} and {{DOMRect/height}} members are zero.
1. Otherwise, return a {{DOMRect}} object describing the smallest rectangle
that includes the first rectangle in list
and all of the remaining rectangles of which the height or width is not zero.
div element in a document:
var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
var exampleWidth = example.width;
var exampleHeight = example.height;
end".
1. If the element does not have any associated layout box terminate these steps.
1. Scroll the element into view
with the align to top flag set if options {{ScrollIntoViewOptions/block}} dictionary member has the value "start",
and the scroll behavior being the value of the {{ScrollOptions/behavior}} dictionary member of options.
1. Optionally perform some other action that brings the element to the user's attention.
The scroll() method must run these steps:
1. If invoked with one argument, follow these substeps:
1. Let options be the argument.
1. Normalize non-finite values for {{ScrollToOptions/left}} and {{ScrollToOptions/top}} dictionary members of options, if present.
1. Let x be the value of the {{ScrollToOptions/left}} dictionary member of options, if present, or the element's current scroll position on the x axis otherwise.
1. Let y be the value of the {{ScrollToOptions/top}} dictionary member of options, if present, or the element's current scroll position on the y axis otherwise.
1. If invoked with two arguments, follow these substeps:
1. Let options be null converted to a {{ScrollToOptions}} dictionary. [[!WEBIDL]]
1. Let x and y be the arguments, respectively.
1. Normalize non-finite values for x and y.
1. Let the {{ScrollToOptions/left}} dictionary member of options have the value x.
1. Let the {{ScrollToOptions/top}} dictionary member of options have the value y.
1. Let document be the element's node document.
1. If document is not the active document, terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, terminate these steps.
1. If the element is the root element and document is in quirks mode, terminate these steps.
1. If the element is the root element invoke {{Window/scroll()}} on window with {{Window/scrollX}} on window as first argument and y as second argument,
and terminate these steps.
1. If the element is the HTML body element,
document is in quirks mode,
and the element is not potentially scrollable,
invoke {{Window/scroll()}} on window with options as the only argument,
and terminate these steps.
1. If the element does not have any associated CSS layout box,
the element has no associated scrolling box,
or the element has no overflow,
terminate these steps.
1. Scroll the element to x,y,
with the scroll behavior being the value of the {{ScrollOptions/behavior}} dictionary member of options.
When the scrollTo() method is invoked, the
user agent must act as if the {{Element/scroll()}} method was invoked with the same arguments.
When the scrollBy() method is invoked, the
user agent must run these steps:
1. If invoked with one argument, follow these substeps:
1. Let options be the argument.
1. Normalize non-finite values for {{ScrollToOptions/left}} and {{ScrollToOptions/top}} dictionary members of options, if present.
1. If invoked with two arguments, follow these substeps:
1. Let options be null converted to a {{ScrollToOptions}} dictionary. [[!WEBIDL]]
1. Let x and y be the arguments, respectively.
1. Normalize non-finite values for x and y.
1. Let the {{ScrollToOptions/left}} dictionary member of options have the value x.
1. Let the {{ScrollToOptions/top}} dictionary member of options have the value y.
1. Add the value of {{Element/scrollLeft}} to the {{ScrollToOptions/left}} dictionary member.
1. Add the value of {{Element/scrollTop}} to the {{ScrollToOptions/top}} dictionary member.
1. Act as if the {{Element/scroll()}} method was invoked with options as the only argument.
The scrollTop attribute, on getting, must return the result of running these steps:
1. Let document be the element's node document.
1. If document is not the active document, return zero and terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, return zero and terminate these steps.
1. If the element is the root element and document is in quirks mode, return zero and terminate these steps.
1. If the element is the root element return the value of {{Window/scrollY}} on window.
1. If the element is the HTML body element, document is in quirks mode, and the element is not potentially scrollable, return the value of {{Window/scrollY}} on window.
1. If the element does not have any associated CSS layout box, return zero and terminate these steps.
1. Return the y-coordinate of the scrolling area at the alignment point with the top of the padding edge of the element.
When setting the {{Element/scrollTop}} attribute these steps must be run:
1. Let y be the given value.
1. Normalize non-finite values for y.
1. Let document be the element's node document.
1. If document is not the active document, terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, terminate these steps.
1. If the element is the root element and document is in quirks mode, terminate these steps.
1. If the element is the root element invoke {{Window/scroll()}} on window with {{Window/scrollX}} on window as first argument and y as second argument, and terminate these steps.
1. If the element is the HTML body element, document is in quirks mode, and the element is not potentially scrollable, invoke {{Window/scroll()}} on window with {{Window/scrollX}} as first argument and y as second argument, and terminate these steps.
1. If the element does not have any associated CSS layout box, the element has no associated scrolling box, or the element has no overflow, terminate these steps.
1. Scroll the element to {{Element/scrollLeft}},y, with the scroll behavior being "auto".
The scrollLeft attribute, on getting, must return the result of running these steps:
1. Let document be the element's node document.
1. If document is not the active document, return zero and terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, return zero and terminate these steps.
1. If the element is the root element and document is in quirks mode, return zero and terminate these steps.
1. If the element is the root element return the value of {{Window/scrollX}} on window.
1. If the element is the HTML body element, document is in quirks mode, and the element is not potentially scrollable, return the value of {{Window/scrollX}} on window.
1. If the element does not have any associated CSS layout box, return zero and terminate these steps.
1. Return the x-coordinate of the scrolling area at the alignment point with the left of the padding edge of the element.
When setting the {{Element/scrollLeft}} attribute these steps must be run:
1. Let x be the given value.
1. Normalize non-finite values for x.
1. Let document be the element's node document.
1. If document is not the active document, terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, terminate these steps.
1. If the element is the root element and document is in quirks mode, terminate these steps.
1. If the element is the root element invoke {{Window/scroll()}} on window with x as first argument and {{Window/scrollY}} on window as second argument, and terminate these steps.
1. If the element is the HTML body element, document is in quirks mode, and the element is not potentially scrollable, invoke {{Window/scroll()}} on window with x as first argument and {{Window/scrollY}} on window as second argument, and terminate these steps.
1. If the element does not have any associated CSS layout box, the element has no associated scrolling box, or the element has no overflow, terminate these steps.
1. Scroll the element to x,{{Element/scrollTop}}, with the scroll behavior being "auto".
The scrollWidth attribute must return the result of running these steps:
1. Let document be the element's node document.
1. If document is not the active document, return zero and terminate these steps.
1. Let viewport width be the width of the viewport excluding the width of the scroll bar, if any, or zero if there is no viewport.
1. If the element is the root element and document is not in quirks mode return max(viewport scrolling area width, viewport width).
1. If the element is the HTML body element, document is in quirks mode and the element is not potentially scrollable, return max(viewport scrolling area width, viewport width).
1. If the element does not have any associated CSS layout box return zero and terminate these steps.
1. Return the width of the element's scrolling area.
The scrollHeight attribute must return the result of running these steps:
1. Let document be the element's node document.
1. If document is not the active document, return zero and terminate these steps.
1. Let viewport height be the height of the viewport excluding the height of the scroll bar, if any, or zero if there is no viewport.
1. If the element is the root element and document is not in quirks mode return max(viewport scrolling area height, viewport height).
1. If the element is the HTML body element, document is in quirks mode and the element is not potentially scrollable, return max(viewport scrolling area height, viewport height).
1. If the element does not have any associated CSS layout box return zero and terminate these steps.
1. Return the height of the element's scrolling area.
The clientTop attribute must run these steps:
1. If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.
1. Return the computed value of the 'border-top-width' property plus the height of any scrollbar rendered between the top padding edge and the top border edge, ignoring any transforms that apply to the element and its ancestors.
The clientLeft attribute must run these steps:
1. If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.
1. Return the computed value of the 'border-left-width' property plus the width of any scrollbar rendered between the left padding edge and the left border edge, ignoring any transforms that apply to the element and its ancestors.
The clientWidth attribute must run these steps:
1. If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.
1. If the element is the root element and the element's node document is not in quirks mode, or if the element is the HTML body element and the element's node document is in quirks mode, return the viewport width excluding the size of a rendered scroll bar (if any).
1. Return the width of the padding edge excluding the width of any rendered scrollbar between the padding edge and the border edge, ignoring any transforms that apply to the element and its ancestors.
The clientHeight attribute must run these steps:
1. If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.
1. If the element is the root element and the element's node document is not in quirks mode, or if the element is the HTML body element and the element's node document is in quirks mode, return the viewport height excluding the size of a rendered scroll bar (if any).
1. Return the height of the padding edge excluding the height of any rendered scrollbar between the padding edge and the border edge, ignoring any transforms that apply to the element and its ancestors.
The {{Element/getClientRects()}} and {{Element/getBoundingClientRect()}} methods {#the-getclientrects()-and-getboundingclientrect()-methods}
----------------------------------------------------------------------------------------------------------------------------
The {{Element/getClientRects()}} and {{Element/getBoundingClientRect()}}
methods provide information about the position of the border box edges of
an element relative to the viewport. The objects these methods return
must be static. That is, changes to the underlying
document are not reflected in the objects.
{{Element}} Scrolling Members {#element-scrolling-members}
----------------------------------------------------------
To scroll an element into view element, optionally with an align to top flag set, and optionally with a scroll behavior
behavior (which is "auto" if omitted), means to run these steps for each ancestor element or viewport that establishes
a scrolling box scrolling box, in order of innermost to outermost scrolling box:
1. If the {{Document}} associated with element is not same origin with the {{Document}} associated with the element or viewport associated with box, terminate these steps.
1. Let element bounding border box be the box that the return value of invoking {{Element/getBoundingClientRect()}} on element represents.
1. Let scrolling box edge A be the beginning edge in the block flow direction of scrolling box, and let element edge A be element bounding border box's edge on the same physical side as that of scrolling box edge A.
1. Let scrolling box edge B be the ending edge in the block flow direction of scrolling box, and let element edge B be element bounding border box's edge on the same physical side as that of scrolling box edge B.
1. Let scrolling box edge C be the beginning edge in the inline base direction of scrolling box, and let element edge C be element bounding border box's edge on the same physical side as that of scrolling box edge C.
1. Let scrolling box edge D be the ending edge in the inline base direction of scrolling box, and let element edge D be element bounding border box's edge on the same physical side as that of box edge D.
1. Let element width be the distance between element edge C and element edge D.
1. Let scrolling box width be the distance between scrolling box edge C and scrolling box edge D.
1. Let position be the scroll position scrolling box would have by following these steps:
1. If the align to top flag is set align element edge A with scrolling box edge A.
1. Otherwise, the align to top flag is not set; align element edge B with scrolling box edge B.
1. "auto" if omitted) means to:
1. Let box be element's associated scrolling box.
1.
partial interface HTMLElement {
readonly attribute Element? offsetParent;
readonly attribute long offsetTop;
readonly attribute long offsetLeft;
readonly attribute long offsetWidth;
readonly attribute long offsetHeight;
};
The offsetParent attribute must return the result of running these steps:
1. If any of the following holds true return null and terminate this algorithm:
* The element does not have an associated CSS layout box.
* The element is the root element.
* The element is the HTML body element.
* The element's computed value of the 'position' property is ''position/fixed''.
1. Return the nearest ancestor element of the element for which at least one of the following is true and terminate this algorithm if such an ancestor is found:
* The computed value of the 'position' property is not ''static''.
* It is the HTML body element.
* The computed value of the 'position' property of the element is ''static'' and the ancestor is one of the following HTML elements: td, th, or table.
1. Return null.
The offsetTop attribute must return the result of running these steps:
1. If the element is the HTML body element or does not have any associated CSS layout box return zero and terminate this algorithm.
1. If the {{HTMLElement/offsetParent}} of the element is null return the y-coordinate of the top border edge of the first CSS layout box associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors, and terminate this algorithm.
1. Return the result of subtracting the y-coordinate of the top padding edge
of the first CSS layout box associated with the {{HTMLElement/offsetParent}} of the element
from the y-coordinate of the top border edge
of the first CSS layout box associated with the element,
relative to the initial containing block origin,
ignoring any transforms that apply to the element and its ancestors.
Note: An inline element that consists of multiple line boxes will only have its first CSS layout box considered.
The offsetLeft attribute must return the result of running these steps:
1. If the element is the HTML body element or does not have any associated CSS layout box return zero and terminate this algorithm.
1. If the {{HTMLElement/offsetParent}} of the element is null return the x-coordinate of the left border edge of the first CSS layout box associated with the element, relative to the initial containing block origin, , ignoring any transforms that apply to the element and its ancestors, and terminate this algorithm.
1. Return the result of subtracting the x-coordinate of the left padding edge of the first CSS layout box associated with the {{HTMLElement/offsetParent}} of the element from the x-coordinate of the left border edge of the first CSS layout box associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors.
The offsetWidth attribute must return the result of running these steps:
1. If the element does not have any associated CSS layout box return zero and terminate this algorithm.
1. Return the border edge width of the first CSS layout box associated with the element, ignoring any transforms that apply to the element and its ancestors.
The offsetHeight attribute must return the result of running these steps:
1. If the element does not have any associated CSS layout box return zero and terminate this algorithm.
1. Return the border edge height of the first CSS layout box associated with the element, ignoring any transforms that apply to the element and its ancestors.
Extensions to the {{HTMLImageElement}} Interface {#extensions-to-the-htmlimageelement-interface}
================================================================================================
partial interface HTMLImageElement {
readonly attribute long x;
readonly attribute long y;
};
The x attribute, on getting, must return the x-coordinate of the left border edge of the
first CSS layout box associated with the element, relative to the initial containing block origin, ignoring any
transforms that apply to the element and its ancestors, or zero if there is no CSS layout box.
The y attribute, on getting, must return the y-coordinate of the top border edge of the
first CSS layout box associated with the element, relative to the initial containing block origin, ignoring any
transforms that apply to the element and its ancestors, or zero if there is no CSS layout box.
Extensions to the {{Range}} Interface {#extensions-to-the-range-interface}
==========================================================================
The objects the methods described below return must be static.
partial interface Range {
DOMRectList getClientRects();
DOMRect getBoundingClientRect();
};
The getClientRects() method, when invoked, must return an empty
{{DOMRectList}} object if the range is not in the document and
otherwise a {{DOMRectList}} object containing a list of
{{DOMRect}} objects in content order that matches the
following constraints:
* For each element selected by the range, whose parent is not selected by the range, include the border boxes returned by invoking {{Element/getClientRects()}} on the element.
* For each {{Text}} node selected or partially selected by the range (including when the boundary-points are identical), include a {{DOMRect}} object (for the part that is selected, not the whole line box). The bounds of these {{DOMRect}} objects are computed using font metrics; thus, for horizontal writing, the vertical dimension of each box is determined by the font ascent and descent, and the horizontal dimension by the text advance width. The transforms that apply to the ancestors are applied.
The getBoundingClientRect() method, when invoked, must return the result of the following
algorithm:
1. Let list be the result of invoking {{Range/getClientRects()}} on the same range this method was invoked on.
1. If list is empty return a {{DOMRect}} object whose x, y, width and height members are zero.
1. Otherwise, return a {{DOMRect}} object describing the smallest rectangle that includes the first rectangle in list and all of the remaining rectangles of which the height or width is not zero.
Extensions to the {{MouseEvent}} Interface {#extensions-to-the-mouseevent-interface}
====================================================================================
Issue: The object IDL fragment redefines some members. Can we resolve this somehow?
partial interface MouseEvent {
readonly attribute double screenX;
readonly attribute double screenY;
readonly attribute double pageX;
readonly attribute double pageY;
readonly attribute double clientX;
readonly attribute double clientY;
readonly attribute double x;
readonly attribute double y;
readonly attribute double offsetX;
readonly attribute double offsetY;
};
partial dictionary MouseEventInit {
double screenX = 0.0;
double screenY = 0.0;
double clientX = 0.0;
double clientY = 0.0;
};
The screenX attribute must return the x-coordinate of
the position where the event occurred relative to the origin of the
screen.
The screenY attribute must return the y-coordinate of
the position where the event occurred relative to the origin of the
screen.
The pageX attribute must follow these steps:
1. If the event's dispatch flag is set, return the horizontal coordinate of the position where the event occurred relative to the origin of the initial containing block and terminate these steps.
1. Let offset be the value of the {{Window/scrollX}} attribute of the event's associated {{Window}} object, if there is one, or zero otherwise.
1. Return the sum of offset and the value of the event's {{MouseEvent/clientX}} attribute.
The pageY attribute must follow these steps:
1. If the event's dispatch flag is set, return the vertical coordinate of the position where the event occurred relative to the origin of the initial containing block and terminate these steps.
1. Let offset be the value of the {{Window/scrollX}} attribute of the event's associated {{Window}} object, if there is one, or zero otherwise.
1. Return the sum of offset and the value of the event's {{MouseEvent/clientY}} attribute.
The clientX attribute must return the x-coordinate of
the position where the event occurred relative to the origin of the
viewport.
The clientY attribute must return the y-coordinate of
the position where the event occurred relative to the origin of the
viewport.
The x attribute must return the value of {{MouseEvent/clientX}}.
The y attribute must return the value of {{MouseEvent/clientY}}.
The offsetX attribute must follow these steps:
1. If the event's dispatch flag is set, return the x-coordinate of the position where the event occurred relative to the origin of the padding edge of the target node, ignoring the transforms that apply to the element and its ancestors, and terminate these steps.
1. Return the value of the event's {{MouseEvent/pageX}} attribute.
The offsetY attribute must follow these steps:
1. If the event's dispatch flag is set, return the y-coordinate of the position where the event occurred relative to the origin of the padding edge of the target node, ignoring the transforms that apply to the element and its ancestors, and terminate these steps.
1. Return the value of the event's {{MouseEvent/pageY}} attribute.
Geometry {#geometry}
====================
enum CSSBoxType { "margin", "border", "padding", "content" };
dictionary BoxQuadOptions {
CSSBoxType box = "border";
GeometryNode relativeTo; // XXX default document (i.e. viewport)
};
dictionary ConvertCoordinateOptions {
CSSBoxType fromBox = "border";
CSSBoxType toBox = "border";
};
[NoInterfaceObject]
interface GeometryUtils {
sequence<DOMQuad> getBoxQuads(optional BoxQuadOptions options);
DOMQuad convertQuadFromNode(DOMQuadInit quad, GeometryNode from, optional ConvertCoordinateOptions options);
DOMQuad convertRectFromNode(DOMRectReadOnly rect, GeometryNode from, optional ConvertCoordinateOptions options);
DOMPoint convertPointFromNode(DOMPointInit point, GeometryNode from, optional ConvertCoordinateOptions options); // XXX z,w turns into 0
};
Text implements GeometryUtils; // like Range
Element implements GeometryUtils;
PseudoElement implements GeometryUtils;
Document implements GeometryUtils;
typedef (Text or Element or PseudoElement or Document) GeometryNode;
The getBoxQuads(options) method must run the following steps:
...
...
...
iframe element's dimensions are changed)
since the last time these steps were run,
fire an event named resize
at the {{Window}} object associated with doc.
Scrolling {#scrolling-events}
----------------------
Each {{Document}} has an associated list of pending scroll event targets, initially empty.
Whenever a viewport gets scrolled (whether in response to user interaction or by an API), the user agent must run these steps:
1. Let doc be the viewport’s associated {{Document}}.
1. If doc is already in doc's pending scroll event targets, abort these steps.
1. Append doc to doc's pending scroll event targets.
Whenever an element gets scrolled (whether in response to user interaction or by an API), the user agent must run these steps:
1. Let doc be the element's node document.
1. If the element is already in doc's pending scroll event targets, abort these steps.
1. Append the element to doc's pending scroll event targets.
When asked to run the scroll steps for a {{Document}} doc, run these steps:
1. For each item target in doc's pending scroll event targets,
in the order they were added to the list, run these substeps:
1. If target is a {{Document}}, fire an event named scroll that bubbles at target.
1. Otherwise, fire an event named scroll at target.
1. Empty doc's pending scroll event targets.
CSS properties {#css-properties}
================================
Issue: The features in this section should be moved to some other specification.
Smooth Scrolling: The 'scroll-behavior' Property {#smooth-scrolling}
--------------------------------------------------------------------
Name: scroll-behavior Value: auto | smooth Initial: auto Applies to: scrolling boxes Inherited: no Computed value: specified value Media: visual Animatable: no Canonical Order: per grammarThe 'scroll-behavior' property specifies the scrolling behavior for a scrolling box, when scrolling happens due to navigation or CSSOM scrolling APIs. Any other scrolls, e.g. those 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 viewport instead.
The 'scroll-behavior' property of the HTML body element is not propagated to the viewport.
features argument to window.open() is now defined.
* The {{Screen/colorDepth}} and {{Screen/pixelDepth}} attributes of {{Screen}} now always return 24.
* The {{Document/elementsFromPoint()}} method of {{Element}} is introduced.
* The specification is now aware of transforms.
* Some geometry utility APIs are introduced but are not yet specified.
* ClientRect has been renamed to {{DOMRect}} and has moved to the Geometry specification. [[GEOMETRY-1]]
* The specification now defines when the resize and scroll events fire.