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, CSSOM and HTML. DOM CSSOM HTML

MouseEvent and MouseEventInit are 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, margin 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 that has an associated SVG layout box in which case that element acts as viewport and initial containing block.

Block flow direction and inline base direction are defined in CSS Writing Modes Module. CSSWRITINGMODES

A scrolling box of a viewport or element has two overflow directions, depending on the viewport's or element's block flow direction and inline base direction, as follows:

If the block flow direction is top-to-bottom and the inline base direction is left-to-right

If the block flow direction is left-to-right and the inline base direction is left-to-right

Rightward and downward.

If the block flow direction is top-to-bottom and the inline base direction is right-to-left

If the block flow direction is right-to-left and the inline base direction is left-to-right

Leftward and downward.

If the block flow direction is right-to-left and the inline base direction is right-to-left

Leftward and upward.

If the block flow direction is left-to-right and the inline base direction is right-to-left

Righward and upward.

The term scrolling area refers to a box of a viewport or an element that has the following edges, depending on the viewport's or element's scrolling box's overflow directions.

The beginning edges of a particular set of edges of a box or element are the following edges:

If the overflow directions are rightward and downward

The top and left edges.

If the overflow directions are leftward and downward

The top and right edges.

If the overflow directions are leftward and upward

The bottom and right edges.

If the overflow directions are rightward and upward

The bottom and left edges.

The ending edges of a particular set of edges of a box or element are the following edges:

If the overflow directions are rightward and downward

The bottom and right edges.

If the overflow directions are leftward and downward

The bottom and left edges.

If the overflow directions are leftward and upward

The top and left edges.

If the overflow directions are rightward and upward

The top and right edges.

The term CSS layout box refers to the same term in CSS. For the purpose of the requirements in this specification, elements that have a computed value of the 'display' property that is 'table-column' or 'table-column-group' must be considered to have an associated CSS layout box (the column or column group, respectively).

The term SVG layout box refers to the same term in SVG.

The terms CSS layout box and SVG layout box are not currently defined by CSS or SVG.

The term layout box refers to either a CSS layout box or an SVG layout box.

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.

Common Infrastructure

Scrolling

When a user agent is to perform a scroll of a scrolling box box, to a given position position, with a set of steps task, an associated element element and optionally a scroll behavior behavior (which is auto if omitted), the following steps must be run:

1. Abort any ongoing smooth scroll for box.

2. If the user agent honors the 'scroll-behavior' property and one of the following are true:

   • behavior is auto and element is not null and its computed value of the 'scroll-behavior' property is 'smooth'

   • behavior is smooth

   ...then follow these substeps:

   1. Perform a smooth scroll of box to position.

   2. Queue a task to run task, unless a task to run task is in the queue.

   3. Repeat the previous step in a user-agent-defined interval while the smooth scroll is ongoing, as well as when the smooth scroll is completed (but not if it is aborted).

3. Otherwise, follow these substeps:

   1. Perform an instant scroll of box to position.

   2. Queue a task to run task, unless a task to run task is in the queue.

When a user agent is to perform a smooth scroll of a scrolling box box to position, it must update the scroll position of box in a user-agent-defined fashion over a user-agent-defined amount of time. When the scroll is completed, the scroll position of box must be position. The scroll can also be aborted, either by an algorithm or by the user.

When a user agent is to perform an instant scroll of a scrolling box box to position, it must update the scroll position of box to position.

To scroll to the beginning of the document for a document document, follow these steps:

1. Let viewport be the viewport that is associated with document.

2. Let position be the the scroll position viewport would have by aligning the beginning edges of the scrolling area with the beginning edges of viewport.

3. If position is the same as viewport's current scroll position, and viewport does not have an ongoing smooth scroll, abort these steps.

4. Let task be these steps:

   1. Fire an event named scroll that bubbles at document.

5. Perform a scroll of viewport to position, with the set of steps task, and document's root element as the associated element, if there is one, or null otherwise.

This algorithm is used when navigating to the #top fragment identifier, as defined in HTML. HTML

Extensions to the Window Interface

enum ScrollBehavior { "auto", "instant", "smooth" };

dictionary ScrollOptions {
  double x;
  double y;
  ScrollBehavior behavior = "auto";
};

partial interface Window {
  MediaQueryList matchMedia(DOMString query);
  readonly attribute Screen screen;

  // viewport
  readonly attribute double innerWidth;
  readonly attribute double innerHeight;

  // viewport scrolling
  readonly attribute double scrollX;
  readonly attribute double pageXOffset;
  readonly attribute double scrollY;
  readonly attribute double pageYOffset;
  void scroll(double x, double y, optional ScrollOptions options);
  void scrollTo(double x, double y, optional ScrollOptions options);
  void scrollBy(double x, double y, optional ScrollOptions options);

  // client
  readonly attribute double screenX;
  readonly attribute double screenY;
  readonly attribute double outerWidth;
  readonly attribute double outerHeight;
};

When the matchMedia(query) method is invoked these steps must be run:

1. Let parsed media query list be the result of parsing query.

2. Return a new MediaQueryList object, associated with the Window object, with parsed media query list as its associated media query list.

The screen attribute must return the Screen object associated with the Window object. It always returns the same object.

Accessing screen through a WindowProxy object might yield different results when the Document is navigated.

The innerWidth attribute must return the viewport width including the size of a rendered scroll bar (if any), or zero if there is no viewport.

var viewportWidth = innerWidth

The innerHeight attribute must return the viewport height including the size of a rendered scroll bar (if any), or zero if there is no viewport.

The scrollX attribute attribute must return the x-coordinate, relative to the initial containing block origin, of the left of the viewport, or zero if there is no viewport.

The pageXOffset attribute must return the value returned by the scrollX attribute.

The scrollY attribute attribute must return the y-coordinate, relative to the initial containing block origin, of the top of the viewport, or zero if there is no viewport.

The pageYOffset attribute must return the value returned by the scrollY attribute.

When the scroll(x, y, options) method is invoked these steps must be run:

1. If there is no viewport, abort these steps.

2. Let viewport width be the width of the viewport excluding the width of the scroll bar, if any.

3. Let viewport height be the height of the viewport excluding the height of the scroll bar, if any.

4. If the viewport has rightward overflow direction

   Let x be max(0, min(x, viewport scrolling area width - viewport width)).

   If the viewport has leftward overflow direction

   Let x be min(0, max(x, viewport width - viewport scrolling area width)).

5. If the viewport has downward overflow direction

   Let y be max(0, min(y, viewport scrolling area height - viewport height)).

   If the viewport has upward overflow direction

   Let y be min(0, max(y, viewport height - viewport scrolling area height)).

6. Let position be the scroll position the viewport would have by aligning the x-coordinate x of the viewport scrolling area with the left of the viewport and aligning the y-coordinate y of the viewport scrolling area with the top of the viewport.

7. If position is the same as the viewport's current scroll position, and the viewport does not have an ongoing smooth scroll, abort these steps.

8. Let task be these steps:

   1. Fire an event named scroll that bubbles at the Document object.

9. Perform a scroll of the viewport to position, with the set of steps task, and the Document's root element as the associated element, if there is one, or null otherwise, and the scroll behavior being the value of the behavior dictionary member of options.

When the scrollTo(x, y, options) method is invoked, the user agent must act as if the scroll() method was invoked with the same arguments.

When the scrollBy(x, y, options) method is invoked, the user agent must act as if the scroll() method was invoked with x plus scrollX as first argument and y plus scrollY as second argument.

The screenX attribute must return the x-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 screenY attribute must return the y-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 outerWidth attribute must return the width of the client window. If there is no client window this attribute must return zero.

The outerHeight attribute must return the height of the client window. If there is no client window this attribute must return zero.

The MediaQueryList Interface

A MediaQueryList object has an associated media query list set on creation and an associated list of media query list listeners, which is initially empty.

If the associated media query list changes in evaluation then, for each listener in the list of media query list listeners — in appending order, queue a task that invokes the listener, passing as argument the MediaQueryList object.

function handleOrientationChange(mql) {
    if(mql.matches) // landscape
      …
    else
      …
  }
  var mql = matchMedia("(orientation:landscape)")
  mql.addListener(handleOrientationChange)

interface MediaQueryList {
  readonly attribute DOMString media;
  readonly attribute boolean matches;
  void addListener(MediaQueryListListener listener);
  void removeListener(MediaQueryListListener listener);
};

callback MediaQueryListListener = void (MediaQueryList list);

The media attribute must return the serialized form of the associated media query list.

The matches attribute must return true if the associated media query list matches the state of the rendered Document and false if it does not.

When the addListener(listener) method is invoked listener must be appended to the list of media query list listeners, unless it is already in the list of media query list listeners.

When the removeListener(listener) method is invoked listener must be removed from the list of media query list listeners.

The Screen Interface

As its name suggests, the Screen interface represents information about the screen of the output device.

interface Screen {
  readonly attribute double availWidth;
  readonly attribute double availHeight;
  readonly attribute double width;
  readonly attribute double height;
  readonly attribute unsigned long colorDepth;
  readonly attribute unsigned long pixelDepth;
};

The availWidth attribute must return the available width of the rendering surface of the output device.

The availHeight attribute must return the available height of the rendering surface of the output device.

The width attribute must return the width of the output device.

The height attribute must return the height of the output device.

The colorDepth attribute must return 24.

The pixelDepth attribute must return 24.

The colorDepth and pixelDepth attributes are useless but are included for compatibility.

Extensions to the Document Interface

partial interface Document {
  Element? elementFromPoint(double x, double y);
  sequence<Element> elementsFromPoint(double x, double y);
  CaretPosition? caretPositionFromPoint(double x, double y);
};

The elementFromPoint(x, y) method must follow these steps:

1. 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 greater than the viewport height excluding the size of a rendered scroll bar (if any), or there is no viewport associated with the document, return null and terminate these steps.

2. If there is a layout box in the viewport that would be a target for hit testing at coordinates x,y, return the associated element and terminate these steps.

3. If the document has a root element, return the root element and terminate these steps.

4. Return null.

The elementFromPoint() method does not necessarily return the top-most painted element. For instance, an element can be excluded from being a target for hit testing by using the 'pointer-events' CSS property.

The elementsFromPoint(x, y) method must follow these steps:

1. Let sequence be a new empty sequence.

2. 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 greater than the viewport height excluding the size of a rendered scroll bar (if any), or there is no viewport associated with the document, return sequence and terminate these steps.

3. For each layout box in the viewport, in paint order, starting with the topmost box, that would be a target for hit testing at coordinates x,y even if nothing would be overlapping it, append the associated element to sequence.

4. If the document has a root element, and the last item in sequence is not the root element, append the root element to sequence.

5. Return sequence.

The caretPositionFromPoint(x, y) method must return the result of running these steps:

1. If there is no viewport associated with the document, return null.

2. 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) return null.

3. If at the coordinates x,y in the viewport no text insertion point indicator would have been inserted return null.

4. If at the coordinates x,y in the viewport a text insertion point indicator would have been inserted in a text entry widget which is also a replaced element return a caret position with its properties set as follows:

   caret node

   The node corresponding to the text entry widget.

   caret offset

   The amount of 16-bit units to the left of where the text insertion point indicator would have inserted.

   caret range

   null

5. Otherwise, return a caret position where the caret range is a collapsed Range object for the position where the text insertion point indicator would have been inserted and the other properties are set as follows:

   caret node

   The startContainer of the caret range.

   caret offset

   The startOffset of the caret range.

The specifics of hit testing are out of scope of this specification and therefore the exact details of elementFromPoint() and caretPositionFromPoint() are therefore too. Hit testing will hopefully be defined in a future revision of CSS or HTML.

The CaretPosition Interface

A caret position gives the position of a text insertion point indicator. It always has an associated caret node, caret offset, and caret range. It is represented by a CaretPosition object.

interface CaretPosition {
  readonly attribute Node offsetNode;
  readonly attribute unsigned long offset;
  ClientRect? getClientRect();
};

The offsetNode attribute must return the caret node.

The offset attribute must return the caret offset.

The getClientRect() method must follow these steps, aborting on the first step that returns a value:

1. If caret range is not null:

   1. Let list be the result of invoking the getClientRects() method on the range.

   2. If list is empty, return null.

   3. Return the ClientRect object in list at index 0.

2. If caret node is a text entry widget that is a replaced element, and that is in the document, return a ClientRect object for the caret in the widget as represented by the caret offset value.

3. Return null.

Extensions to the Element Interface

partial interface Element {
  ClientRectList getClientRects();
  ClientRect getBoundingClientRect();
  void scrollIntoView(optional boolean top = true, optional ScrollOptions options);
  attribute (double or ScrollOptions) scrollTop;
  attribute (double or ScrollOptions) scrollLeft;
  readonly attribute double scrollWidth;
  readonly attribute double scrollHeight;
  readonly attribute double clientTop;
  readonly attribute double clientLeft;
  readonly attribute double clientWidth;
  readonly attribute double clientHeight;
};

The getClientRects() method, when invoked, must return the result of the following algorithm:

1. If the element on which it was invoked does not have an associated layout box return an empty ClientRectList object and stop this algorithm.

2. If the element has an associated SVG layout box return a ClientRectList object containing a single ClientRect object that describes the bounding box of the element as defined by the SVG specification. SVG

3. 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 the 'display' property of 'table' or 'inline-table' include both the table box and the caption box, if any, but not the anonymous container box.

   • Replace each anonymous block box with its child box(es) and repeat this until no anonymous block boxes are left in the final list.

The getBoundingClientRect() method, when invoked, must return the result of the following algorithm:

1. Let list be the result of invoking getClientRects() on the same element this method was invoked on.

2. If the list is empty return a ClientRect object whose top, right, bottom and left members are zero.

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

var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
var exampleWidth = example.width;
var exampleHeight = example.height;

The scrollIntoView(top, options) method must run these steps:

1. If the element does not have any associated layout box terminate these steps.

2. Scroll the element into view with the align to top flag set if top is true, and the scroll behavior being the value of the behavior dictionary member of options.

3. Optionally perform some other action that brings the element to the user's attention.

The scrollTop attribute must return the result of running these steps:

1. If the element does not have any associated CSS layout box or the element is the root element and the Document is in quirks mode return zero and terminate these steps.

2. If the element is the root element return the value of scrollY.

3. If the element is the HTML body element, the Document is in quirks mode, and the element does not have any overflow, return the value of scrollY.

4. Return the y-coordinate of the scrolling area at the alignment point with the top of the padding edge of the element.

When setting the scrollTop attribute these steps must be run:

1. If the given value is a ScrollOptions object, and the y dictionary member is not present, abort these steps.

2. If the given value is a ScrollOptions object, let y be the value of the y dictionary member. Otherwise, let y be the given value.

3. If the element does not have any associated CSS layout box, the element is the root element and the Document is in quirks mode, or the element has no associated scrolling box, or the element has no overflow, terminate these steps.

4. If the element is the root element invoke scroll() with zero as first argument and y as second, and, if the given value is a ScrollOptions object, the given value as the third argument.

5. If the element is the HTML body element, the Document is in quirks mode, and the element does not have any vertical overflow, invoke scroll() with scrollX as first argument and y as second, and, if the given value is a ScrollOptions object, the given value as the third argument.

6. Scroll the element to scrollLeft,y, with the scroll behavior being the value of the behavior dictionary member if the given value is a ScrollOptions object, or auto otherwise.

The scrollLeft attribute must return the result of running these steps:

1. If the element does not have any associated CSS layout box or the element is the root element and the Document is in quirks mode return zero and terminate these steps.

2. If the element is the root element return the value of scrollX.

3. If the element is the HTML body element, the Document is in quirks mode, and the element does not have any overflow, return the value of scrollX.

4. Return the x-coordinate of the scrolling area at the alignment point with the left of the padding edge of the element.

When setting the scrollLeft attribute these steps must be run:

1. If the given value is a ScrollOptions object, and the x dictionary member is not present, abort these steps.

2. If the given value is a ScrollOptions object, let x be the value of the x dictionary member. Otherwise, let x be the given value.

3. If the element does not have any associated CSS layout box, the element is the root element and the Document is in quirks mode, or the element has no associated scrolling box, or the element has no overflow, terminate these steps.

4. If the element is the root element invoke scroll() with x as first argument and zero as second, and, if the given value is a ScrollOptions object, the given value as the third argument.

5. If the element is the HTML body element, the Document is in quirks mode, and the element does not have any vertical overflow, invoke scroll() with x as first argument and scrollY as second, and, if the given value is a ScrollOptions object, the given value as the third argument.

6. Scroll the element to x,scrollTop, with the scroll behavior being the value of the behavior dictionary member if the given value is a ScrollOptions object, or auto otherwise.

The scrollWidth attribute must return the result of running these steps:

1. If the element does not have any associated CSS layout box return zero and terminate these steps.

2. Let viewport width be the width of the viewport excluding the width of the scroll bar, if any, or zero if there is no viewport.

3. If the element is the root element and the Document is not in quirks mode return max(viewport scrolling area width, viewport width).

4. If the element is the HTML body element and the Document is in quirks mode return max(viewport scrolling area width, viewport width).

5. Return the width of the element's scrolling area.

The scrollHeight attribute must return the result of running these steps:

1. If the element does not have any associated CSS layout box return zero and terminate these steps.

2. Let viewport height be the height of the viewport excluding the height of the scroll bar, if any, or zero if there is no viewport.

3. If the element is the root element and the Document is not in quirks mode return max(viewport scrolling area height, viewport height).

4. If the element is the HTML body element and the Document is in quirks mode return max(viewport scrolling area height, viewport height).

5. Return the height of the element's scrolling area.

The clientTop attribute must run these steps:

1. If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.

2. Return the computed value of the 'border-top-width' property plus the height of any scrollbar rendered between the top padding edge and the top border edge.

The clientLeft attribute must run these steps:

1. If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.

2. Return 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.

The clientWidth attribute must run these steps:

1. If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.

2. If the element is the root element and the element's document's browsing context is a top-level browsing context, return the viewport width excluding the size of a rendered scroll bar (if any).

3. Return the width of the padding edge excluding the width of any rendered scrollbar between the padding edge and the border edge.

The clientHeight attribute must run these steps:

1. If the element has no associated CSS layout box or if the CSS layout box is inline, return zero.

2. If the element is the root element and the element's document's browsing context is a top-level browsing context, return the viewport height excluding the size of a rendered scroll bar (if any).

3. Return the height of the padding edge excluding the height of any rendered scrollbar between the padding edge and the border edge.

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 element, optionally with an align to top flag set, and optionally with a scroll behavior behavior (which is auto if omitted), means to run these steps for each ancestor element or viewport that establishes a scrolling box scrolling box, in order of innermost to outermost scrolling box:

1. If the Document associated with element is not same origin with the Document associated with the element or viewport associated with box, terminate these steps.

2. Let element bounding border box be the box that the return value of invoking getBoundingClientRect() on element represents.

3. Let scrolling box edge A be the beginning edge in the block flow direction of scrolling box, and let element edge A be element bounding border box's edge on the same physical side as that of scrolling box edge A.

4. Let scrolling box edge B be the ending edge in the block flow direction of scrolling box, and let element edge B be element bounding border box's edge on the same physical side as that of scrolling box edge B.

5. Let scrolling box edge C be the beginning edge in the inline base direction of scrolling box, and let element edge C be element bounding border box's edge on the same physical side as that of scrolling box edge C.

6. Let scrolling box edge D be the ending edge in the inline base direction of scrolling box, and let element edge D be element bounding border box's edge on the same physical side as that of box edge D.

7. Let element width be the distance between element edge C and element edge D.

8. Let scrolling box width be the distance between scrolling box edge C and scrolling box edge D.

9. Let position be the scroll position scrolling box would have by following these steps:

   1. If the align to top flag is set align element edge A with scrolling box edge A.

   2. Otherwise, the align to top flag is not set; align element edge B with scrolling box edge B.

   3. If element edge C and element edge D are both outside scrolling box edge C and scrolling box edge D

      Do nothing.

      If element edge C is outside scrolling box edge C and element width is less than scrolling box width

      If element edge D is outside scrolling box edge D and element width is greater than scrolling box width

      Align element edge C with scrolling box edge C.

      If element edge C is outside scrolling box edge C and element width is greater than scrolling box width

      If element edge D is outside scrolling box edge D and element width is less than scrolling box width

      Align element edge D with scrolling box edge D.

10. If position is the same as scrolling box's current scroll position, and scrolling box does not have an ongoing smooth scroll, abort these steps.

11. If scrolling box is associated with an element

    Let associated element be the element.

    Let task be these steps:

    1. Fire an event named scroll at associated element.

    If scrolling box is associated with a viewport

    Let associated element be the Document's root element, if there is one, or null otherwise.

    Let task be these steps:

    1. Fire an event named scroll that bubbles at the Document object associated with the viewport.

12. Perform a scroll of scrolling box to position, with the set of steps task, associated element as the associated element and behavior as the scroll behavior.

To scroll an element element to x,y optionally with a scroll behavior behavior (which is auto if omitted) means to:

1. Let box be element's associated scrolling box.

2. If box has rightward overflow direction

   Let x be max(0, min(x, element scrolling area width - element padding edge width)).

   If box has leftward overflow direction

   Let x be min(0, max(x, element padding edge width - element scrolling area width)).

3. If box has downward overflow direction

   Let y be max(0, min(y, element scrolling area height - element padding edge height)).

   If box has upward overflow direction

   Let y be min(0, max(y, element padding edge height - element scrolling area height)).

4. Let position be the scroll position box would have by aligning scrolling area x-coordinate x with the left of box and aligning scrolling area y-coordinate y with the top of box.

5. If position is the same as box's current scroll position, and box does not have an ongoing smooth scroll, abort these steps.

6. Let task be these steps:

   1. Fire an event named scroll at the element.

7. Perform a scroll of box to position, with the set of steps task, element as the associated element and behavior as the scroll behavior.

Extensions to the HTMLElement Interface

partial interface HTMLElement {
  readonly attribute Element offsetParent;
  readonly attribute double offsetTop;
  readonly attribute double offsetLeft;
  readonly attribute double offsetWidth;
  readonly attribute double offsetHeight;
};

The offsetParent attribute must return the result of running these steps:

1. If any of the following holds true return null and terminate this algorithm:

   • The element does not have an associated CSS layout box.
   • The element is the root element.
   • The element is the HTML body element.
   • The element's computed value of the 'position' property is 'fixed'.

2. Return the nearest ancestor element of the element for which at least one of the following is true and terminate this algorithm if such an ancestor is found:

   • The computed value of the 'position' property is not 'static'.
   • It is the HTML body element.
   • The computed value of the 'position' property of the element is 'static' and the ancestor is one of the following HTML elements: td, th, or table.

3. Return null.

The offsetTop attribute must return the result of running these steps:

1. If the element is the HTML body element or does not have any associated CSS layout box return zero and terminate this algorithm.

2. If the offsetParent of the element is null return the y-coordinate of the top border edge of the first CSS layout box associated with the element, relative to the initial containing block origin, and terminate this algorithm.

3. Return the result of subtracting the y-coordinate of the top padding edge of the first CSS layout box associated with the offsetParent of the element from the y-coordinate of the top border edge of the first CSS layout box associated with the element, relative to the initial containing block origin.

   An inline element that consists of multiple line boxes will only have its first CSS layout box considered.

The offsetLeft attribute must return the result of running these steps:

1. If the element is the HTML body element or does not have any associated CSS layout box return zero and terminate this algorithm.

2. If the offsetParent of the element is null return the x-coordinate of the left border edge of the first CSS layout box associated with the element, relative to the initial containing block origin, and terminate this algorithm.

3. Return the result of subtracting the x-coordinate of the left padding edge of the first CSS layout box associated with the offsetParent of the element from the x-coordinate of the left border edge of the first CSS layout box associated with the element, relative to the initial containing block origin.

The offsetWidth attribute must return the result of running these steps:

1. If the element does not have any associated CSS layout box return zero and terminate this algorithm.

2. Return the border edge width of the first CSS layout box associated with the element.

The offsetHeight attribute must return the result of running these steps:

1. If the element does not have any associated CSS layout box return zero and terminate this algorithm.

2. Return the border edge height of the first CSS layout box associated with the element.

Extensions to the Range Interface

The objects the methods described below return must be static.

partial interface Range {
  ClientRectList getClientRects();
  ClientRect getBoundingClientRect();
};

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:

• For each element selected by the range, whose parent is not selected by the range, include the border boxes returned by invoking getClientRects() on the element.
• For each 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:

1. Let list be the result of invoking getClientRects() on the same range this method was invoked on.

2. If list is empty return a ClientRect object whose top, right, bottom and left members are zero.

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

Extensions to the MouseEvent Interface

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

partial interface MouseEvent {
  readonly attribute double screenX;
  readonly attribute double screenY;
  readonly attribute double pageX;
  readonly attribute double pageY;
  readonly attribute double clientX;
  readonly attribute double clientY;
  readonly attribute double x;
  readonly attribute double y;
  readonly attribute double offsetX;
  readonly attribute double offsetY;
};

partial dictionary MouseEventInit {
  double screenX = 0;
  double screenY = 0;
  double clientX = 0;
  double clientY = 0;
};

The screenX attribute must return the x-coordinate of the position where the event occurred relative to the origin of the screen.

The screenY attribute must return the y-coordinate of the position where the event occurred relative to the origin of the screen.

The pageX attribute must follow these steps:

1. If the event's dispatch flag is set, return the horizontal coordinate of the position where the event occurred relative to the origin of the initial containing block and terminate these steps.

2. Let offset be the value of the scrollX attribute of the event's associated Window object, if there is one, or zero otherwise.

3. Return the sum of offset and the value of the event's clientX attribute.

The pageY attribute must follow these steps:

1. If the event's dispatch flag is set, return the vertical coordinate of the position where the event occurred relative to the origin of the initial containing block and terminate these steps.

2. Let offset be the value of the scrollX attribute of the event's associated Window object, if there is one, or zero otherwise.

3. Return the sum of offset and the value of the event's clientY attribute.

The clientX attribute must return the x-coordinate of the position where the event occurred relative to the origin of the viewport.

The clientY attribute must return the y-coordinate of the position where the event occurred relative to the origin of the viewport.

The x attribute must return the value of clientX.

The y attribute must return the value of clientY.

The offsetX attribute must follow these steps:

1. If the event's dispatch flag is set, return the x-coordinate of the position where the event occurred relative to the origin of the padding edge of the target node and terminate these steps.

2. Return the value of the event's pageX attribute.

The offsetY attribute must follow these steps:

1. If the event's dispatch flag is set, return the y-coordinate of the position where the event occurred relative to the origin of the padding edge of the target node and terminate these steps.

2. Return the value of the event's pageY attribute.

Rectangles

The ClientRectList Interface

The ClientRectList interface 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 throw an IndexSizeError exception when index is greater than the number of ClientRect objects associated with the object. Otherwise, the ClientRect object at index must be returned.

The ClientRect Interface

Objects 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 double top;
  readonly attribute double right;
  readonly attribute double bottom;
  readonly attribute double left;
  readonly attribute double width;
  readonly attribute double height;
};

The top attribute must return the y-coordinate, relative to the viewport origin, of the top of the rectangle box.

The right attribute must return the x-coordinate, relative to the viewport origin, of the right of the rectangle box.

The bottom attribute must return the y-coordinate, relative to the viewport origin, of the bottom of the rectangle box.

The left attribute must return the x-coordinate, relative to the viewport origin, of the left of the rectangle box.

The width attribute must return the width of the rectangle box.

This is identical to right minus left.

The height attribute must return the height of the rectangle box.

This is identical to bottom minus top.

Events

Resizing viewports

Whenever a viewport has its width or height changed (e.g. as a result of the user resizing the browser window, or zooming in, or an iframe element's dimensions are changed), the user agent must queue a task to fire an event event named resize at the Window object associated with that viewport. If such a resize is ongoing over a period of time, the user agent must queue that task at a user-agent-defined interval while the resize is ongoing.

Scrolling

Whenever a viewport gets scrolled in response to user interaction, the user agent must queue a task to fire an event named scroll that bubbles at the Document object associated with that viewport. If such a scroll is ongoing over a period of time, the user agent must queue that task at a user-agent-defined interval while the scroll is ongoing.

Whenever an element gets scrolled in response to user interaction, the user agent must queue a task to fire an event named scroll at the element. If such a scroll is ongoing over a period of time, the user agent must queue that task at a user-agent-defined interval while the scroll is ongoing.

CSS properties

The features in this section should be moved to some other specification.

Smooth Scrolling: The 'scroll-behavior' Property

Name: scroll-behavior
Value: instant | smooth
Initial: instant
Applies to: scrolling boxes
Inherited: no
Computed value:	specified value 
Media: visual
Animatable: no
Canonical Order: per grammar

The 'scroll-behavior' property specifies the scrolling behavior for a scrolling box, when scrolling happens due to navigation or CSSOM scrolling APIs. Scrolls that are performed by the user are not affected by this property. When this property is specified on the root element, it applies to the viewport instead.

The 'scroll-behavior' property of the HTML body element is not propagated to the viewport.

'instant'

The scrolling box is scrolled in an instant fashion.

'smooth'

The scrolling box is scrolled in a smooth fashion using a user-agent-defined timing function over a user-agent-defined period of time. User agents should follow platform convensions, if any.

User agents may ignore this property.

References

Acknowledgments

The editors would like to thank Alan Stearns, Alexey Feldgendler, Björn Höhrmann, Dan Bates, David Vest, Elliott Sprehn, 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, Scott Johnson, Sebastian Zartner, 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.