Copyright © 2008 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 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 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.
This is the first public Working Draft of the CSSOM View Module.
WindowView Interface
DocumentView Interface
ElementView Interface
RangeView Interface
MouseEventView Interface
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.