Copyright © 2009 W3C® (MIT, ERCIM, Keio), 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.
The CSSOM View Module also supercedes DOM Level 2 Views and therefore
defines the AbstractView and
DocumentView interfaces and
extensions for them.
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/.
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.
The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “cssom-view” in the subject, preferably like this: “[cssom-view] …summary of comment…”
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.
AbstractView Interface
ScreenView Interface
DocumentView Interface
Element Interface
HTMLElement Interface
Range Interface
MouseEvent Interface
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 identical way without differences between no quirks, limited quirks and no quirks mode, as defined by HTML 5. [HTML5]
As well as serving as a specification for that "de facto" standard this specification also obsoletes DOM Level 2 Views by taking the concepts defined in that specification, making them more concrete, and integrating them with the various "de facto" concepts.
Finally, the specification defines a couple of new features that the CSS WG considers to be useful for authors.
Everything in this specification is normative except for diagrams, examples, notes and sections marked non-normative.
The key word must in this document is to be interpreted as described in RFC 2119. [RFC2119]
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]
Document and Element are defined by DOM Level 3 Core.
[DOM3Core]
Range is defined in DOM Level 2
Traversal and Range. [DOM2TR]
MouseEvent is defined in DOM Level
2 Events. [DOM2Events]
HTML element, HTMLElement, view and
default view are defined by HTML 5.
[HTML5]
The HTML body element
is the first body HTML element
child of the root HTML element
html.
The terms content edge, padding edge, border edge, and canvas are defined by CSS 2.1. [CSS21]
The terms viewport, initial containing block are defined by
CSS 2.1 unless there's an ancestor foreignObject element in
the http://www.w3.org/2000/svg namespace in which case that
element acts as viewport and initial containing block. [CSS21] [SVG]
The term content refers to the dimensions of the element's content area, including overflown content. [CSS21]
The term document content refers to the area on the canvas that is rendered upon, excluding content on negative axis.
All coordinates and dimensions for the APIs defined in this specification are in CSS pixels. [CSS21]
This does not apply to e.g. matchMedium() as the units are
explicitly given there and defined by the Media Queries specification.
[MQ]
This specification defines the DOM
feature "Views" for versions "2.0" and
"3.0". User agents supporting this specification must support that feature and versions. [DOM3Core]
Authors are encouraged to stay away from DOM features as user agents claiming to support the DOM feature might not support the feature you need and user agents supporting parts of the specification might not claim support for the DOM feature.
AbstractView InterfaceThe AbstractView interface is a
base interface that all views must derive from.
[NoInterfaceObject] interface AbstractView {
readonly attribute DocumentView document;
readonly attribute Media media;
};
The document attribute, on
getting, must return the object implementing the
DocumentView interface that is
associated with the view.
The media attribute, on
getting, must return an object implementing the Media interface. It must always
return the same object.
Media Interfaceinterface Media {
readonly attribute DOMString type;
boolean matchMedium(DOMString mediaquery);
};
The type attribute, on
getting, must return the string that represents the
media type of the current view used for rendering the
Document. The media types are defined
by CSS 2.1 (screen, print, et cetera).
[CSS21]
The following snippet determines whether the page is rendered using the projection media type:
var isProjection = media.type == "projection"The matchMedium(mediaquery)
method, when invoked, must return the result of the
following algorithm:
If mediaquery can be parsed according to the rules
given in the Media Queries specification and matches the state of the
current view return true and terminate
this algorithm. [MQ]
Otherwise, return false.
The following snippet determines whether the device is a color device:
var isColorDevice = media.matchMedium("(color)")ScreenView InterfaceAn object implementing the ScreenView interface represents a view for visual media. If the default view is visual the defaultView attribute on the
Document object must return an object implementing this interface.
[NoInterfaceObject] interface ScreenView : AbstractView {
// viewport
readonly attribute long innerWidth;
readonly attribute long innerHeight;
readonly attribute long pageXOffset;
readonly attribute long pageYOffset;
void scroll(long x, long y);
void scrollTo(long x, long y);
void scrollBy(long x, long y);
// client
readonly attribute long screenX;
readonly attribute long screenY;
readonly attribute long outerWidth;
readonly attribute long outerHeight;
// output device
readonly attribute Screen screen;
};
The innerWidth
attribute, on getting, must return the viewport width including the size of a rendered
scroll bar (if any).
The following snippet shows how to obtain the width of the viewport:
var viewportWidth = innerWidthThe innerHeight
attribute, on getting, must return the viewport height including the size of a rendered
scroll bar (if any).
The pageXOffset
attribute, on getting, must return the x-coordinate,
relative to the initial containing
block origin, of the left of the viewport.
The pageYOffset
attribute, on getting, must return the y-coordinate,
relative to the initial containing
block origin, of the top of the viewport.
When the scroll(x,y) method is invoked, the user agent must run the following algorithm:
If either x or y is infinite or NaN stop this algorithm.
Let x be min(x, content width - content edge width).
If x is negative let it be zero.
Let x be max(x, content edge width - content width).
If x is non-negative let it be zero.
Let y be min(y, document content height - viewport height excluding the size of a rendered scroll bar (if any)).
If y is negative let it be zero.
Align the x-coordinate x of the document content with the left of the viewport and align the y-coordinate y of the document content with the top of the viewport.
When the scrollTo(x,y) method is invoked, the user agent must act as if the scroll() method was invoked with
the same arguments.
When the scrollBy(x,y) method is invoked, the user agent must act as if the scroll() method was invoked with
x plus pageXOffset as first
argument and y plus pageYOffset as second
argument.
The screenX attribute,
on getting, must return the x-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 screenY attribute,
on getting, must return the y-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 outerWidth
attribute, on getting, must return the width of the
client window. If there is no client window this attribute must return zero.
The outerHeight
attribute, on getting, must return the height of the
client window. If there is no client window this attribute must return zero.
The screen attribute, on
getting, must return an object implementing the Screen interface. It must
always return the same object.
Screen InterfaceAs its name suggests, the Screen
interface represents information about the screen of the output device.
interface Screen {
readonly attribute unsigned long availWidth;
readonly attribute unsigned long availHeight;
readonly attribute unsigned long width;
readonly attribute unsigned long height;
readonly attribute unsigned long colorDepth;
readonly attribute unsigned long pixelDepth;
};
The availWidth
attribute, on getting, must return the available width
of the rendering surface of the output device.
The availHeight
attribute, on getting, must return the available height
of the rendering surface of the output device.
The width attribute, on
getting, must return the width of the output device.
The height attribute, on
getting, must return the height of the output device.
The colorDepth and pixelDepth attributes must both return the number of bits allocated to colors in
the output device. If the output device does not support colors these
attributes must return zero.
Bits allocated to handling transparancy are not taken into account.
DocumentView Interface[NoInterfaceObject] interface DocumentView {
readonly attribute AbstractView defaultView;
Element elementFromPoint(float x, float y);
Range caretRangeFromPoint(float x, float y);
};
Document implements DocumentView;
The defaultView
attribute, on getting, must return an object
implementing the AbstractView
interface that is the default view for this
document. If there is no default view available this attribute must return null.
The elementFromPoint(x, y) method, when invoked, must return the element at coordinates
x,y in the viewport. The
element to be returned is determined through hit testing. 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 greather than the viewport height excluding the size of a rendered
scroll bar (if any), the method must return
null. If there is no element at the given position the method
must return the root element, if any, or
null otherwise.
The caretRangeFromPoint(x,
y) method, when invoked, must return an empty text range for the position where a
text insertion point indicator would have been inserted if editing was
enabled and hit testing was performed at the coordinates
x,y in the viewport. 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), or no insertion point indicator would have been
inserted, the method must return null.
[DOM2TR]
The specifics of hit testing are out of scope of this
specification and therefore the exact details of elementFromPoint()
and caretRangeFromPoint()
are too. Hit testing might be defined in a future revision of CSS or
HTML 5.
Element Interface[Supplemental] interface Element {
ClientRectList getClientRects();
ClientRect getBoundingClientRect();
attribute long scrollTop; // scroll on setting
attribute long scrollLeft; // scroll on setting
readonly attribute long scrollWidth;
readonly attribute long scrollHeight;
readonly attribute long clientTop;
readonly attribute long clientLeft;
readonly attribute long clientWidth;
readonly attribute long clientHeight;
};
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.
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 CSS
layout box and is not in the http://www.w3.org/2000/svg
namespace return an empty ClientRectList object and stop this
algorithm.
If the element does not have an associated CSS layout box and is in
the http://www.w3.org/2000/svg namespace return a ClientRectList object containing a
single ClientRect object that
describes the bounding box of the element as defined by SVG
specification. [SVG]
Return a ClientRectList
object containing a list of ClientRect objects in content order
describing the border boxes (including those with a height or width of
zero) with the following constraints:
If the element on which the method was invoked has a computed value
for display property of table or
inline-table include both the table box and the caption
box, if any, but not the anonymous container box. [CSS21]
Replace each anonymous block box with its child box(es) and repeat this until no anonymous block boxes are left in the final list. [CSS21]
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 ClientRect object whose top,
right, bottom and left
members are zero.
Otherwise, return a ClientRect
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;scrollTop, scrollLeft, scrollWidth, and scrollHeight
attributesThe scrollTop
attribute, when called on element A, must
return the value that is the result of running the following algorithm:
If A does not have an associated CSS layout box return zero and stop this algorithm.
Return the y-coordinate of the content at the alignment point with the top of the content edge of A.
When setting the scrollTop attribute to y on element A user agents must run the following algorithm:
If A does not have an associated CSS layout box or vertical overflow stop this algorithm.
If y is infinite or NaN stop this algorithm.
Let y be min(y, content height - content edge height).
If y is negative let it be zero.
Align content y-coordinate y with the top of the content edge of A.
The scrollLeft
attribute, when called on element A, must
return the value that is the result of running the following algorithm:
If A does not have an associated CSS layout box return zero and stop this algorithm.
Return the x-coordinate of the content at the alignment point with the left of the content edge of A.
When setting the scrollLeft attribute to x on element A user agents must run the following algorithm:
If A does not have an associated CSS layout box or horizontal overflow stop this algorithm.
If x is infinite or NaN stop this algorithm.
Let x be min(x, content width - content edge width).
If x is negative let it be zero.
Let x be max(x, content edge width - content width).
If x is non-negative let it be zero.
Align content x-coordinate x with the left of the content edge of A.
The scrollWidth
attribute, when called on element A, must
return value that is the result of the following algorithm:
If A does not have an associated CSS layout box return zero and stop this algorithm.
Return the computed value of the padding-left property of
A, plus the computed value of the padding-right
property of A, plus the content width
of A.
The scrollHeight
attribute, when called on element A, must
return value that is the result of the following algorithm:
If A does not have an associated CSS layout box return zero and stop this algorithm.
Return the computed value of the padding-top property of
A, plus the computed value of the padding-bottom
property of A, plus the content height
of A.
clientTop, clientLeft, clientWidth, and clientHeight
attributesThe clientTop, clientLeft, clientWidth, and clientHeight attributes, on
getting, must return zero if the element does not have
an associated CSS layout box or if the layout box is inline. Otherwise,
these attributes must behave as defined in the remainder
of this section.
On getting, the clientTop attribute returns the
computed value of the border-top-width property plus the
width of any scrollbar rendered between the top padding edge and the top border edge.
On getting, the clientLeft attribute returns 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.
On getting, the clientWidth attribute returns
the viewport width excluding the size of a
rendered scroll bar (if any) if the element is the root element and the
width of the padding edge (excluding the width
of any rendered scrollbar between the padding
edge and the border edge) otherwise.
On getting, the clientHeight attribute returns
the viewport height excluding the size of a
rendered scroll bar (if any) if the element is the root element and the
height of the padding edge (excluding the
width of any rendered scrollbar between the padding edge and the border edge) otherwise.
HTMLElement Interface[Supplemental] interface HTMLElement {
readonly attribute Element offsetParent;
readonly attribute long offsetTop;
readonly attribute long offsetLeft;
readonly attribute long offsetWidth;
readonly attribute long offsetHeight;
};
offsetParent, offsetTop, offsetLeft, offsetWidth, and offsetHeight attributesThe offsetParent
attribute, when called on element A, must
return the element determined by the following algorithm:
If any of the following holds true return null and stop
this algorithm:
body element.
position property for element
A is fixed.
If A is an area HTML
element which has a map HTML
element somewhere in the ancestor chain return the nearest ancestor
map HTML element and stop this
algorithm.
Return the nearest ancestor element of A for which at least one of the following is true and stop this algorithm if such an ancestor is found:
position property is not
static.
body
element.
position property of
A is static and the ancestor is one of the
following HTML
elements: td, th, or table.
Return null.
The offsetTop
attribute, when called on element A, must
return the value that is the result of the following algorithm:
If A is the HTML
body element or does not have an associated CSS layout
box return zero and stop this algorithm.
If the offsetParent of
A is null or the HTML body element
return the y-coordinate of the top border
edge of A and stop this algorithm.
Return the result of subtracting the y-coordinate of the top padding edge of the offsetParent of
A from the y-coordinate of the top border edge of A, relative to the initial containing block origin.
In case of an inline element that consists of multiple line boxes only the first in content order is to be considered for the purposes of the above algorithm.
The offsetLeft
attribute, when called on element A, must
return the value that is the result of the following algorithm:
If element A is the HTML
body element or does not have an associated CSS layout
box return zero and stop this algorithm.
If the offsetParent of
A is null or the HTML body element
return the x-coordinate of the left border
edge of A and stop this algorithm.
Return the result of subtracting the x-coordinate of the left padding edge of the offsetParent of
A from the x-coordinate of the left border edge of A, relative to the initial containing block origin.
In case of an inline element that consists of multiple line boxes only the first in content order is to be considered for the purposes of the above algorithm.
The offsetWidth
attribute, when called on element A, must
return value that is the result of the following algorithm:
If A does not have an associated CSS layout box return zero and stop this algorithm.
Return the border edge width of A.
The offsetHeight
attribute, when called on element A, must
return value that is the result of the following algorithm:
If A does not have an associated CSS layout box return zero and stop this algorithm.
Return the border edge height of A.
Range Interface[Supplemental] interface Range {
ClientRectList getClientRects();
ClientRect getBoundingClientRect();
};
The objects the methods described below return must be static.
The getClientRects() method,
when invoked, must return an empty ClientRectList object if the range is
not in the document and otherwise a ClientRectList object containing a list
of ClientRect 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
ClientRect object (for the part
that is selected, not the whole line box). The bounds of these ClientRect 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 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 ClientRect object whose top,
right, bottom and left
members are zero.
Otherwise, return a ClientRect
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 Interface[Supplemental] interface MouseEvent {
readonly attribute long screenX;
readonly attribute long screenY;
readonly attribute long pageX;
readonly attribute long pageY;
readonly attribute long clientX;
readonly attribute long clientY;
readonly attribute long x;
readonly attribute long y;
readonly attribute long offsetX;
readonly attribute long offsetY;
};
The object IDL fragment redefines some members. Can we resolve this somehow?
The screenX attribute, on
getting, must return the x-coordinate of the position
where the event occurred relative to the origin of the screen.
The screenY attribute, on
getting, must return the y-coordinate of the position
where the event occurred relative to the origin of the screen.
The pageX attribute, on
getting, must return the horizontal coordinate of the
position where the event occurred relative to the origin of the initial containing block.
The pageY attribute, on
getting, must return the y-coordinate of the position
where the event occurred relative to the origin of the initial containing block.
The clientX attribute,
on getting, must return the x-coordinate of the position
where the event occurred relative to the origin of the viewport.
The clientY attribute,
on getting, must return the y-coordinate of the position
where the event occurred relative to the origin of the viewport.
The x
attribute, on getting, must return the value of clientX.
The y
attribute, on getting, must return the value of clientY.
The offsetX attribute,
on getting, must return the x-coordinate of the position
where the event occurred relative to the origin of the padding edge of the target node.
The offsetY attribute,
on getting, must return the y-coordinate of the position
where the event occurred relative to the origin of the padding edge of the target node.
ClientRectList InterfaceThe ClientRectList object
consists of an ordered list of ClientRect objects.
interface ClientRectList {
readonly attribute unsigned long length;
getter ClientRect item(unsigned long index);
};
The length attribute must return the total number of ClientRect objects associated with the
object.
The item(index) method, when invoked, must raise an INDEX_SIZE_ERR exception when
index is negative or greater than the number of
ClientRect objects associated with
the object. Otherwise, the ClientRect object at index must be returned.
ClientRect InterfaceObjects implementing the ClientRect interface represent a rectangular
box. The type of box is specified by the method that returns a ClientRect object.
interface ClientRect {
readonly attribute float top;
readonly attribute float right;
readonly attribute float bottom;
readonly attribute float left;
readonly attribute float width;
readonly attribute float height;
};
The top attribute, on getting, must return the y-coordinate, relative to the viewport origin, of the top of the rectangle box.
The right attribute, on getting,
must return the x-coordinate, relative to the viewport origin, of the right of the rectangle box.
The bottom attribute, on
getting, must return the y-coordinate, relative to the
viewport origin, of the bottom of the rectangle
box.
The left attribute, on getting,
must return the x-coordinate, relative to the viewport origin, of the left of the rectangle box.
The width attribute, on getting,
must return the width of the rectangle box.
This is identical to right minus left.
The height attribute, on
getting, must return the height of the rectangle box.
This is identical to bottom minus top.
All references are normative.
The editor would like to thank Alexey Feldgendler, Björn Höhrmann, David Vest, Garrett Smith, Hallvord R. M. Steen, Mike Wilson, Morten Stenshorne, Peter-Paul Koch, Rachel Kmetz, Robert O'Callahan, Simon Pieters, Sylvain Galineau, Tarquin Wilton-Jones, and Thomas Moore 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.