1. 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!)
2. Terminology
Terminology used in this specification is from DOM, CSSOM and HTML. [DOM] [CSSOM] [HTML]
The HTML body
element#the-html-body-elementReferenced in:2. Terminology5. Extensions to the Document Interface (2) (3) (4)6. Extensions to the Element Interface (2) (3) (4) (5) (6) (7) (8) (9)7. Extensions to the HTMLElement Interface (2) (3) (4) is the first body
HTML element child of the root HTML element html
.
Content edge, padding edge#padding-edgeReferenced in:2. Terminology (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16)6. Extensions to the Element Interface (2) (3) (4) (5) (6) (7) (8)6.1. Element Scrolling Members (2) (3) (4)7. Extensions to the HTMLElement Interface (2)10. Extensions to the MouseEvent Interface (2), border edge#border-edgeReferenced in:6. Extensions to the Element Interface (2) (3) (4)7. Extensions to the HTMLElement Interface (2) (3) (4) (5) (6)8. Extensions to the HTMLImageElement Interface (2), margin edge#margin-edgeReferenced in:2. Terminology (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16), and viewport#viewportReferenced in:2. Terminology (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15)3.1. Scrolling4. Extensions to the Window Interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17) (18) (19) (20) (21) (22) (23) (24) (25) (26) (27) (28) (29) (30)5. Extensions to the Document Interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17) (18)6. Extensions to the Element Interface (2) (3) (4) (5) (6) (7) (8) (9) (10)6.1. Element Scrolling Members (2) (3) (4)10. Extensions to the MouseEvent Interface (2)12.1. Resizing viewports12.2. Scrolling (2)12.3. Event summary (2)13.1. Smooth Scrolling: The scroll-behavior Property are defined by CSS.
Elements and viewports have an associated scrolling box#scrolling-boxReferenced in:2. Terminology (2) (3)3.1. Scrolling (2) (3)6. Extensions to the Element Interface (2) (3)6.1. Element Scrolling Members (2) (3)13.1. Smooth Scrolling: The scroll-behavior Property (2) (3) (4) if has a scrolling mechanism or it overflows its content area and the used value of the overflow-x or overflow-y property is hidden. [CSS3-BOX]
An element is potentially scrollable#potentially-scrollableReferenced in:2. Terminology5. Extensions to the Document Interface6. Extensions to the Element Interface (2) (3) (4) (5) (6) (7) 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 visible. -
The element’s used value of the overflow-x or overflow-y properties is not visible.
Note: An element that is potentially scrollable might not have a scrolling box. For instance, it could have overflow set to auto but not have its content overflowing its content area.
A scrolling box of a viewport or element has two overflow directions#overflow-directionsReferenced in:2. Terminology (2) (3) (4) (5) (6) (7) (8) (9) (10)4. Extensions to the Window Interface (2) (3) (4)6.1. Element Scrolling Members (2) (3) (4), depending on the viewport’s or element’s block flow direction and inline base direction, as follows:
- If the block flow direction is top-to-bottom and the inline base direction is left-to-right
- If the block flow direction is left-to-right and the inline base direction is left-to-right
- Rightward and downward.
- If the block flow direction is top-to-bottom and the inline base direction is right-to-left
- If the block flow direction is right-to-left and the inline base direction is left-to-right
- Leftward and downward.
- If the block flow direction is right-to-left and the inline base direction is right-to-left
- Leftward and upward.
- If the block flow direction is left-to-right and the inline base direction is right-to-left
- Rightward and upward.
The term scrolling area#scrolling-areaReferenced in:2. Terminology (2)3.1. Scrolling4. Extensions to the Window Interface (2) (3) (4) (5) (6)6. Extensions to the Element Interface (2) (3) (4) (5) (6) (7) (8)6.1. Element Scrolling Members (2) (3) (4) (5) (6) 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 origin of a scrolling area is the origin of the initial containing block if the scrolling area is a viewport, and otherwise the top left padding edge of the element when the element has its default scroll position. The x-coordinate increases rightwards, and the y-coordinate increases downwards.
The beginning edges#beginning-edgesReferenced in:3.1. Scrolling (2)6.1. Element Scrolling Members (2) of a particular set of edges of a box or element are the following edges:
- If the overflow directions are rightward and downward
- The top and left edges.
- If the overflow directions are leftward and downward
- The top and right edges.
- If the overflow directions are leftward and upward
- The bottom and right edges.
- If the overflow directions are rightward and upward
- The bottom and left edges.
The ending edges#ending-edgesReferenced in:6.1. Element Scrolling Members (2) of a particular set of edges of a box or element are the following edges:
- If the overflow directions are rightward and downward
- The bottom and right edges.
- If the overflow directions are leftward and downward
- The bottom and left edges.
- If the overflow directions are leftward and upward
- The top and left edges.
- If the overflow directions are rightward and upward
- The top and right edges.
The term CSS layout box#css-layout-boxReferenced in:2. Terminology (2) (3) (4)6. Extensions to the Element Interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15)7. Extensions to the HTMLElement Interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14)8. Extensions to the HTMLImageElement Interface (2) (3) (4) 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#svg-layout-boxReferenced in:2. Terminology (2)6. Extensions to the Element Interface 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#layout-boxReferenced in:5. Extensions to the Document Interface (2)6. Extensions to the Element Interface (2) refers to either a CSS layout box or an SVG layout box.
The term transforms#transformsReferenced in:5. Extensions to the Document Interface (2) (3) (4) (5)5.1. The CaretPosition Interface6. Extensions to the Element Interface (2) (3) (4) (5) (6)7. Extensions to the HTMLElement Interface (2) (3) (4) (5) (6)8. Extensions to the HTMLImageElement Interface (2)9. Extensions to the Range Interface10. Extensions to the MouseEvent Interface (2)Changes From 4 August 2011 To 17 December 2013 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.
2.1. 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.
2.2. Zooming
There are two kinds of zoom, page zoom#page-zoomReferenced in:4. Extensions to the Window InterfaceChanges From 4 August 2011 To 17 December 2013 which affects the size of the initial viewport, and pinch zoom#pinch-zoomReferenced in:4. Extensions to the Window InterfaceChanges From 4 August 2011 To 17 December 2013 which acts like a magnifying glass and does not affect the initial viewport or actual viewport. [CSS-DEVICE-ADAPT]
3. Common Infrastructure
3.1. Scrolling
When a user agent is to perform a scroll#perform-a-scrollReferenced in:3.1. Scrolling4. Extensions to the Window Interface6.1. Element Scrolling Members (2) 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:
- 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
- behavior is
When a user agent is to perform a smooth scroll#concept-smooth-scrollReferenced in:3.1. Scrolling (2) (3)4. Extensions to the Window Interface6.1. Element Scrolling Members (2) 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#smooth-scroll-abortedReferenced in:3.1. Scrolling, either by an algorithm or by the user.
When a user agent is to perform an instant scroll#concept-instant-scrollReferenced in:3.1. Scrolling 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.
- Perform a scroll of viewport to position, and document’s root element as the associated element, if there is one, or null otherwise.
Note: This algorithm is used when navigating to the #top
fragment identifier, as defined in HTML. [HTML]
3.2. WebIDL values
When asked to normalize non-finite values#normalize-non-finite-valuesReferenced in:4. Extensions to the Window Interface (2)6. Extensions to the Element Interface (2) (3) (4) (5) (6) 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]
4. Extensions to the Window
Interface
enum ScrollBehavior#enumdef-scrollbehaviorReferenced in:4. Extensions to the Window Interface { "auto", "instant", "smooth" }; dictionary ScrollOptions#dictdef-scrolloptionsReferenced in:4. Extensions to the Window Interface6. Extensions to the Element Interface { ScrollBehavior behavior#dom-scrolloptions-behaviorReferenced in:4. Extensions to the Window Interface6. Extensions to the Element Interface6.1. Element Scrolling Members = "auto"; }; dictionary ScrollToOptions#dictdef-scrolltooptionsReferenced in:4. Extensions to the Window Interface (2) (3) (4) (5)6. Extensions to the Element Interface (2) (3) (4) (5) : ScrollOptions { unrestricted double left#dom-scrolltooptions-leftReferenced in:4. Extensions to the Window Interface (2) (3) (4)6. Extensions to the Element Interface (2) (3) (4) (5) (6); unrestricted double top#dom-scrolltooptions-topReferenced in:4. Extensions to the Window Interface (2) (3) (4)6. Extensions to the Element Interface (2) (3) (4) (5) (6); }; 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)#dom-window-matchmediaReferenced in:2.1. CSS pixels4. Extensions to the Window Interface method is invoked these steps must be run:
- Let parsed media query list be the result of parsing query.
- Return a new
MediaQueryList
object, with the context object’s associatedDocument
as the document, with parsed media query list as its associated media query list.
The screen#dom-window-screenReferenced in:4. Extensions to the Window Interface (2) attribute must return the Screen
object
associated with the Window
object.
Note: Accessing screen
through a WindowProxy
object might yield different
results when the Document
is navigated.
The moveTo(x, y)#dom-window-movetoReferenced in:4. Extensions to the Window InterfaceChanges From 4 August 2011 To 17 December 2013 method must follow these steps:
-
Optionally, terminate these steps.
-
Let target be the browsing context of the context object.
-
Let source be the responsible browsing context of the incumbent settings object.
-
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)#dom-window-movebyReferenced in:4. Extensions to the Window InterfaceChanges From 4 August 2011 To 17 December 2013 method must follow these steps:
-
Optionally, terminate these steps.
-
Let target be the browsing context of the context object.
-
Let source be the responsible browsing context of the incumbent settings object.
-
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 rightward and y CSS pixels of target downward.
The resizeTo(x, y)#dom-window-resizetoReferenced in:4. Extensions to the Window InterfaceChanges From 4 August 2011 To 17 December 2013 method must follow these steps:
-
Optionally, terminate these steps.
-
Let target be the browsing context of the context object.
-
Let source be the responsible browsing context of the incumbent settings object.
-
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)#dom-window-resizebyReferenced in:4. Extensions to the Window InterfaceChanges From 4 August 2011 To 17 December 2013 method must follow these steps:
-
Optionally, terminate these steps.
-
Let target be the browsing context of the context object.
-
Let source be the responsible browsing context of the incumbent settings object.
-
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 rightward 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#allowed-to-resize-and-moveReferenced in:4. Extensions to the Window Interface (2) (3) (4) 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#dom-window-innerwidthReferenced in:4. Extensions to the Window InterfaceChanges From 4 August 2011 To 17 December 2013 attribute must return the viewport width including the size of a rendered scroll bar (if any), or zero if there is no viewport.
The innerHeight#dom-window-innerheightReferenced in:4. Extensions to the Window Interface 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#dom-window-scrollxReferenced in:4. Extensions to the Window Interface (2) (3)6. Extensions to the Element Interface (2) (3) (4) (5)10. Extensions to the MouseEvent Interface 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#dom-window-pagexoffsetReferenced in:4. Extensions to the Window Interface attribute must return the value returned by the scrollX
attribute.
The scrollY#dom-window-scrollyReferenced in:4. Extensions to the Window Interface (2) (3)6. Extensions to the Element Interface (2) (3) (4)10. Extensions to the MouseEvent Interface 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#dom-window-pageyoffsetReferenced in:4. Extensions to the Window Interface attribute must return the value returned by the scrollY
attribute.
When the scroll()#dom-window-scrollReferenced in:4. Extensions to the Window Interface (2) (3) (4)6. Extensions to the Element Interface (2) (3) (4) (5) (6)Changes From 17 December 2013 method is invoked these steps must be run:
-
If invoked with one argument, follow these substeps:
-
Let options be the argument.
-
Let x be the value of the
left
dictionary member of options, if present, or the viewport’s current scroll position on the x axis otherwise. -
Let y be the value of the
top
dictionary member of options, if present, or the viewport’s current scroll position on the y axis otherwise.
-
-
If invoked with two arguments, follow these substeps:
-
Let options be null converted to a
ScrollToOptions
dictionary. [WEBIDL] -
Let x and y be the arguments, respectively.
-
-
Normalize non-finite values for x and y.
-
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.
-
- If the viewport has rightward overflow direction
- Let x be max(0, min(x, viewport scrolling area width - viewport width)).
- If the viewport has leftward overflow direction
- Let x be min(0, max(x, viewport width - viewport scrolling area width)).
-
- If the viewport has downward overflow direction
- Let y be max(0, min(y, viewport scrolling area height - viewport height)).
- If the viewport has upward overflow direction
- 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 document be the viewport’s associated
Document
. -
Perform a scroll of the viewport to position, 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()#dom-window-scrolltoReferenced in:4. Extensions to the Window Interface (2)Changes From 17 December 2013 method is invoked, the
user agent must act as if the scroll()
method was invoked with the same arguments.
When the scrollBy()#dom-window-scrollbyReferenced in:4. Extensions to the Window Interface (2)Changes From 17 December 2013 method is invoked, the user agent must run these steps:
-
If invoked with two arguments, follow these substeps:
-
Let options be null converted to a
ScrollToOptions
dictionary. [WEBIDL] -
Let x and y be the arguments, respectively.
-
Let the
left
dictionary member of options have the value x. -
Let the
top
dictionary member of options have the value y.
-
-
Normalize non-finite values for the
left
andtop
dictionary members of options. -
Act as if the
scroll()
method was invoked with options as the only argument.
The screenX#dom-window-screenxReferenced in:4. Extensions to the Window Interface 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#dom-window-screenyReferenced in:4. Extensions to the Window Interface 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#dom-window-outerwidthReferenced in:4. Extensions to the Window Interface attribute must return the width of the client window. If there is no client window this attribute must return zero.
The outerHeight#dom-window-outerheightReferenced in:4. Extensions to the Window Interface attribute must return the height of the client window. If there is no client window this attribute must return zero.
The devicePixelRatio#dom-window-devicepixelratioReferenced in:4. Extensions to the Window InterfaceChanges From 4 August 2011 To 17 December 2013 attribute must return the result of the following algorithm:
-
If there is no output device, return 1 and abort these steps.
-
Let CSS pixel size be the size of a CSS pixel at the current page zoom scale factor and at a pinch zoom scale factor of 1.0.
-
Let device pixel size be the vertical size of a device pixel of the output device.
-
Return the result of dividing CSS pixel size by device pixel size.
4.1. The features argument to the open()
method
HTML 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 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.
-
A supported open()
feature name#supported-open-feature-nameReferenced in:4.1. The features argument to the open() method is one of the following:
- width#supported-open-feature-name-widthReferenced in:4.1. The features argument to the open() method (2)
- The width of the viewport.
- height#supported-open-feature-name-heightReferenced in:4.1. The features argument to the open() method (2)
- The height of the viewport.
- left#supported-open-feature-name-leftReferenced in:4.1. The features argument to the open() method (2)
- The left position of the window.
- top#supported-open-feature-name-topReferenced in:4.1. The features argument to the open() method (2)
- The top position of the window.
4.2. The MediaQueryList
Interface
This section integrates with the event loop defined in HTML. [HTML]
A MediaQueryList
object has an associated media query list#media-query-listReferenced in:4. Extensions to the Window Interface4.2. The MediaQueryList Interface (2) and an associated document#mediaquerylist-documentReferenced in:4. Extensions to the Window Interface4.2. The MediaQueryList Interface (2) set on creation.
A MediaQueryList
object has an associated media#mediaquerylist-mediaReferenced in:4.2. The MediaQueryList Interface (2) which is the serialized form of the associated media query list.
A MediaQueryList
object has an associated matches state#mediaquerylist-matches-stateReferenced in:4.2. The MediaQueryList Interface (2) (3)4.2.1. Event summary which is
true if the associated media query list matches the state of the document, and false otherwise.
When asked to evaluate media queries and report changes for a Document
doc, run these steps:
-
For each
MediaQueryList
object target that has doc as its document, in the order they were created, oldest first, run these substeps:- If target’s matches state has changed since the last time these steps were run, dispatch a new event to target using the
MediaQueryList
interface, with itstype
attribute initialized to change, itsisTrusted
attribute initialized to true, itsmedia
attribute initialized to target’s media, and itsmatches
attribute initialized to target’s matches state.
- If target’s matches state has changed since the last time these steps were run, dispatch a new event to target using the
function handleOrientationChange(event) { if(event.matches) // landscape … else … } var mql = matchMedia("(orientation:landscape)"); mql.onchange = handleOrientationChange;
interface MediaQueryList#mediaquerylistReferenced in:4. Extensions to the Window Interface (2)4.2. The MediaQueryList Interface (2) (3) (4) (5) (6) (7) (8)4.2.1. Event summary (2)Changes From 17 December 2013 (2) : EventTarget {
readonly attribute DOMString media;
readonly attribute boolean matches;
void addListener(EventListener? listener);
void removeListener(EventListener? listener);
attribute EventHandler onchange;
};
The media#dom-mediaquerylist-mediaReferenced in:4.2. The MediaQueryList Interface (2) attribute must return the associated media.
The matches#dom-mediaquerylist-matchesReferenced in:4.2. The MediaQueryList Interface attribute must return the associated matches state.
The addListener(listener)#dom-mediaquerylist-addlistenerReferenced in:4.2. The MediaQueryList Interface (2) (3)Changes From 17 December 2013 method must run these steps:
-
If listener is null, terminate these steps.
-
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)#dom-mediaquerylist-removelistenerReferenced in:4.2. The MediaQueryList Interface (2) (3) method must run these steps:
-
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#dom-mediaquerylist-onchangeReferenced in:4.2. The MediaQueryList Interface | change |
[Constructor(DOMString type, optional MediaQueryListEventInit eventInitDict)]
interface MediaQueryListEvent : Event {
readonly attribute DOMString media;
readonly attribute boolean matches;
};
dictionary MediaQueryListEventInit#dictdef-mediaquerylisteventinitReferenced in:4.2. The MediaQueryList Interface : EventInit {
DOMString media = "";
boolean matches = false;
};
The media#dom-mediaquerylistevent-mediaReferenced in:4.2. The MediaQueryList Interface attribute must return the value it was initialized to.
The matches#dom-mediaquerylistevent-matchesReferenced in:4.2. The MediaQueryList Interface (2) attribute must return the value it was initialized to.
4.2.1. Event summary
This section is non-normative.
Event | Interface | Interesting targets | Description |
---|---|---|---|
change#eventdef-mediaquerylist-changeReferenced in:4.2. The MediaQueryList Interface (2) | Event
| MediaQueryList
| Fired at the MediaQueryList when the matches state changes.
|
4.3. The Screen
Interface
As its name suggests, the Screen
interface represents information about the screen of the output device.
interface Screen#screenReferenced in:4. Extensions to the Window Interface (2)4.3. The Screen Interface (2)Changes From 4 August 2011 To 17 December 2013 {
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#dom-screen-availwidthReferenced in:4.3. The Screen Interface attribute must return the available width of the rendering surface of the output device, in CSS pixels.
The availHeight#dom-screen-availheightReferenced in:4.3. The Screen Interface attribute must return the available height of the rendering surface of the output device, in CSS pixels.
The width#dom-screen-widthReferenced in:4.3. The Screen Interface attribute must return the width of the output device, in CSS pixels.
The height#dom-screen-heightReferenced in:4.3. The Screen Interface attribute must return the height of the output device, in CSS pixels.
The colorDepth#dom-screen-colordepthReferenced in:4.3. The Screen Interface (2)Changes From 4 August 2011 To 17 December 2013 attribute must return 24.
The pixelDepth#dom-screen-pixeldepthReferenced in:4.3. The Screen Interface (2)Changes From 4 August 2011 To 17 December 2013 attribute must return 24.
Note: The colorDepth
and pixelDepth
attributes are useless but are
included for compatibility.
5. 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)#dom-document-elementfrompointReferenced in:5. Extensions to the Document Interface (2) (3) 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.
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)#dom-document-elementsfrompointReferenced in:5. Extensions to the Document InterfaceChanges From 4 August 2011 To 17 December 2013 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)#dom-document-caretpositionfrompointReferenced in:5. Extensions to the Document Interface (2) 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 greater 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:
- caret node
- The node corresponding to the text entry widget.
- caret offset
- The amount of 16-bit units to the left of where the text insertion point indicator would have inserted.
- caret range
- 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:- caret node
- The
startContainer
of the caret range. - caret offset
- The
startOffset
of the caret range.
Note: 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.
The scrollingElement#dom-document-scrollingelementReferenced in:5. Extensions to the Document Interface (2)Changes From 17 December 2013 attribute, on getting, must run these steps:
-
If the
Document
is in quirks mode, follow these substeps:-
If the HTML
body
element exists, and it is not potentially scrollable, return the HTMLbody
element and abort these steps. -
Return null and abort these steps.
-
-
If there is a root element, return the root element and abort these steps.
-
Return null.
Note: For non-conforming user agents that always use the quirks mode behavior for scrollTop
and scrollLeft
, the 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.
5.1. The CaretPosition
Interface
A caret position#caret-positionReferenced in:5. Extensions to the Document Interface (2) gives the position of a text insertion point indicator. It always has an associated caret node#caret-nodeReferenced in:5. Extensions to the Document Interface (2)5.1. The CaretPosition Interface (2), caret offset#caret-offsetReferenced in:5. Extensions to the Document Interface (2)5.1. The CaretPosition Interface (2), and caret range#caret-rangeReferenced in:5. Extensions to the Document Interface (2) (3) (4)5.1. The CaretPosition Interface. It is represented by a CaretPosition
object.
interface CaretPosition#caretpositionReferenced in:5. Extensions to the Document Interface5.1. The CaretPosition Interface (2) {
readonly attribute Node offsetNode;
readonly attribute unsigned long offset;
[NewObject] DOMRect? getClientRect();
};
The offsetNode#dom-caretposition-offsetnodeReferenced in:5.1. The CaretPosition Interface attribute must return the caret node.
The offset#dom-caretposition-offsetReferenced in:5.1. The CaretPosition Interface attribute must return the caret offset.
The getClientRect()#dom-caretposition-getclientrectReferenced in:5.1. The CaretPosition Interface 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 static
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.
6. Extensions to the Element
Interface
enum ScrollLogicalPosition#enumdef-scrolllogicalpositionReferenced in:6. Extensions to the Element Interface (2) { "start", "center", "end", "nearest" }; dictionary ScrollIntoViewOptions#dictdef-scrollintoviewoptionsReferenced in:6. Extensions to the Element Interface6.1. Element Scrolling Members : ScrollOptions { ScrollLogicalPosition block#dom-scrollintoviewoptions-blockReferenced in:6. Extensions to the Element Interface (2)6.1. Element Scrolling Members (2) (3) = "center"; ScrollLogicalPosition inline#dom-scrollintoviewoptions-inlineReferenced in:6. Extensions to the Element Interface (2)6.1. Element Scrolling Members (2) (3) = "center"; }; partial interface Element { sequence<DOMRect> getClientRects(); [NewObject] 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()#dom-element-getclientrectsReferenced in:6. Extensions to the Element Interface (2)9. Extensions to the Range Interface 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 sequence and stop this algorithm.
-
If the element has an associated SVG layout box return a sequence 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 sequence containing static
DOMRect
objects in content order, one for each box fragment, describing its border area (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()#dom-element-getboundingclientrectReferenced in:6. Extensions to the Element Interface6.1. Element Scrolling Members 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 static
DOMRect
object whosex
,y
,width
andheight
members are zero. -
Otherwise, return a static
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;
The scrollIntoView(arg)#dom-element-scrollintoviewReferenced in:6. Extensions to the Element Interface (2)Changes From 17 December 2013 (2) method must run these steps:
-
Let options be null.
-
If arg is an object, let options be arg.
-
Convert options to a
ScrollIntoViewOptions
dictionary. [WEBIDL] -
If arg is not specified or is true, let the
block
dictionary member of options have the value "start
", and let theinline
dictionary member of options have the value "nearest
". -
If arg is false, let the
block
dictionary member of options have the value "end
", and let theinline
dictionary member of options have the value "nearest
". -
If the element does not have any associated layout box terminate these steps.
-
Scroll the element into view with the options options.
-
Optionally perform some other action that brings the element to the user’s attention.
The scroll()#dom-element-scrollReferenced in:6. Extensions to the Element Interface (2) (3) (4)Changes From 17 December 2013 method must run these steps:
-
If invoked with one argument, follow these substeps:
-
Let options be the argument.
-
Normalize non-finite values for
left
andtop
dictionary members of options, if present. -
Let x be the value of the
left
dictionary member of options, if present, or the element’s current scroll position on the x axis otherwise. -
Let y be the value of the
top
dictionary member of options, if present, or the element’s current scroll position on the y axis otherwise.
-
-
If invoked with two arguments, follow these substeps:
-
Let options be null converted to a
ScrollToOptions
dictionary. [WEBIDL] -
Let x and y be the arguments, respectively.
-
Normalize non-finite values for x and y.
-
Let the
left
dictionary member of options have the value x. -
Let the
top
dictionary member of options have the value y.
-
-
Let document be the element’s node document.
-
If document is not the active document, terminate these steps.
-
Let window be the value of document’s
defaultView
attribute. -
If window is null, terminate these steps.
-
If the element is the root element and document is in quirks mode, terminate these steps.
-
If the element is the root element invoke
scroll()
on window withscrollX
on window as first argument and y as second argument, and terminate these steps. -
If the element is the HTML
body
element, document is in quirks mode, and the element is not potentially scrollable, invokescroll()
on window with options as the only argument, and terminate these steps. -
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.
-
Scroll the element to x,y, with the scroll behavior being the value of the
behavior
dictionary member of options.
When the scrollTo()#dom-element-scrolltoReferenced in:6. Extensions to the Element Interface (2)Changes From 17 December 2013 method is invoked, the
user agent must act as if the scroll()
method was invoked with the same arguments.
When the scrollBy()#dom-element-scrollbyReferenced in:6. Extensions to the Element Interface (2)Changes From 17 December 2013 method is invoked, the user agent must run these steps:
-
If invoked with one argument, follow these substeps:
-
Let options be the argument.
-
Normalize non-finite values for
left
andtop
dictionary members of options, if present.
-
-
If invoked with two arguments, follow these substeps:
-
Let options be null converted to a
ScrollToOptions
dictionary. [WEBIDL] -
Let x and y be the arguments, respectively.
-
Normalize non-finite values for x and y.
-
Let the
left
dictionary member of options have the value x. -
Let the
top
dictionary member of options have the value y.
-
-
Add the value of
scrollLeft
to theleft
dictionary member. -
Act as if the
scroll()
method was invoked with options as the only argument.
The scrollTop#dom-element-scrolltopReferenced in:5. Extensions to the Document Interface6. Extensions to the Element Interface (2) (3) (4)Changes From 17 December 2013 attribute, on getting, must return the result of running these steps:
-
Let document be the element’s node document.
-
If document is not the active document, return zero and terminate these steps.
-
Let window be the value of document’s
defaultView
attribute. -
If window is null, return zero and terminate these steps.
-
If the element is the root element and document is in quirks mode, return zero and terminate these steps.
-
If the element is the root element return the value of
scrollY
on window. -
If the element is the HTML
body
element, document is in quirks mode, and the element is not potentially scrollable, return the value ofscrollY
on window. -
If the element does not have any associated CSS layout box, return zero and terminate these steps.
-
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:
-
Let y be the given value.
-
Normalize non-finite values for y.
-
Let document be the element’s node document.
-
If document is not the active document, terminate these steps.
-
Let window be the value of document’s
defaultView
attribute. -
If window is null, terminate these steps.
-
If the element is the root element and document is in quirks mode, terminate these steps.
-
If the element is the root element invoke
scroll()
on window withscrollX
on window as first argument and y as second argument, and terminate these steps. -
If the element is the HTML
body
element, document is in quirks mode, and the element is not potentially scrollable, invokescroll()
on window withscrollX
as first argument and y as second argument, and terminate these steps. -
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.
-
Scroll the element to
scrollLeft
,y, with the scroll behavior being"auto"
.
The scrollLeft#dom-element-scrollleftReferenced in:5. Extensions to the Document Interface6. Extensions to the Element Interface (2) (3) (4)Changes From 17 December 2013 (2) attribute, on getting, must return the result of running these steps:
-
Let document be the element’s node document.
-
If document is not the active document, return zero and terminate these steps.
-
Let window be the value of document’s
defaultView
attribute. -
If window is null, return zero and terminate these steps.
-
If the element is the root element and document is in quirks mode, return zero and terminate these steps.
-
If the element is the root element return the value of
scrollX
on window. -
If the element is the HTML
body
element, document is in quirks mode, and the element is not potentially scrollable, return the value ofscrollX
on window. -
If the element does not have any associated CSS layout box, return zero and terminate these steps.
-
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:
-
Let x be the given value.
-
Normalize non-finite values for x.
-
Let document be the element’s node document.
-
If document is not the active document, terminate these steps.
-
Let window be the value of document’s
defaultView
attribute. -
If window is null, terminate these steps.
-
If the element is the root element and document is in quirks mode, terminate these steps.
-
If the element is the root element invoke
scroll()
on window with x as first argument andscrollY
on window as second argument, and terminate these steps. -
If the element is the HTML
body
element, document is in quirks mode, and the element is not potentially scrollable, invokescroll()
on window with x as first argument andscrollY
on window as second argument, and terminate these steps. -
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.
-
Scroll the element to x,
scrollTop
, with the scroll behavior being"auto"
.
The scrollWidth#dom-element-scrollwidthReferenced in:6. Extensions to the Element InterfaceChanges From 17 December 2013 attribute must return the result of running these steps:
-
Let document be the element’s node document.
-
If document is not the active document, 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 document is not in quirks mode return max(viewport scrolling area width, viewport width).
-
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). -
If the element does not have any associated CSS layout box return zero and terminate these steps.
-
Return the width of the element’s scrolling area.
The scrollHeight#dom-element-scrollheightReferenced in:6. Extensions to the Element InterfaceChanges From 17 December 2013 attribute must return the result of running these steps:
-
Let document be the element’s node document.
-
If document is not the active document, 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 document is not in quirks mode return max(viewport scrolling area height, viewport height).
-
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). -
If the element does not have any associated CSS layout box return zero and terminate these steps.
-
Return the height of the element’s scrolling area.
The clientTop#dom-element-clienttopReferenced in:6. Extensions to the Element InterfaceChanges From 17 December 2013 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#dom-element-clientleftReferenced in:6. Extensions to the Element InterfaceChanges From 17 December 2013 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#dom-element-clientwidthReferenced in:6. Extensions to the Element InterfaceChanges From 17 December 2013 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 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). -
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#dom-element-clientheightReferenced in:6. Extensions to the Element InterfaceChanges From 17 December 2013 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 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). -
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.
6.1. Element
Scrolling Members
To scroll an element into view#scroll-an-element-into-viewReferenced in:6. Extensions to the Element Interface element,
with a ScrollIntoViewOptions
dictionary options,
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 theDocument
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 scrolling 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
block
dictionary member of options is "start", align element edge A with scrolling box edge A. -
Otherwise, if the
block
dictionary member of options is "end"; align element edge B with scrolling box edge B. -
Otherwise, if the
block
dictionary member of options is "center"; align the center of element bounding border box with the center of scrolling box in scrolling box’s block flow direction. -
Otherwise, it is "nearest"; follow these steps:
- If element edge A and element edge B are both outside scrolling box edge A and scrolling box edge B
- Do nothing.
- If element edge A is outside scrolling box edge A and element width is less than scrolling box width
- If element edge B is outside scrolling box edge B and element width is greater than scrolling box width
- Align element edge A with scrolling box edge A.
- If element edge A is outside scrolling box edge A and element width is greater than scrolling box width
- If element edge B is outside scrolling box edge B and element width is less than scrolling box width
- Align element edge B with scrolling box edge B.
-
If the
inline
dictionary member of options is "start", align element edge C with scrolling box edge C. -
Otherwise, if the
inline
dictionary member of options is "end"; align element edge D with scrolling box edge D. -
Otherwise, if the
inline
dictionary member of options is "center", align the center of element bounding border box with the center of scrolling box in scrolling box’s inline base direction. -
Otherwise, it is "nearest"; follow these steps:
- If element edge C and element edge D are both outside scrolling box edge C and scrolling box edge D
- Do nothing.
- If element edge C is outside scrolling box edge C and element width is less than scrolling box width
- If element edge D is outside scrolling box edge D and element width is greater than scrolling box width
- Align element edge C with scrolling box edge C.
- If element edge C is outside scrolling box edge C and element width is greater than scrolling box width
- If element edge D is outside scrolling box edge D and element width is less than scrolling box width
- 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.
-
- If scrolling box is associated with an element
- Let associated element be the element.
- If scrolling box is associated with a viewport
- Let document be the viewport’s associated
Document
. Let associated element be document’s root element, if there is one, or null otherwise.
-
Let behavior be the
behavior
dictionary member of options. -
Perform a scroll of scrolling box to position, associated element as the associated element and behavior as the scroll behavior.
To scroll an element#scroll-an-elementReferenced in:6. Extensions to the Element Interface (2) (3) 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.
-
- If box has rightward overflow direction
- Let x be max(0, min(x, element scrolling area width - element padding edge width)).
- If box has leftward overflow direction
- Let x be min(0, max(x, element padding edge width - element scrolling area width)).
-
- If box has downward overflow direction
- Let y be max(0, min(y, element scrolling area height - element padding edge height)).
- If box has upward overflow direction
- 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.
-
Perform a scroll of box to position, element as the associated element and behavior as the scroll behavior.
7. Extensions to the HTMLElement
Interface
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#dom-htmlelement-offsetparentReferenced in:7. Extensions to the HTMLElement Interface (2) (3) (4) (5) attribute must return the result of running these steps:
-
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 fixed.
-
-
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:
-
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
, ortable
.
-
Return null.
The offsetTop#dom-htmlelement-offsettopReferenced in:7. Extensions to the HTMLElement Interface 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.Note: An inline element that consists of multiple line boxes will only have its first CSS layout box considered.
The offsetLeft#dom-htmlelement-offsetleftReferenced in:7. Extensions to the HTMLElement Interface 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#dom-htmlelement-offsetwidthReferenced in:7. Extensions to the HTMLElement Interface 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#dom-htmlelement-offsetheightReferenced in:7. Extensions to the HTMLElement Interface 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.
8. Extensions to the HTMLImageElement
Interface
partial interface HTMLImageElement { readonly attribute long x; readonly attribute long y; };
The x#dom-htmlimageelement-xReferenced in:8. Extensions to the HTMLImageElement Interface 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#dom-htmlimageelement-yReferenced in:8. Extensions to the HTMLImageElement Interface 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.
9. Extensions to the Range
Interface
The objects the methods described below return must be static.
partial interface Range { sequence<DOMRect> getClientRects(); [NewObject] DOMRect getBoundingClientRect(); };
The getClientRects()#dom-range-getclientrectsReferenced in:5.1. The CaretPosition Interface9. Extensions to the Range Interface (2) method, when invoked, must return an empty
sequence if the range is not in the document and
otherwise a sequence object containing
static 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 areas returned by invoking
getClientRects()
on the element. -
For each
Text
node selected or partially selected by the range (including when the boundary-points are identical), include aDOMRect
object (for the part that is selected, not the whole line box). The bounds of theseDOMRect
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()#dom-range-getboundingclientrectReferenced in:9. Extensions to the Range Interface 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 static
DOMRect
object whosex
,y
,width
andheight
members are zero. -
Otherwise, return a static
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.
10. Extensions to the MouseEvent
Interface
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#dom-mouseevent-screenxReferenced in:10. Extensions to the MouseEvent Interface attribute must return the x-coordinate of the position where the event occurred relative to the origin of the screen.
The screenY#dom-mouseevent-screenyReferenced in:10. Extensions to the MouseEvent Interface attribute must return the y-coordinate of the position where the event occurred relative to the origin of the screen.
The pageX#dom-mouseevent-pagexReferenced in:10. Extensions to the MouseEvent Interface (2) 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 associatedWindow
object, if there is one, or zero otherwise. -
Return the sum of offset and the value of the event’s
clientX
attribute.
The pageY#dom-mouseevent-pageyReferenced in:10. Extensions to the MouseEvent Interface (2) 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
scrollY
attribute of the event’s associatedWindow
object, if there is one, or zero otherwise. -
Return the sum of offset and the value of the event’s
clientY
attribute.
The clientX#dom-mouseevent-clientxReferenced in:10. Extensions to the MouseEvent Interface (2) (3) attribute must return the x-coordinate of the position where the event occurred relative to the origin of the viewport.
The clientY#dom-mouseevent-clientyReferenced in:10. Extensions to the MouseEvent Interface (2) (3) attribute must return the y-coordinate of the position where the event occurred relative to the origin of the viewport.
The x#dom-mouseevent-xReferenced in:10. Extensions to the MouseEvent Interface attribute must return the value of clientX
.
The y#dom-mouseevent-yReferenced in:10. Extensions to the MouseEvent Interface attribute must return the value of clientY
.
The offsetX#dom-mouseevent-offsetxReferenced in:10. Extensions to the MouseEvent Interface 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#dom-mouseevent-offsetyReferenced in:10. Extensions to the MouseEvent Interface 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.
11. Geometry
11.1. The GeometryUtils
Interface
enum CSSBoxType#enumdef-cssboxtypeReferenced in:11.1. The GeometryUtils Interface (2) (3) { "margin", "border", "padding", "content" }; dictionary BoxQuadOptions#dictdef-boxquadoptionsReferenced in:11.1. The GeometryUtils Interface { CSSBoxType box = "border"; GeometryNode relativeTo; // XXX default document (i.e. viewport) }; dictionary ConvertCoordinateOptions#dictdef-convertcoordinateoptionsReferenced in:11.1. The GeometryUtils Interface (2) (3) { CSSBoxType fromBox = "border"; CSSBoxType toBox = "border"; }; [NoInterfaceObject] interface GeometryUtils#geometryutilsReferenced in:11.1. The GeometryUtils Interface (2) (3) (4) (5) { 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; CSSPseudoElement implements GeometryUtils; Document implements GeometryUtils; typedef (Text or Element or CSSPseudoElement or Document) GeometryNode#typedefdef-geometrynodeReferenced in:11.1. The GeometryUtils Interface (2) (3) (4);
The getBoxQuads(options)#dom-geometryutils-getboxquadsReferenced in:11.1. The GeometryUtils Interface method must run the following steps:
-
DOM order
p1 = top left even in RTL
scale to 0 means divide by zero, return 0x0
cross-frames not allowed, throw WrongDocumentError?
points are flattened (3d transform), z=0. like getClientRect
test block in inline
pseudo-elements before/after are children of the element
viewport boxes are all the same
The convertQuadFromNode(quad, from, options)#dom-geometryutils-convertquadfromnodeReferenced in:11.1. The GeometryUtils Interface method must run the following steps:
The convertRectFromNode(rect, from, options)#dom-geometryutils-convertrectfromnodeReferenced in:11.1. The GeometryUtils Interface method must run the following steps:
The convertPointFromNode(point, from, options)#dom-geometryutils-convertpointfromnodeReferenced in:11.1. The GeometryUtils Interface method must run the following steps:
12. Events
12.1. Resizing viewports
This section integrates with the event loop defined in HTML. [HTML]
When asked to run the resize steps for a Document
doc, run these steps:
-
If doc’s viewport has had its width or height changed (e.g. as a result of the user resizing the browser window, or changing the page zoom scale factor, or an
iframe
element’s dimensions are changed) since the last time these steps were run, fire an event named resize at theWindow
object associated with doc.
12.2. Scrolling
This section integrates with the event loop defined in HTML. [HTML]
Each Document
has an associated list of pending scroll event targets#pending-scroll-event-targetsReferenced in:12.2. Scrolling (2) (3) (4) (5) (6), initially empty.
Whenever a viewport gets scrolled (whether in response to user interaction or by an API), the user agent must run these steps:
-
Let doc be the viewport’s associated
Document
. -
If doc is already in doc’s pending scroll event targets, abort these steps.
-
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:
-
Let doc be the element’s node document.
-
If the element is already in doc’s pending scroll event targets, abort these steps.
-
Append the element to doc’s pending scroll event targets.
When asked to run the scroll steps for a Document
doc, run these steps:
-
For each item target in doc’s pending scroll event targets, in the order they were added to the list, run these substeps:
-
If target is a
Document
, fire an event named scroll that bubbles at target. -
Otherwise, fire an event named scroll at target.
-
-
Empty doc’s pending scroll event targets.
12.3. Event summary
This section is non-normative.
Event | Interface | Interesting targets | Description |
---|---|---|---|
resize#eventdef-window-resizeReferenced in:12.1. Resizing viewportsChanges From 17 December 2013 | Event
| Window
| Fired at the Window when the viewport is resized.
|
scroll#eventdef-document-scrollReferenced in:12.2. Scrolling (2)Changes From 17 December 2013 | Event
| Document , elements
| Fired at the Document or element when the viewport or element is scrolled, respectively.
|
13. CSS properties
The features in this section should be moved to some other specification.
13.1. Smooth Scrolling: The scroll-behavior Property
Name: | scroll-behavior#propdef-scroll-behaviorReferenced in:3.1. Scrolling (2)13.1. Smooth Scrolling: The scroll-behavior Property (2) (3)Changes From 17 December 2013Changes From 4 August 2011 To 17 December 2013 |
---|---|
Value: | auto | smooth |
Initial: | auto |
Applies to: | scrolling boxes |
Inherited: | no |
Percentages: | n/a |
Media: | visual |
Computed value: | specified value |
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. 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.
- auto#valdef-scroll-behavior-autoReferenced in:Changes From 17 December 2013
- The scrolling box is scrolled in an instant fashion.
- smooth#valdef-scroll-behavior-smoothReferenced in:3.1. Scrolling
- 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 conventions, if any.
User agents may ignore this property.
Change History
This section documents some of the changes between publications of this specification. This section is not exhaustive. Bug fixes and editorial changes are generally not listed.
Changes From 17 December 2013
-
The
scrollIntoView()
method onElement
was changed and extended. -
The
scrollTop
andscrollLeft
IDL attributes onElement
changed to no longer take an object; thescroll()
,scrollTo()
andscrollBy()
methods were added instead. -
The
scrollWidth
,scrollHeight
,clientTop
,clientLeft
,clientWidth
andclientHeight
IDL attributes onElement
were changed back to return integers. -
The
DOMRectList
interface was removed. -
The
scrollingElement
IDL attribute onDocument
was added. -
Some readonly attributes on
Window
were annotated with[Replaceable]
IDL extended attribute. -
MediaQueryList
, scroll event and resize event are integrated with the event loop in HTML so they are synchronized with animation frames. -
The
instant
value of scroll-behavior was renamed to auto. -
The origin of
scrollLeft
onElement
was changed (for RTL). -
The
scrollIntoView()
method onElement
andscroll()
,scrollTo()
andscrollBy()
methods onWindow
take the relevant dictionary as the first argument. -
The
MediaQueryList
interface was changed to use regular event API and defineaddListener()
in terms of that.
Changes From 4 August 2011 To 17 December 2013
-
The specification now handles right-to-left and vertical writing modes.
-
The specification is now aware of page zoom and pinch zoom.
-
The scroll-behavior CSS property is introduced and scrolling APIs are extended with a mechanism to control smooth scrolling.
-
The
moveTo()
,moveBy()
,resizeTo()
andresizeBy()
methods are now defined. -
innerWidth
et al now use the WebIDL typedouble
instead oflong
. -
devicePixelRatio
is now defined. -
The
features
argument to window.open() is now defined. -
The
colorDepth
andpixelDepth
attributes ofScreen
now always return 24. -
The
elementsFromPoint()
method ofElement
is introduced. -
The specification is now aware of transforms.
-
Some geometry utility APIs are introduced but are not yet specified.
-
ClientRect
has been renamed toDOMRect
and has moved to the Geometry specification. [GEOMETRY-1] -
The specification now defines when the
resize
andscroll
events fire.
Acknowledgments
The editors would like to thank Alan Stearns, Alexey Feldgendler, Antonio Gomes, Björn Höhrmann, Boris Zbarsky, Chris Rebert, Dan Bates, David Vest, Elliott Sprehn, Garrett Smith, Henrik Andersson, 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, Rick Byers, Robert O’Callahan, Sam Weinig, Scott Johnson, Sebastian Zartner, Stewart Brodie, Sylvain Galineau, Tab Atkins, Tarquin Wilton-Jones, Thomas Moore, Thomas Shinnick, 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.