Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the 30 September 2013 Editor's Draft of CSSOM View. Please send comments to www-style@w3.org (archived) with [cssom-view] at the start of the subject line.
This document was produced by the CSS Working Group (part of the Style Activity).
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Window
Interface
Document
Interface
Element
Interface
HTMLElement
InterfaceRange
InterfaceMouseEvent
InterfaceMany 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!)
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]
Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)
User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.
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.
A conforming user agent implements all the requirements made by this specification.
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
Terminology used in this specification is from DOM, CSSOM and HTML. [DOM] [CSSOM] [HTML]
MouseEvent
and MouseEventInit
are defined in …
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 canvas are defined by CSS.
Viewport and initial containing block are defined by CSS 2.1.
Block flow direction and inline base direction are defined in CSS Writing Modes Module. [CSSWRITINGMODES]
Elements and viewports have an associated scrolling box if it overflows its content area and either has a scrolling mechanism or the used value of the 'overflow-x' or 'overflow-y' property is 'hidden'. [CSSBOX]
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:
Rightward and downward.
Leftward and downward.
Leftward and upward.
Righward and upward.
The term scrolling area refers to a box of a viewport or an element that has the following edges, depending on the viewport's or element's scrolling box's overflow directions.
If the overflow directions are… | For a viewport | For an element |
---|---|---|
rightward and downward |
|
|
leftward and downward |
|
|
leftward and upward |
|
|
rightward and upward |
|
|
The beginning edges of a particular set of edges of a box or element are the following edges:
The top and left edges.
The top and right edges.
The bottom and right edges.
The bottom and left edges.
The ending edges of a particular set of edges of a box or element are the following edges:
The bottom and right edges.
The bottom and left edges.
The top and left edges.
The top and right edges.
The term CSS layout box refers to the same term in CSS. For the purpose of the requirements in this specification, elements that have a computed value of the 'display' property that is 'table-column' or 'table-column-group' must be considered to have an associated CSS layout box (the column or column group, respectively).
The term SVG layout box refers to the same term in SVG.
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] [CSSTRANSFORMS]
All coordinates and dimensions for the APIs defined in this specification are in CSS pixels, unless otherwise specified.
This does not apply to e.g.
matchMedia()
as the units
are explicitly given there.
When a user agent is to perform a scroll of a scrolling box box, to a given position position, with a set of
steps task, an associated element element and optionally a scroll behavior behavior (which is
auto
if omitted), the following steps must be run:
Abort any ongoing smooth scroll for box.
If the user agent honors the 'scroll-behavior' property and one of the following are true:
behavior is auto
and element is not null and its computed value of the
'scroll-behavior' property is 'smooth'
behavior is smooth
...then follow these substeps:
Perform a smooth scroll of box to position.
Queue a task to run task, unless a task to run task is in the queue.
Repeat the previous step in a user-agent-defined interval while the smooth scroll is ongoing, as well as when the smooth scroll is completed (but not if it is aborted).
Otherwise, follow these substeps:
Perform an instant scroll of box to position.
Queue a task to run task, unless a task to run task is in the queue.
When a user agent is to perform a smooth scroll of a scrolling box box to position, it must update the scroll position of box in a user-agent-defined fashion over a user-agent-defined amount of time. When the scroll is completed, the scroll position of box must be position. The scroll can also be aborted, either by an algorithm or by the user.
When a user agent is to perform an instant scroll of a scrolling box box to position, it must update the scroll position of box to position.
To scroll to the beginning of the document for a document document, follow these steps:
Let viewport be the viewport that is associated with document.
Let position be the the scroll position viewport would have by aligning the beginning edges of the scrolling area with the beginning edges of viewport.
If position is the same as viewport's current scroll position, and viewport does not have an ongoing smooth scroll, abort these steps.
Let task be these steps:
Fire an event named scroll
that bubbles at document.
Perform a scroll of viewport to position, with the set of steps task, and document's root element as the associated element, if there is one, or null otherwise.
This algorithm is used when navigating to the #top
fragment identifier, as defined in HTML. [HTML]
Window
Interfaceenum ScrollBehavior { "auto", "instant", "smooth" }; dictionary ScrollOptions { ScrollBehavior behavior = "auto"; }; partial interface Window { MediaQueryList matchMedia(DOMString query); [SameObject] readonly attribute Screen screen; // browsing context void moveTo(double x, double y); void moveBy(double x, double y); void resizeTo(double x, double y); void resizeBy(double x, double y); // viewport readonly attribute double innerWidth; readonly attribute double innerHeight; // viewport scrolling readonly attribute double scrollX; readonly attribute double pageXOffset; readonly attribute double scrollY; readonly attribute double pageYOffset; void scroll(double x, double y, optional ScrollOptions options); void scrollTo(double x, double y, optional ScrollOptions options); void scrollBy(double x, double y, optional ScrollOptions options); // client readonly attribute double screenX; readonly attribute double screenY; readonly attribute double outerWidth; readonly attribute double outerHeight; };
When the matchMedia(query)
method is invoked these steps must be run:
Let parsed media query list be the result of parsing query.
Return a new MediaQueryList
object,
associated with the Window
object, with
parsed media query list as its associated
media query list.
The screen
attribute must return the Screen
object
associated with the Window
object.
Accessing screen
through a WindowProxy
object might yield different
results when the Document
is navigated.
The moveTo(x, y) method must follow these steps:
Optionally, terminate these steps.
Let target be the browsing context of the context object.
Let source be the browsing context of the incumbent script.
If source is not allowed to resize and move target, terminate these steps.
Optionally, clamp x and y in a user-agent-defined manner so that the window does not move outside the available space.
Move target's window such that the window's top left corner is at coordinates (x, y) relative to the top left corner of the output device, measured in CSS pixels of target. The positive axes are rightward and downward.
The moveBy(x, y) method must follow these steps:
Optionally, terminate these steps.
Let target be the browsing context of the context object.
Let source be the browsing context of the incumbent script.
If source is not allowed to resize and move target, terminate these steps.
Optionally, clamp x and y in a user-agent-defined manner so that the window does not move outside the available space.
Move target's window x CSS pixels of target righward and y CSS pixels of target downward.
The resizeTo(x, y) method must follow these steps:
Optionally, terminate these steps.
Let target be the browsing context of the context object.
Let source be the browsing context of the incumbent script.
If source is not allowed to resize and move target, terminate these steps.
Optionally, clamp x and y in a user-agent-defined manner so that the window does not get too small or bigger than the available space.
Resize target's window by moving its right and bottom edges such that the distance between the left and right edges of the viewport are x CSS pixels of target and the distance between the top and bottom edges of the viewport are y CSS pixels of target.
Optionally, move target's window in a user-agent-defined manner so that it does not grow outside the available space.
The resizeBy(x, y) method must follow these steps:
Optionally, terminate these steps.
Let target be the browsing context of the context object.
Let source be the browsing context of the incumbent script.
If source is not allowed to resize and move target, terminate these steps.
Optionally, clamp x and y in a user-agent-defined manner so that the window does not get too small or bigger than the available space.
Resize target's window by moving its right edge x CSS pixels of target righward and its bottom edge y CSS pixels of target downward.
Optionally, move target's window in a user-agent-defined manner so that it does not grow outside the available space.
A browsing context A is allowed to resize and move a browsing context B if all the following conditions are met:
B is an auxiliary browsing context that was created by a script (as opposed to by an action of the user).
A is familiar with B.
The innerWidth
attribute must return the viewport width including the size of a rendered
scroll bar (if any), or zero if there is no viewport.
The following snippet shows how to obtain the width of the viewport:
var viewportWidth = innerWidth
The innerHeight
attribute must return the viewport height including the size of a rendered
scroll bar (if any), or zero if there is no viewport.
The scrollX
attribute attribute must return the x-coordinate, relative to the initial containing
block origin, of the left of the viewport, or zero if there is no viewport.
The pageXOffset
attribute must return the value returned by the
scrollX
attribute.
The scrollY
attribute attribute must return the y-coordinate, relative to the initial containing
block origin, of the top of the viewport, or zero if there is no viewport.
The pageYOffset
attribute must return the value returned by the
scrollY
attribute.
When the scroll(x, y, options)
method is invoked these
steps must be run:
If there is no viewport, abort these steps.
Let viewport width be the width of the viewport excluding the width of the scroll bar, if any.
Let viewport height be the height of the viewport excluding the height of the scroll bar, if any.
Let x be max(0, min(x, viewport scrolling area width - viewport width)).
Let x be min(0, max(x, viewport width - viewport scrolling area width)).
Let y be max(0, min(y, viewport scrolling area height - viewport height)).
Let y be min(0, max(y, viewport height - viewport scrolling area height)).
Let position be the scroll position the viewport would have by aligning the x-coordinate x of the viewport scrolling area with the left of the viewport and aligning the y-coordinate y of the viewport scrolling area with the top of the viewport.
If position is the same as the viewport's current scroll position, and the viewport does not have an ongoing smooth scroll, abort these steps.
Let task be these steps:
Fire an event named scroll
that bubbles at the
Document
object.
Perform a scroll of the viewport to position, with the set of steps task, and the
Document
's root element as the associated element, if there is one, or null otherwise, and the scroll behavior being the
value of the behavior
dictionary member of options.
When the scrollTo(x, y, options)
method is invoked, the
user agent must act as if the scroll()
method was invoked with the same arguments.
When the scrollBy(x, y, options)
method is invoked, the
user agent must act as if the scroll()
method was invoked with
x plus scrollX
as first argument and y plus
scrollY
as second argument.
The screenX
attribute must return the x-coordinate,
relative to the origin of the screen of the output device, of the left of
the client window as number of pixels, or zero if there is no such
thing.
The screenY
attribute must return the y-coordinate,
relative to the origin of the screen of the output device, of the top of
the client window as number of pixels, or zero if there is no such
thing.
The outerWidth
attribute must return the width of the
client window. If there is no client window this
attribute must return zero.
The outerHeight
attribute must return the height of the
client window. If there is no client window this
attribute must return zero.
open()
methodHTML defines the open()
method but has no defined effect for the third argument, features.
[HTML]
This specification defines the effect of the features argument for user agents that do not opt to ignore it, as follows:
If the method does not result in a new auxiliary browsing context being created, terminate these steps.
Let target be the new auxiliary browsing context.
Let tokens be the result of splitting features on commas.
Let parsed features be a new empty dictionary.
Token loop: For each token token in tokens, follow these substeps:
Let input be token.
Let position point at the first character of input.
Collect a sequence of characters that are not space
characters nor "=
" (U+003D). Let name be the collected characters, converted to ASCII
lowercase.
If name is in parsed features or if name is not a supported open()
feature name,
continue token loop.
If the character at position is not "=
" (U+003D), continue token loop.
Advance position by one.
If position is past the end of input, continue token loop.
Collect a sequence of characters that are any characters. Let raw value be the collected characters.
Let value be the result of invoking the rules for parsing integers on raw value.
If value is an error, continue token loop.
Set name in parsed features to value.
If left
is present in parsed features, follow these substeps:
Let x be the value of left
.
Optionally, clamp x in a user-agent-defined manner so that the window does not move outside the available space.
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.
If top
is present in parsed features, follow these substeps:
Let y be the value of top
.
Optionally, clamp y in a user-agent-defined manner so that the window does not move outside the available space.
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.
If width
is present in parsed features, follow these substeps:
Let x be the value of width
.
Optionally, clamp x in a user-agent-defined manner so that the window does not get too small or bigger than the available space.
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.
Optionally, move target's window in a user-agent-defined manner so that it does not grow outside the available space.
If height
is present in parsed features, follow these substeps:
Let y be the value of height
.
Optionally, clamp y in a user-agent-defined manner so that the window does not get too small or bigger than the available space.
Optionally, size target's window by moving its bottom edge such that the distance between the top and bottom edges of the viewport are x CSS pixels of target.
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:
The width of the viewport.
The height of the viewport.
The left position of the window.
The top position of the window.
MediaQueryList
InterfaceA MediaQueryList
object has an associated media query list set on creation and an associated
list of media query list listeners, which is initially empty.
If the associated media query list changes in evaluation then, for each
listener in the list of media query list listeners — in
appending order, queue a task that invokes the listener,
passing as argument the MediaQueryList
object.
A simple piece of code that detects changes in the orientation of the viewport can be written as follows:
function handleOrientationChange(mql) { if(mql.matches) // landscape … else … } var mql = matchMedia("(orientation:landscape)") mql.addListener(handleOrientationChange)
interface MediaQueryList { readonly attribute DOMString media; readonly attribute boolean matches; void addListener(MediaQueryListListener listener); void removeListener(MediaQueryListListener listener); }; callback MediaQueryListListener = void (MediaQueryList list);
The media
attribute must return the
serialized form of the associated media query list.
The matches
attribute must return true if the associated media query list
matches the state of the rendered Document
and false if it does not.
When the addListener(listener)
method is invoked listener must
be appended to the list of media query list listeners, unless
it is already in the list of media query list listeners.
When the removeListener(listener)
method is invoked
listener must be removed from the list of media query list listeners.
Screen
InterfaceAs its name suggests, the Screen
interface represents information about the screen of the output device.
interface Screen { readonly attribute double availWidth; readonly attribute double availHeight; readonly attribute double width; readonly attribute double 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.
The colorDepth
and pixelDepth
attributes are useless but are
included for compatibility.
Document
Interfacepartial interface Document { Element? elementFromPoint(double x, double y); sequence<Element> elementsFromPoint(double x, double y); CaretPosition? caretPositionFromPoint(double x, double y); };
The elementFromPoint(x, y)
method must follow these steps:
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.
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.
If the document has a root element, return the root element and terminate these steps.
Return null.
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:
Let sequence be a new empty sequence.
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.
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.
If the document has a root element, and the last item in sequence is not the root element, append the root element to sequence.
Return sequence.
The caretPositionFromPoint(x, y)
method must return the
result of running these steps:
If there is no viewport associated with the document, return null.
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.
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.
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 node corresponding to the text entry widget.
The amount of 16-bit units to the left of where the text insertion point indicator would have inserted.
null
Otherwise, return a caret position where the
caret range is a collapsed
Range
object for the position
where the text insertion point indicator would have been inserted when applying the transforms that apply to the descendants of the
viewport, and the other properties are set as follows:
The startContainer
of the caret range.
The startOffset
of
the caret range.
The specifics of hit testing are out of scope of this
specification and therefore the exact details of
elementFromPoint()
and
caretPositionFromPoint()
are therefore too. Hit testing will hopefully be defined in a future
revision of CSS or HTML.
CaretPosition
InterfaceA 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:
If caret range is not null:
Let list be the result of invoking the
getClientRects()
method on the
range.
If list is empty, return null.
Return the DOMRect
object in list at index 0.
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.
Return null.
Element
Interfacedictionary ScrollOptionsHorizontal : ScrollOptions { double x; }; dictionary ScrollOptionsVertical : ScrollOptions { double y; }; partial interface Element { DOMRectList getClientRects(); DOMRect getBoundingClientRect(); void scrollIntoView(optional boolean top = true, optional ScrollOptions options); attribute (double or ScrollOptionsVertical) scrollTop; attribute (double or ScrollOptionsHorizontal) scrollLeft; readonly attribute double scrollWidth; readonly attribute double scrollHeight; readonly attribute double clientTop; readonly attribute double clientLeft; readonly attribute double clientWidth; readonly attribute double clientHeight; };
The getClientRects()
method, when invoked, must return the result of the following algorithm:
If the element on which it was invoked does not have an associated
layout box return an empty DOMRectList
object and stop
this algorithm.
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.
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:
Let list be the result of invoking
getClientRects()
on the
same element this method was invoked on.
If the list is empty return a DOMRect
object whose top
,
right
,
bottom
and
left
members are zero.
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.
The following snippet gets the dimensions of the first
div
element in a document:
var example = document.getElementsByTagName("div")[0].getBoundingClientRect(); var exampleWidth = example.width; var exampleHeight = example.height;
The scrollIntoView(top, options)
method must run these steps:
If the element does not have any associated layout box terminate these steps.
Scroll the element into view with the
align to top flag set if top is true, and the scroll behavior being the value of the behavior
dictionary member of options.
Optionally perform some other action that brings the element to the user's attention.
The scrollTop
attribute must return the result of running these steps:
If the element does not have any associated CSS layout box or the
element is the root element and the Document
is in
quirks mode return zero and terminate these steps.
If the element is the root element return the value of
scrollY
.
If the element is the HTML body
element,
the Document
is in quirks mode, and the element
does not have any overflow, return the value of
scrollY
.
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 scrollTop
attribute these steps must be run:
If the given value is a ScrollOptionsVertical
object, and the y
dictionary member is not present, abort these steps.
If the given value is a ScrollOptionsVertical
object, let y be the value of the y
dictionary member.
Otherwise, let y be the given value.
If the element does not have any associated CSS layout box, the
element is the root element and the Document
is in
quirks mode, or the element has no associated scrolling box, or the element has no
overflow, terminate these steps.
If the element is the root element invoke
scroll()
with zero as first
argument and y as second, and, if the given value is a ScrollOptionsVertical
object, the given value as the third argument.
If the element is the HTML body
element,
the Document
is in quirks mode, and the element
does not have any vertical overflow, invoke
scroll()
with
scrollX
as first
argument and y as second, and, if the given value is a ScrollOptionsVertical
object, the given value as the third argument.
Scroll the element to
scrollLeft
,y, with the scroll behavior being the value of the behavior
dictionary
member if the given value is a ScrollOptionsVertical
object, or auto
otherwise.
The scrollLeft
attribute must return the result of running these steps:
If the element does not have any associated CSS layout box or the
element is the root element and the Document
is in
quirks mode return zero and terminate these steps.
If the element is the root element return the value of
scrollX
.
If the element is the HTML body
element,
the Document
is in quirks mode, and the element
does not have any overflow, return the value of
scrollX
.
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 scrollLeft
attribute these steps must be run:
If the given value is a ScrollOptionsHorizontal
object, and the x
dictionary member is not present, abort these steps.
If the given value is a ScrollOptionsHorizontal
object, let x be the value of the x
dictionary member.
Otherwise, let x be the given value.
If the element does not have any associated CSS layout box, the
element is the root element and the Document
is in
quirks mode, or the element has no associated scrolling box, or the element has no
overflow, terminate these steps.
If the element is the root element invoke
scroll()
with
x as first argument and zero as second, and, if the given value is a ScrollOptionsHorizontal
object, the given value as the third
argument.
If the element is the HTML body
element,
the Document
is in quirks mode, and the element
does not have any vertical overflow, invoke
scroll()
with
x as first argument and
scrollY
as second, and, if the given value is a ScrollOptionsHorizontal
object, the given value as the third
argument.
Scroll the element to
x,scrollTop
, with the scroll behavior being the value of the behavior
dictionary
member if the given value is a ScrollOptionsHorizontal
object, or auto
otherwise.
The scrollWidth
attribute must return the result of running these steps:
If the element does not have any associated CSS layout box return zero and terminate these steps.
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.
If the element is the root element and the
Document
is not in
quirks mode
return max(viewport scrolling area width, viewport width).
If the element is the HTML body
element
and the Document
is in
quirks mode
return max(viewport scrolling area width, viewport width).
Return the width of the element's scrolling area.
The scrollHeight
attribute must return the result of running these steps:
If the element does not have any associated CSS layout box return zero and terminate these steps.
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.
If the element is the root element and the
Document
is not in
quirks mode
return max(viewport scrolling area height, viewport height).
If the element is the HTML body
element
and the Document
is in
quirks mode
return max(viewport scrolling area height, viewport height).
Return the height of the element's scrolling area.
The clientTop
attribute must run these steps:
If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.
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:
If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.
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:
If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.
If the element is the root element and the element's document is not in quirks mode, or
if the element is the HTML body
element and the element's document is in
quirks mode, return the viewport width excluding the size of a rendered scroll bar
(if any).
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:
If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.
If the element is the root element and the element's document is not in quirks mode, or
if the element is the HTML body
element and the element's document is in
quirks mode, return the viewport height excluding the size of a rendered scroll
bar (if any).
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.
getClientRects()
and
getBoundingClientRect()
methodsThe getClientRects()
and 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 MembersTo 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:
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.
Let element bounding border box be the box that the return value of invoking
getBoundingClientRect()
on element represents.
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.
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.
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.
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.
Let element width be the distance between element edge C and element edge D.
Let scrolling box width be the distance between scrolling box edge C and scrolling box edge D.
Let position be the scroll position scrolling box would have by following these steps:
If the align to top flag is set align element edge A with scrolling box edge A.
Otherwise, the align to top flag is not set; align element edge B with scrolling box edge B.
Do nothing.
Align element edge C with scrolling box edge C.
Align element edge D with scrolling box edge D.
If position is the same as scrolling box's current scroll position, and scrolling box does not have an ongoing smooth scroll, abort these steps.
Let associated element be the element.
Let task be these steps:
Fire an event
named scroll
at associated element.
Let associated element be the Document
's root element, if there is one, or null otherwise.
Let task be these steps:
Fire an event
named scroll
that bubbles at the
Document
object associated with the viewport.
Perform a scroll of scrolling box to position, with the set of steps task, associated element as the associated element and behavior as the scroll behavior.
To scroll an element element to x,y optionally with a scroll behavior behavior (which is
auto
if omitted) means to:
Let box be element's associated scrolling box.
Let x be max(0, min(x, element scrolling area width - element padding edge width)).
Let x be min(0, max(x, element padding edge width - element scrolling area width)).
Let y be max(0, min(y, element scrolling area height - element padding edge height)).
Let y be min(0, max(y, element padding edge height - element scrolling area height)).
Let position be the scroll position box would have by aligning scrolling area x-coordinate x with the left of box and aligning scrolling area y-coordinate y with the top of box.
If position is the same as box's current scroll position, and box does not have an ongoing smooth scroll, abort these steps.
Let task be these steps:
Fire an event named
scroll
at the element.
Perform a scroll of box to position, with the set of steps task, element as the associated element and behavior as the scroll behavior.
HTMLElement
Interfacepartial interface HTMLElement { readonly attribute Element? offsetParent; readonly attribute double offsetTop; readonly attribute double offsetLeft; readonly attribute double offsetWidth; readonly attribute double offsetHeight; };
The offsetParent
attribute must return the result of running these steps:
If any of the following holds true return null and terminate this algorithm:
body
element.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:
body
element.td
, th
, or table
.Return null.
The offsetTop
attribute must return the result of running these steps:
If the element is the HTML body
element
or does not have any associated CSS layout box return zero and terminate
this algorithm.
If the 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.
Return the result of subtracting the y-coordinate of the top
padding edge of the first CSS layout box associated with
the 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.
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:
If the element is the HTML body
element or does not have any associated CSS layout box return zero
and terminate this algorithm.
If the 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.
Return the result of subtracting the x-coordinate of the left
padding edge of the first CSS layout box associated with
the 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:
If the element does not have any associated CSS layout box return zero and terminate this algorithm.
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:
If the element does not have any associated CSS layout box return zero and terminate this algorithm.
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.
Range
InterfaceThe 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:
getClientRects()
on the
element.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:
Let list be the result of invoking
getClientRects()
on the
same range this method was invoked on.
If list is empty return a
DOMRect
object whose
top
,
right
,
bottom
and
left
members are zero.
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.
MouseEvent
InterfaceThe 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:
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.
Let offset be the value of the scrollX
attribute of the event's associated
Window
object, if there is one, or zero otherwise.
Return the sum of offset and the value of the event's clientX
attribute.
The pageY
attribute must follow these steps:
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.
Let offset be the value of the scrollX
attribute of the event's associated
Window
object, if there is one, or zero otherwise.
Return the sum of offset and the value of the event's 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 clientX
.
The y
attribute must return the value of clientY
.
The offsetX
attribute must follow these steps:
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.
Return the value of the event's pageX
attribute.
The offsetY
attribute must follow these steps:
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.
Return the value of the event's pageY
attribute.
DOMRectList
InterfaceThe DOMRectList
interface consists of an ordered list of DOMRect
objects.
[ArrayClass] interface DOMRectList { readonly attribute unsigned long length; getter DOMRect item(unsigned long index); };
The length
attribute must return the total number of DOMRect
objects associated with
the object.
The item(index)
method, when invoked, must throw an
IndexSizeError
exception when index is
greater than the number of DOMRect
objects associated with the object. Otherwise, the DOMRect
object at
index must be returned.
DOMRect
and DOMRectReadOnly
InterfacesObjects implementing the DOMRect
or DOMRectReadOnly
interface represent a rectangular box. The type of box is specified by the
method or attribute that returns a DOMRect
or DOMRectReadOnly
object. The interfaces are identical except the attributes of
DOMRectReadOnly
are readonly.
[Constructor(unrestricted double left, unrestricted double top, unrestricted double width, unrestricted double height)] interface DOMRect { attribute unrestricted double top; attribute unrestricted double right; attribute unrestricted double bottom; attribute unrestricted double left; attribute unrestricted double width; attribute unrestricted double height; }; interface DOMRectReadOnly { readonly attribute unrestricted double top; readonly attribute unrestricted double right; readonly attribute unrestricted double bottom; readonly attribute unrestricted double left; readonly attribute unrestricted double width; readonly attribute unrestricted double height; }; typedef (DOMRect or DOMRectReadOnly) DOMRectAny;
The DOMRect(left, top, width, height)
constructor, when
invoked, must run the following steps:
Let right be left plus width.
Let bottom be top plus height.
Return a new DOMRect
object with top set to top, right
set to right, bottom set to bottom and left set to
left.
The top
attribute gives the y-coordinate, relative to the viewport origin, of the top of
the rectangle box. On getting, it must return the current value. On setting, the current value must be set to the new value.
The right
attribute gives the x-coordinate, relative to the viewport origin, of the
right of the rectangle box. On getting, it must return the current value. On setting, the current value must be set to the new value.
The bottom
attribute gives the y-coordinate, relative to the viewport origin, of the
bottom of the rectangle box. On getting, it must return the current value. On setting, the current value must be set to the new value.
The left
attribute gives the x-coordinate, relative to the viewport origin, of the left
of the rectangle box. On getting, it must return the current value. On setting, the current value must be set to the new value.
The width
attribute, on getting, must return the value of right
minus
left
. On setting, the right
attribute must be set to the new value plus the value of
left
.
The height
attribute, on getting, must return the value of bottom
minus top
. On setting, the bottom
attribute must be set to the new value plus the value
of top
.
The top
, right
,
bottom
, left
,
width
and height
attributes of the
DOMRectReadOnly
interface, on getting, must behave the same as the attribute of the same name on the DOMRect
interface.
DOMPoint
Interface[Constructor(optional DOMPointInit point), Constructor(unrestricted double x, unrestricted double y, optional unrestricted double z = 0, optional unrestricted double w = 1)] interface DOMPoint { attribute unrestricted double x; attribute unrestricted double y; attribute unrestricted double z; attribute unrestricted double w; }; dictionary DOMPointInit { unrestricted double x = 0; unrestricted double y = 0; unrestricted double z = 0; unrestricted double w = 1; };
The DOMPoint()
constructor, when invoked, must run the following steps:
If invoked with one argument, follow these substeps:
Let point be the argument.
Let x be the x
dictionary member of point.
Let y be the y
dictionary member of point.
Let z be the z
dictionary member of point.
Let w be the w
dictionary member of point.
Otherwise, let x, y, z and w be the given arguments, respectively.
Return a new DOMPoint
object with the x
, y
,
z
and w
attributes set to x, y, z and w,
respectively.
The x
attribute gives the x coordinate of the point. On getting, it must return the current value. On setting,
it must set the current value to the new value.
The y
attribute gives the y coordinate of the point. On getting, it must return the current value. On setting,
it must set the current value to the new value.
The z
attribute gives the z coordinate of the point. On getting, it must return the current value. On setting,
it must set the current value to the new value.
The w
attribute gives the perspective of the point. On getting, it must return the current value. On setting,
it must set the current value to the new value.
DOMQuad
InterfaceObjects implementing the DOMQuad
interface represents a quadrilateral shape. DOMQuad
objects have an associated
bounding rectangle set to a DOMRectReadOnly
object when created.
[Constructor(DOMPointInit p1, DOMPointInit p2, DOMPointInit p3, DOMPointInit p4), Constructor(DOMRectAny rect)] interface DOMQuad { [SameObject] readonly attribute DOMPoint p1; [SameObject] readonly attribute DOMPoint p2; [SameObject] readonly attribute DOMPoint p3; [SameObject] readonly attribute DOMPoint p4; [SameObject] readonly attribute DOMRectReadOnly bounds; };
The DOMQuad()
constructor, when invoked, must run the following steps:
If invoked with one argument, follow these substeps:
Let rect be the argument.
Let top, right, bottom and left be rect's the value of top
,
right
, bottom
and left
attributes,
respectively.
Let point 1 be a new DOMPoint
object with x
set to left,
y
set to top, z
set to zero and w
set to
one.
Let point 2 be a new DOMPoint
object with x
set to right,
y
set to top, z
set to zero and w
set to
one.
Let point 3 be a new DOMPoint
object with x
set to right,
y
set to bottom, z
set to zero and w
set to
one.
Let point 4 be a new DOMPoint
object with x
set to left,
y
set to bottom, z
set to zero and w
set to
one.
Let bounds be a new DOMRectReadOnly
object with its attributes set to the values of the namesake attributes in
rect.
Otherwise, follow these substeps:
Let p1, p2, p3 and p4 be the given arguments, in the same order.
Let point 1 be a new DOMPoint
object with its attributes set to the values of the namesake dictionary members in
p1.
Let point 2 be a new DOMPoint
object with its attributes set to the values of the namesake dictionary members in
p2.
Let point 3 be a new DOMPoint
object with its attributes set to the values of the namesake dictionary members in
p3.
Let point 4 be a new DOMPoint
object with its attributes set to the values of the namesake dictionary members in
p4.
Let bounds be a new DOMRectReadOnly
object describing the bounding box of point 1, point 2, point
3 and point 4.
Return a new DOMQuad
with p1
set to point 1, p2
set to
point 2, p3
set to point 3 and p4
set to point 4, and
let the associated bounding rectangle be bounds.
The p1
attribute must return the DOMPoint
it was set to.
The p2
attribute must return the DOMPoint
it was set to.
The p3
attribute must return the DOMPoint
it was set to.
The p4
attribute must return the DOMPoint
it was set to.
The bounds
attribute must return the associated bounding rectangle.
The associated bounding rectangle is live; whenever the objects in p1
, p2
,
p3
or p4
are changed, the associated bounding rectangle must update its
attributes as appropriate to describe the new bounding box of the four points.
GeometryUtils
Interfaceenum CSSBoxType { "margin", "border", "padding", "content" }; dictionary BoxQuadOptions { CSSBoxType box = "border"; GeometryNode relativeTo; }; dictionary ConvertCoordinateOptions { CSSBoxType fromBox = "border"; CSSBoxType toBox = "border"; }; [NoInterfaceObject] interface GeometryUtils { sequence<DOMQuad> getBoxQuads(BoxQuadOptions options); DOMQuad convertQuadFromNode(DOMQuad quad, GeometryNode from, optional ConvertCoordinateOptions options); DOMQuad convertRectFromNode(DOMRectAny rect, GeometryNode from, optional ConvertCoordinateOptions options); DOMPoint convertPointFromNode(DOMPointInit point, GeometryNode from, optional ConvertCoordinateOptions options); }; Text implements GeometryUtils; 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:
...
The convertQuadFromNode(quad, from, options)
method
must run the following steps:
...
The convertRectFromNode(rect, from, options)
method
must run the following steps:
...
The convertPointFromNode(point, from, options)
method must run the following steps:
...
Whenever a viewport has its width or height changed (e.g. as a result of the user resizing the browser window, or zooming in, or an
iframe
element's dimensions are changed), the user agent must queue a task to
fire an event event named
resize
at the Window
object associated with that
viewport. If such a resize is ongoing over a period of time, the user agent must queue that
task at a user-agent-defined interval while the resize is ongoing.
Whenever a viewport gets scrolled in response to user interaction, the user agent must queue a task to
fire an event named
scroll
that bubbles at the Document
object associated with that viewport. If such a scroll is
ongoing over a period of time, the user agent must queue that task at a user-agent-defined interval
while the scroll is ongoing.
Whenever an element gets scrolled in response to user interaction, the user agent must queue a task to
fire an event named
scroll
at the element. If such a scroll is ongoing over a period of time, the user agent must
queue that task at a user-agent-defined interval while the scroll is ongoing.
The features in this section should be moved to some other specification.
Name: scroll-behavior Value: instant | smooth Initial: instant Applies to: scrolling boxes Inherited: no Computed value: specified value Media: visual Animatable: no Canonical Order: per grammar
The 'scroll-behavior' property specifies the scrolling behavior for a scrolling box, when scrolling happens due to navigation or CSSOM scrolling 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 viewport instead.
The 'scroll-behavior' property of the HTML body
element is not propagated to the viewport.
The scrolling box is scrolled in an instant fashion.
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 should follow platform convensions, if any.
User agents may ignore this property.
The editors would like to thank Alan Stearns, Alexey Feldgendler, Björn Höhrmann, Dan Bates, David Vest, Elliott Sprehn, Garrett Smith, Hallvord R. M. Steen, Kang-Hao Lu, Leif Arne Storset, Luiz Agostini, Maciej Stachowiak, Michael Dyck, Mike Wilson, Morten Stenshorne, Olli Pettay, Pavel Curtis, Peter-Paul Koch, Rachel Kmetz, Robert O'Callahan, Sam Weinig, Scott Johnson, Sebastian Zartner, Stewart Brodie, Sylvain Galineau, Tab Atkins, Tarquin Wilton-Jones, Thomas Moore, and Xiaomei Ji for their contributions to this document.
Special thanks to the Microsoft employees who first implemented many of the features specified in this draft, which were first widely deployed by the Windows Internet Explorer browser.