CSSOM View Module

Abstract

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.

Status of this Document

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/.

This is the [DATE: 3 August 2002] [LONGSTATUS] of CSSOM View. Please send comments to www-style@w3.org (archived) with [cssom-view] at the start of the subject line.

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.

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.

Table of Contents

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!)

Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. RFC2119

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

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.

A conforming user agent implements all the requirements made by this specification.

Web IDL

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. WEBIDL

Terminology

Terminology used in this specification is from DOM Core, CSSOM and HTML. DOM CSSOM HTML

MouseEvent is defined in …

The HTML body element is the first body HTML element child of the root HTML element html.

Content edge, padding edge, border edge, and canvas are defined by CSS.

Viewport and initial containing block are defined by CSS 2.1 unless there is 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.

The term content refers to the dimensions of the element's content area, including overflown content.

The term document content refers to the area on the canvas that is rendered upon, excluding content on negative axis.

CSS pixels

All coordinates and dimensions for the APIs defined in this specification are in CSS pixels.

This does not apply to e.g. matchMedia() as the units are explicitly given there.

Extensions to the Window Interface

The MediaQueryList Interface

The Screen Interface

Extensions to the Document Interface

The CaretPosition Interface

Extensions to the Element Interface

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 objects these methods return must be static. That is, changes to the underlying document are not reflected in the objects.

Element Scrolling Members

To scroll an element into view, optionally with an align to top flag set, means to run these steps for each ancestor element or viewport that establishes a scrolling box, in order of innermost to outermost scrolling box:

1. If the Document associated with the element to be scrolled into view is not same origin with the Document associated with the element or viewport associated with the scrolling box, terminate these steps.

2. If the align to top flag is set align the top of the border box of the element to be scrolled into view with the top of the scrolling box.

3. Otherwise, if the align to top flag is not set align the bottom of the border box of the element to be scrolled into view with the bottom of the scrolling box.

4. Align the left of the border box of the element to be scrolled into view with the left of the scrolling box.

5. If the aligning did not cause content to move terminate these steps.

6. If the scrolling box is associated with an element

   Queue a task to fire an event named scroll at the element associated with the scrolling box, unless a task to fire that event at that element was already queued.

   If the scrolling box is associated with a viewport

   Queue a task to fire an event named scroll that bubbles at the Document object associated with the viewport, unless a task to fire that event at that Document object was already queued.

To scroll an element to x,y means to:

1. If either x or y is infinite or NaN terminate this algorithm.

2. If the element can have overflow to the right

   Let x be max(0, min(x, content width - content edge width)).

   If the element can have overflow to the left (under right-to-left conditions)

   Let x be min(0, max(x, content edge width - content width)).

3. Let y be max(0, min(y, content height - content edge height)).

4. Align content x-coordinate x with the left of the content edge of the element and align content y-coordinate y with the top of the content edge of the element.

5. If the aligning caused content to move queue a task to fire an event named scroll at the element, unless a task to fire that event at that element was already queued.

The clientTop, clientLeft, clientWidth, and clientHeight attributes

The clientTop, clientLeft, clientWidth, and clientHeight attributes must return zero if the element does not have any associated CSS layout box or if the CSS layout box is inline. Otherwise, these attributes must behave as defined in the remainder of this section.

Extensions to the HTMLElement Interface

Extensions to the Range Interface

The objects the methods described below return must be static.

Extensions to the MouseEvent Interface

The object IDL fragment redefines some members. Can we resolve this somehow?

Rectangles

The ClientRectList Interface

The ClientRect Interface

References

Normative references

Acknowledgments

The editors would like to thank Alexey Feldgendler, Björn Höhrmann, David Vest, Garrett Smith, Hallvord R. M. Steen, Leif Arne Storset, Luiz Agostini, Maciej Stachowiak, Michael Dyck, Mike Wilson, Morten Stenshorne, Peter-Paul Koch, Rachel Kmetz, Robert O'Callahan, Sam Weinig, Simon Pieters, Sylvain Galineau, Tarquin Wilton-Jones, Thomas Moore, 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.