The APIs introduced by this specification provide authors with a way to inspect and manipulate the view information of a document. This includes getting the position of element layout boxes, obtaining the width of the viewport through script, and also scrolling an element.
This is the first public Working Draft of the CSSOM View Module.
Everything in this specification is normative except for diagrams, examples, notes and sections marked non-normative.
The key word must, must not, should and may in this document are to be interpreted as described in RFC 2119. [RFC2119]
A conforming user agent implements all the requirements made by this specification.
This specification depends on several definitions and features defined in the HTML 5 specification. [HTML5]
This specification also depends on several features defined in the DOM Level 2 Events and DOM Level 3 Core specifications. [DOM2Events] [DOM3Core]
The term HTML element is defined by the HTML 5 specification. [HTML5]
The HTML body element is the first
body HTML element child of the root HTML
element html.
WindowView InterfaceObjects implementing the Window interface
must also implement the WindowView
interface. [HTML5]
interface WindowView {
readonly attribute float innerWidth;
readonly attribute float innerHeight;
readonly attribute float outerWidth;
readonly attribute float outerHeight;
readonly attribute float pageXOffset;
readonly attribute float pageYOffset;
readonly attribute float screenX;
readonly attribute float screenY;
readonly attribute Media media;
readonly attribute Screen screen;
};
The innerWidth
attribute, on getting, must return the viewport width
as number of CSS pixels.
This is including, if rendered, the vertical
scrollbar.
The innerHeight
attribute, on getting, must return the viewport height
as number of CSS pixels. This is including, if
rendered, the horizontal scrollbar.
The outerWidth
attribute, on getting, must return the width of the
browser window as number of CSS pixels. If there is no browser window this
attribute must return zero.
The outerHeight
attribute, on getting, must return the height of the
browser window as number of CSS pixels. If there is no browser windows
this attribute must return zero.
The pageXOffset
attribute, on getting, must return the number of CSS
pixels the user has scrolled towards the right within the viewport.
The pageYOffset
attribute, on getting, must return the number of CSS
pixels the user has scrolled towards the bottom within the viewport.
The screenX
attribute, on getting, must return the amount of CSS
pixels between the left of the browser window and the left of the screen
of the output device. If there is no browser window this attribute
must return zero.
The screenY
attribute, on getting, must return the amount of CSS
pixels between the top of the browser window and the top of the screen of
the output device. If there is no browser window this attribute
must return zero.
The
media
attribute, on getting, must return an object
implementing the Media interface.
The
screen
attribute, on getting, must return an object
implementing the Screen interface.
Screen InterfaceAs its name suggests, the Screen interface represents
information about the screen of the output device.
interface Screen {
readonly attribute float availWidth;
readonly attribute float availHeight;
readonly attribute float width;
readonly attribute float height;
readonly attribute float colorDepth;
readonly attribute float pixelDepth;
};
The availWidth
attribute, on getting, must return the available width
of the rendering surface of the output device as number of CSS pixels.
The availHeight
attribute, on getting, must return the available
height of the rendering surface of the output device as number of CSS
pixels.
The width attribute, on
getting, must return the width of the output device as
number of CSS pixels.
The height attribute, on
getting, must return the height of the output device
as number of CSS pixels.
The colorDepth and
pixelDepth attributes
must both return the lowest number of bits from the
color components of the output device. If the device is not a color device
these attributes must return zero.
Media Interfaceinterface Media {
readonly attribute DOMString type;
boolean query(in DOMString mediaquery);
};
The type attribute, on getting,
must return the string that represents the canvas'
current rendering mode in canonical form. That is, identical to how it is
defined by the CSS specification. [CSS21]
The
query(mediaquery)
method, when invoked, must return the result of the
following algorithm:
false
and terminate this algorithm.true and terminate this algorithm.false.DocumentView InterfaceThis conflicts with an interface in DOM Level 2 Views. Maybe this specification combined with HTML 5 (for AbstractView) can obsolete that one as it is completely useless in practice.
Objects implementing the Document interface
must also implement the DocumentView
interface. [DOM3Core]
interface DocumentView {
Element elementFromPoint(in unsigned long x, in unsigned long y);
};
The
elementFromPoint(x,
y) method, when invoked,
must return the element at x,y
in the viewport. The element to be returned is determined through hit
testing. If either argument is negative or if there is no element at
the given position the method, when invoked, must
return null.
Hit testing is currently defined exactly nowhere.
ElementView InterfaceObjects implementing the Element interface
must also implement the ElementView
interface. [DOM3Core]
interface ElementView {
TextRectangleList getClientRects();
TextRectangle getBoundingClientRect();
readonly attribute Element offsetParent;
readonly attribute float offsetTop;
readonly attribute float offsetLeft;
readonly attribute float offsetWidth;
readonly attribute float offsetHeight;
attribute float scrollTop; // scroll on setting
attribute float scrollLeft; // scroll on setting
readonly attribute float scrollWidth;
readonly attribute float scrollHeight;
readonly attribute float clientTop;
readonly attribute float clientLeft;
readonly attribute float clientWidth;
readonly attribute float 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
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 return an empty (static) TextRectangleList
object and stop this algorithm.
Return a (static) TextRectangleList object containing
a list of (static) TextRectangle objects in content order
describing the border boxes, even if they are empty, for the element on
which it was invoked.
The
getBoundingClientRect()
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 return a (static) TextRectangle object whose
top,
right,
bottom and
left members are zero.
Let list be the result of invoking
getClientRects() on the same element this method was invoked
on.
If list is empty return a (static)
TextRectangle object whose
top,
right,
bottom and
left members are zero.
Otherwise, return a union of the border boxes in list,
excluding border boxes that are empty, as a single
TextRectangle object. If all border boxes are empty let the
top attribute of the new
TextRectangle object be the value of the
top attribute of the first border
box in the list returned. Do likewise for
left and then let
bottom be equal to
top and
right to
left.
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 element A is the HTML body
element, has a computed value of the display property
of none, or does not have an associated CSS layout box
return zero and stop this algorithm.
If the offsetParent of element A is
null or the HTML body element
return the distance, as number of CSS pixels, between the top border edge
of element A and the canvas origin and stop this
algorithm.
Return the distance as number of CSS pixels between the top border
edge of the offsetParent of element A
and the top border edge of element A.
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, has a computed value of the display propery
that is none, or does not have an associated CSS layout box
return zero and stop this algorithm.
If the offsetParent of element A is
null or the HTML body element
return the distance, as number of CSS pixels, between the left border
edge of element A and the left of the canvas origin and stop
this algorithm.
Return the distance, as number of CSS pixels, between the left
border edge of the offsetParent of element
A and the left border edge of element
A.
The offsetWidth
attribute, when called on element A,
must return value that is the result of the following
algorithm:
If element A does not have an associated CSS layout box return zero and stop this algorithm.
Return the number of CSS pixels of the border box width of element A.
The offsetHeight
attribute, when called on element A,
must return value that is the result of the following
algorithm:
If element A does not have an associated CSS layout box return zero and stop this algorithm.
Return the number of CSS pixels of the border box height of element A.
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 element A does not have an associated CSS layout box return zero and stop this algorithm.
...
When setting the scrollTop attribute to y
on element A user agents must run the
following algorithm:
If element A does not have vertical overflow stop this algorithm.
If y is negative act as if it was zero.
...
The scrollLeft
attribute, when called on element A,
must return the value that is the result of running the
following algorithm:
If element A does not have an associated CSS layout box return zero and stop this algorithm.
...
When setting the scrollLeft attribute to x
on element A user agents must run the
following algorithm:
If element A does not have horizontal overflow stop this algorithm.
If y is negative act as if it was zero.
...
The scrollWidth
attribute, when called on element A,
must return value that is the result of the following
algorithm:
If element 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 element A, plus the computed value of the padding-right
property of element A, plus the combined width of the margin box
children of element A subtracting all the collapsed margins of
those children, as number of CSS pixels.
The scrollHeight
attribute, when called on element A,
must return value that is the result of the following
algorithm:
If element 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 element A, plus the computed value of the padding-bottom
property of element A, plus the combined height of the margin box
children of element A subtracting all the collapsed margins
of those children, as number of CSS pixels.
clientTop,
clientLeft, clientWidth, and
clientHeight attributesThe clientTop
attribute, when called on element A,
must return the result of the following algorithm:
If element A does not have an associated CSS layout box or if it is an inline box return zero and stop this algorithm.
Return the computed value of the border-top-width
property as number of CSS pixels plus the width of any scrollbar rendered
between the top padding box and top border box as number of CSS
pixels.
The clientLeft
attribute, when called on element A,
must return the result of the following algorithm:
If element A does not have an associated CSS layout box or if it is an inline box return zero and stop this algorithm.
Return the computed value of the border-left-width
property as number CSS pixels plus the width of any scrollbar rendered
between the left padding box and left border box as number of CSS
pixels.
The clientWidth
attribute, when called on element A,
must return the result of the following algorithm:
If element A does not have an associated CSS layout box or if it is an inline box return zero and stop this algorithm.
If element A is the root element return the width of the viewport as number of CSS pixels and stop this algorithm.
Return the width of the padding box of element A (excluding the width of any rendered scrollbar between the padding and border box) as number of CSS pixels.
The clientHeight
attribute, when called on element A,
must return the result of the following algorithm:
If element A does not have an associated CSS layout box or if it is an inline box return zero and stop this algorithm.
If element A is the root element return the height of the viewport as number of CSS pixels and stop this algorithm.
Return the height of the padding box of element A (excluding the width of any rendered scrollbar between the padding and border box) as number of CSS pixels.
RangeView InterfaceObjects implementing the Range interface
must also implement the RangeView
interface. [DOM2TR]
interface RangeView {
TextRectangleList getClientRects();
TextRectangle getBoundingClientRect();
};
The
getClientRects()
method, when invoked, must return an empty (static)
TextRectangleList object if the range is empty (if the
boundary-points are identical) and otherwise a (static)
TextRectangleList object based on the following
conditions:
getClientRects() on the element.Text node selected or partially selected by the
range, include a TextRectangle object for each CSS box
associated with the text in the range (the part that is selected, not the
whole line box). The bounds of these TextRectangle 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.TextRectangle objects are in content order.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 (static)
TextRectangle object whose
top,
right,
bottom and
left members are zero.
Otherwise, return a union of the boxes in list,
excluding boxes that are empty, as a single TextRectangle
object. If all boxes are empty let the
top attribute of the new
TextRectangle object be the value of the
top attribute of the first border
box in the list returned. Do likewise for
left and then let
bottom be equal to
top and
right to
left.
MouseEventView InterfaceObjects implementing the MouseEvent interface
must also implement the MouseEventView
interface. [DOM2Events]
interface MouseEventView {
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 offsetX;
readonly attribute long offsetY;
readonly attribute long x;
readonly attribute long y;
};
The
screenX
attribute, on getting, must return the horizontal
coordinate, as number of CSS pixels, of the position where the event
occurred relative to the origin of the screen.
The
screenY
attribute, on getting, must return the vertical
coordinate, as number of CSS pixels, of the position where the event
occurred relative to the origin of the screen.
The pageX attribute,
on getting, must return the horizontal coordinate, as
number of CSS pixels, of the position where the event occurred relative to
the origin of the canvas.
The pageY attribute,
on getting, must return the vertical coordinate, as
number of CSS pixels, of the position where the event occurred relative to
the origin of the canvas.
The clientX attribute,
on getting, must return the horizontal coordinate, as
number of CSS pixels, of the position where the event occurred relative to
the origin of the viewport.
The clientY attribute,
on getting, must return the vertical coordinate, as
number of CSS pixels, of the position where the event occurred relative to
the origin of the viewport.
The offsetX
attribute, on getting, must return the horizontal
coordinate, as number of CSS pixels, of the position where the event
occurred relative to the origin of the padding box of the target
node.
The offsetY
attribute, on getting, must return the vertical
coordinate, as number of CSS pixels, of the position where the event
occurred relative to the origin of the padding box of the target
node.
The
x
attribute, on getting, must return the value of
pageX.
The
y
attribute, on getting, must return the value of
pageY.
Need to more carefully check the
x and y members and likely the
others too.
TextRectangleList InterfaceThe TextRectangleList object consists of an ordered list
of TextRectangle objects.
interface TextRectangleList {
readonly attribute unsigned long length;
TextRectangle item(in unsigned long index);
};
The
length
attribute must return the total number of
TextRectangle 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 TextRectangle objects
associated with the object. Otherwise, the TextRectangle
object at index must be
returned.
In ECMAScript implementations, objects that implement the
TextRectangleList interface must also
have a [[Get]] method that, when invoked with a number, acts
like the item() method would
when invoked with that argument.
TextRectangle InterfaceObjects implementing the TextRectangle interface represent
a rectangular box. The type of box is specified by the method that returns
a TextRectangle object.
interface TextRectangle {
readonly attribute float top;
readonly attribute float right;
readonly attribute float bottom;
readonly attribute float left;
};
The
top
attribute, on getting, must return the distance
between the top of the viewport and the top of the rectangle box as number
of CSS pixels.
The
right
attribute, on getting, must return the distance
between the left of the viewport and the right of the rectangle box as
number of CSS pixels.
The
bottom
attribute, on getting, must return the distance between
the top of the viewport and the bottom of the rectangle box as number of
CSS pixels.
The
left
attribute, on getting, must return the distance between
the left of the viewport and the left of the rectangle box as number of
CSS pixels.
All references are normative.
The editor would like to thank Alexey Feldgendler, David Vest, Hallvord R. M. Steen, Morten Stenshorne, Robert O'Callahan, Simon Pieters, and Tarquin Wilton-Jones 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.