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.
Status of this DocumentThis 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.
Table of ContentsWindowView Interface
DocumentView InterfaceElementView Interface
RangeView InterfaceMouseEventView InterfaceEverything 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.
1.1 DependenciesThis 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]
1.2 TerminologyThe 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 Interface
Objects 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 Interface
As 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 Interface
interface 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 Interface
This 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.
4. TheElementView Interface
Objects 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;
};4.1 The getClientRects() and getBoundingClientRect() methods
The 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 attributes
The 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 attributes
The 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 attributes
The 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 Interface
Objects 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 Interface
Objects 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 Interface
The 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 Interface
Objects 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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4