Provide cross-browser Rects for box model dimensions for Elements.

sdk/lib/html/dart2js/html_dart2js.dart

 /// The Dart HTML library.
 library dart.dom.html;
 
 import 'dart:async';
 import 'dart:collection';
 import 'dart:_collection-dev';
 import 'dart:html_common';
 import 'dart:indexed_db';
 import 'dart:isolate';
 import 'dart:json' as json;
@@ skipping 7009 matching lines @@
   }
 
   Element get single {
     if (length > 1) throw new StateError("More than one element");
     return first;
   }
 }
 
 /** 
  * An immutable list containing HTML elements. This list contains some
- * additional methods for ease of CSS manipulation on a group of elements.
+ * additional methods when compared to regular lists for ease of CSS 
+ * manipulation on a group of elements.
  */
 abstract class ElementList<T extends Element> extends ListBase<T> {
   /**
    * The union of all CSS classes applied to the elements in this list.
    *
    * This set makes it easy to add, remove or toggle (add if not present, remove
    * if present) the classes applied to a collection of elements.
    *
    *     htmlList.classes.add('selected');
    *     htmlList.classes.toggle('isOnline');
    *     htmlList.classes.remove('selected');
    */
   CssClassSet get classes;
 
   /** Replace the classes with `value` for every element in this list. */
   set classes(Iterable<String> value);
+
+  /**
+   * Access dimensions and position of the first Element's content in this list.

[blois, 2013/05/22 01:18:07]

If it's just the first item's, then why have it here at all?

+   * 
+   * Setting the height or width properties will set the height or width
+   * property for all elements in the list. This returns a rectangle with the 
+   * dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not.
+   */
+  CssRect get contentEdge;
+  
+  /**
+   * Access dimensions and position of the first Element's content + padding box 
+   * in this list.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `innerHeight` value for an element. This
+   * is also a rectangle equalling the dimensions of clientHeight and
+   * clientWidth.
+   */
+  CssRect get paddingEdge;
+
+  /**
+   * Access dimensions and position of the first Element's content + padding +
+   * border box in this list.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   */
+  CssRect get borderEdge;
+
+  /**
+   * Access dimensions and position of the first Element's content + padding +
+   * border + margin box in this list.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   */
+  CssRect get marginEdge;
 }
 
 // TODO(jacobr): this is an inefficient implementation but it is hard to see
 // a better option given that we cannot quite force NodeList to be an
 // ElementList as there are valid cases where a NodeList JavaScript object
 // contains Node objects that are not Elements.
 class _FrozenElementList<T extends Element> extends ListBase<T> implements ElementList {
   final List<Node> _nodeList;
+  // The subset of _nodeList that are Elements.
+  List<Element> _elementList;
 
-  _FrozenElementList._wrap(this._nodeList);
+  _FrozenElementList._wrap(this._nodeList) {
+    _elementList = _nodeList.where((e) => e is Element);
+  }
 
   int get length => _nodeList.length;
 
   Element operator [](int index) => _nodeList[index];
 
   void operator []=(int index, Element value) {
     throw new UnsupportedError('Cannot modify list');
   }
 
   void set length(int newLength) {
     throw new UnsupportedError('Cannot modify list');
   }
 
   void sort([Comparator<Element> compare]) {
     throw new UnsupportedError('Cannot sort list');
   }
 
   Element get first => _nodeList.first;
 
   Element get last => _nodeList.last;
 
   Element get single => _nodeList.single;
 
-  CssClassSet get classes => new _MultiElementCssClassSet(
-      _nodeList.where((e) => e is Element));
+  CssClassSet get classes => new _MultiElementCssClassSet(_elementList);
 
   void set classes(Iterable<String> value) {
-    _nodeList.where((e) => e is Element).forEach((e) => e.classes = value);
+    _elementList.forEach((e) => e.classes = value);
   }
+
+  /**
+   * Access this element's content position.

[blois, 2013/05/22 01:18:07]

This just implements the API, right? If so, duplicating the documentation isn't
needed.

+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not.
+   */
+  CssRect get contentEdge => new _ContentCssListRect(_elementList);
+  
+  /**
+   * Access the dimensions and position of this element's content + padding box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `innerHeight` value for an element. This
+   * is also a rectangle equalling the dimensions of clientHeight and
+   * clientWidth.
+   */
+  CssRect get paddingEdge => _elementList.first.paddingEdge;
+
+  /**
+   * Access the dimensions and position of this element's content + padding +
+   * border box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   */
+  CssRect get borderEdge => _elementList.first.borderEdge;
+
+  /**
+   * Access the dimensions and position of this element's content + padding +
+   * border + margin box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   */
+  CssRect get marginEdge => _elementList.first.marginEdge;
 }
 
 /**
  * An abstract class, which all HTML elements extend.
  */
 @DomName('Element')
 abstract class Element extends Node implements ElementTraversal native "Element" {
 
   /**
    * Creates an HTML element from a valid fragment of HTML.
@@ skipping 404 matching lines @@
     } else if (JS('bool', '!!#.webkitMatchesSelector', this)) {
       return JS('bool', '#.webkitMatchesSelector(#)', this, selectors);
     } else if (JS('bool', '!!#.mozMatchesSelector', this)) {
       return JS('bool', '#.mozMatchesSelector(#)', this, selectors);
     } else if (JS('bool', '!!#.msMatchesSelector', this)) {
       return JS('bool', '#.msMatchesSelector(#)', this, selectors);
     }
     throw new UnsupportedError("Not supported on this platform");
   }
 
+  /**
+   * Access this element's content position.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not.
+   */
+  CssRect get contentEdge => new _ContentCssRect(this);
+  
+  /**
+   * Access the dimensions and position of this element's content + padding box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `innerHeight` value for an element. This
+   * is also a rectangle equalling the dimensions of clientHeight and
+   * clientWidth.
+   */
+  CssRect get paddingEdge => new _PaddingCssRect(this);
+
+  /**
+   * Access the dimensions and position of this element's content + padding +
+   * border box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   */
+  CssRect get borderEdge => new _BorderCssRect(this);
+
+  /**
+   * Access the dimensions and position of this element's content + padding +
+   * border + margin box.
+   * 
+   * This returns a rectangle with the dimenions actually available for content
+   * in this element, in pixels, regardless of this element's box-sizing 
+   * property. Unlike [getBoundingClientRect], the dimensions of this rectangle
+   * will return the same numerical height if the element is hidden or not. This
+   * can be used to retrieve jQuery's `outerHeight` value for an element.
+   */
+  CssRect get marginEdge => new _MarginCssRect(this);
 
   @DomName('Element.abortEvent')
   @DocsEditable
   static const EventStreamProvider<Event> abortEvent = const EventStreamProvider<Event>('abort');
 
   @DomName('Element.beforecopyEvent')
   @DocsEditable
   static const EventStreamProvider<Event> beforeCopyEvent = const EventStreamProvider<Event>('beforecopy');
 
   @DomName('Element.beforecutEvent')
@@ skipping 15089 matching lines @@
       }
     }
     return s;
   }
 
   void writeClasses(Set<String> s) {
     List list = new List.from(s);
     _element.$dom_className = s.join(' ');
   }
 }
+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+
+class _ContentCssRect extends CssRect {
+
+  _ContentCssRect(element) : super(element);
+  int get height => _element.offsetHeight +
+      _addOrSubtractToBoxModel(CssRect._HEIGHT, 'content');
+
+  int get width => _element.offsetWidth +
+      _addOrSubtractToBoxModel(CssRect._WIDTH, 'content');
+
+  /**
+   * Set the height to `newHeight`.
+   *
+   * Values of newHeight that are less than zero are converted to effectively
+   * setting the height to 0. This is equivalent to the `height`
+   * function in jQuery and the calculated `height` css value, converted to an
+   * int in pixels.
+   */
+  void set height(Dimension newHeight) {
+    if (newHeight.value < 0) newHeight = new Dimension.px(0);
+    _element.style.height = newHeight.toString();
+  }
+
+  /**
+   * Set the current computed width in pixels of this element.
+   *
+   * This is equivalent to the `width` function in jQuery and the calculated
+   * `width` css value, converted to a dimensionless int in pixels.
+   */
+  void set width(Dimension newWidth) {
+    if (newWidth.value < 0) newWidth = new Dimension.px(0);
+    _element.style.width = newWidth.toString();
+  }
+
+  int get left() => _element.getBoundingClientRect().left -
+      _addOrSubtractToBoxModel(['left'], 'content');
+  int get top() => _element.getBoundingClientRect().top -
+      _addOrSubtractToBoxModel(['top'], 'content');
+}
+
+class _ContentCssListRect extends _ContentCssRect {
+  List<Element> _elementList;
+
+  _ContentCssListRect(elementList) : super(elementList.first) {
+    _elementList = elementList;
+  }
+
+  /**
+   * Set the height to `newHeight`.
+   *
+   * Values of newHeight that are less than zero are converted to effectively
+   * setting the height to 0. This is equivalent to the `height`
+   * function in jQuery and the calculated `height` css value, converted to an
+   * int in pixels.
+   */
+  void set height(Dimension newHeight) {
+    _elementList.forEach((e) => e.contentEdge.height = newHeight);
+  }
+
+  /**
+   * Set the current computed width in pixels of this element.
+   *
+   * This is equivalent to the `width` function in jQuery and the calculated
+   * `width` css value, converted to a dimensionless int in pixels.
+   */
+  void set width(Dimension newWidth) {
+    _elementList.forEach((e) => e.contentEdge.width = newWidth);
+  }
+}
+
+class _PaddingCssRect extends CssRect {
+  _PaddingCssRect(element) : super(element);
+  int get height => _element.offsetHeight +
+      _addOrSubtractToBoxModel(CssRect._HEIGHT, 'padding');
+  int get width => _element.offsetWidth +
+      _addOrSubtractToBoxModel(CssRect._WIDTH, 'padding');
+
+  int get left() => _element.getBoundingClientRect().left -
+      _addOrSubtractToBoxModel(['left'], 'padding');
+  int get top() => _element.getBoundingClientRect().top -
+      _addOrSubtractToBoxModel(['top'], 'padding');
+}
+
+class _BorderCssRect extends CssRect {
+  _BorderCssRect(element) : super(element);
+  int get height() => _element.offsetHeight;
+  int get width() => _element.offsetWidth;
+
+  int get left() => _element.getBoundingClientRect().left;
+  int get top() => _element.getBoundingClientRect().top;
+}
+
+class _MarginCssRect extends CssRect {
+  _MarginCssRect(element) : super(element);
+  int get height() => _element.offsetHeight +
+      _addOrSubtractToBoxModel(CssRect._HEIGHT, 'margin');
+  int get width() =>
+      _element.offsetWidth + _addOrSubtractToBoxModel(CssRect._WIDTH, 'margin');
+
+  int get left() => _element.getBoundingClientRect().left -
+      _addOrSubtractToBoxModel(['left'], 'margin');
+  int get top() => _element.getBoundingClientRect().top -
+      _addOrSubtractToBoxModel(['top'], 'margin');
+}
+
+/**
+ * A class for representing CSS dimensions.
+ *
+ * In contrast to the more general purpose [Rect] class, this class's values are

[blois, 2013/05/22 01:18:07]

Why not a mutable rect interface then?

+ * mutable, so one can change the height of an element programmatically.
+ *
+ * SPECIAL NOTE: Do _not_ use these methods of setting height for animations, as
+ * they will trigger a redraw of the layout. For deferred layout options, see
+ * the LayoutManager.
+ */
+abstract class CssRect extends RectBase implements Rect {
+  Element _element;
+
+  CssRect(this._element);
+
+  int get left();
+
+  int get top();
+
+  /**
+   * The height of this rectangle.
+   *
+   * This is equivalent to the `height` function in jQuery and the calculated
+   * `height` css value, converted to a dimensionless int in pixels. Unlike
+   * [getBoundingClientRect], `height` will return the same numerical width if
+   * the element is hidden or not.
+   */
+  int get height();
+
+  /**
+   * The width of this rectangle.
+   *
+   * This is equivalent to the `width` function in jQuery and the calculated
+   * `width` css value, converted to a dimensionless int in pixels. Unlike
+   * [getBoundingClientRect], `width` will return the same numerical width if
+   * the element is hidden or not.
+   */
+  int get width();
+
+  /**
+   * Set the height to `newHeight`.
+   *
+   * Values of newHeight that are less than zero are converted to effectively
+   * setting the height to 0. Note that only the content height can be set via
+   * this method.
+   */
+  void set height(Dimension newHeight) {
+    throw new UnsupportedError("Can only set height for content rect.");
+  }
+
+  /**
+   * Set the current computed width in pixels of this element.
+   *
+   * Note that only the content width can be set via this method.
+   */
+  void set width(Dimension newWidth) {
+    throw new UnsupportedError("Can only set width for content rect.");
+  }
+
+  /**
+   * Return a value that is used to modify the initial height or width
+   * measurement of an element. Depending on the value (ideally an enum) passed
+   * to augmentingMeasurement, we may need to add or subtract margin, padding,
+   * or border values, depending on the measurement we're trying to obtain.
+   */
+  int _addOrSubtractToBoxModel(List<String> dimensions,
+      String augmentingMeasurement) {
+    // getComputedStyle always returns pixel values (hence, computed), so we're
+    // always dealing with pixels in this method.
+    var styles = _element.getComputedStyle();
+
+    var val = 0;
+
+    for (String measurement in dimensions) {
+      // The border-box and default box model both exclude margin in the regular
+      // height/width calculation, so add it if we want it for this measurement.
+      if (augmentingMeasurement == "margin") {
+        val += new Dimension.css(styles.getPropertyValue(
+            '$augmentingMeasurement-$measurement')).value;
+      }
+
+      // The border-box includes padding and border, so remove it if we want
+      // just the content itself.
+      if (augmentingMeasurement == 'content') {
+        val -= new Dimension.css(
+            styles.getPropertyValue('padding-$measurement')).value;
+      }
+
+      // At this point, we don't wan't to augment with border or margin,
+      // so remove border.
+      if (augmentingMeasurement != 'margin') {
+              val -= new Dimension.css(styles.getPropertyValue(
+            'border-${measurement}-width')).value;
+      }
+    }
+    return val;
+  }
+
+  final static _HEIGHT = ['top', 'bottom'];
+  final static _WIDTH = ['right', 'left'];
+}
+
+/** Class representing a distance measurement in CSS. */
+class Dimension {
+  num _value;
+  String _unit;
+
+  /** Set this CSS Dimension to a percentage `value`. */
+  Dimension.percent(this._value) : _unit = '%';
+
+  /** Set this CSS Dimension to a pixel `value`. */
+  Dimension.px(this._value) : _unit = 'px';
+
+  /** Set this CSS Dimension to a pica `value`. */
+  Dimension.pc(this._value) : _unit = 'pc';
+
+  /** Set this CSS Dimension to a point `value`. */
+  Dimension.pt(this._value) : _unit = 'pt';
+
+  /** Set this CSS Dimension to an inch `value`. */
+  Dimension.inch(this._value) : _unit = 'in';
+
+  /** Set this CSS Dimension to a centimeter `value`. */
+  Dimension.cm(this._value) : _unit = 'cm';
+
+  /** Set this CSS Dimension to a millimeter `value`. */
+  Dimension.mm(this._value) : _unit = 'mm';
+
+  /**
+   * Set this CSS Dimension to the specified number of ems.
+   *
+   * 1em is equal to the current font size. (So 2ems is equal to double the font
+   * size). This is useful for producing website layouts that scale nicely with
+   * the user's desired font size.
+   */
+  Dimension.em(this._value) : _unit = 'em';
+
+  /**
+   * Set this CSS Dimension to the specified number of x-heights.
+   *
+   * One ex is equal to the the x-height of a font's baseline to its mean line,
+   * generally the height of the letter "x" in the font, which is usually about
+   * half the font-size.
+   */
+  Dimension.ex(this._value) : _unit = 'ex';
+
+  /** Construct a Dimension object from the valid CSS string `cssValue`. */
+  Dimension.css(String cssValue) {
+    if (cssValue == '') cssValue = '0px';
+    if (cssValue.endsWith('%')) {
+      _unit = '%';
+      _value = int.parse(cssValue.substring(0, cssValue.length-1));
+    } else {
+      _value = int.parse(cssValue.substring(0, cssValue.length - 2));
+      _unit = cssValue.substring(cssValue.length - 2);
+    }
+  }
+
+  /** Print out the CSS String representation of this value. */
+  String toString() {
+    return '${_value}${_unit}';
+  }
+
+  /** Return a unitless, numerical value of this CSS value. */
+  num get value => this._value;
+}
 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 
 typedef EventListener(Event event);
 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
@@ skipping 1589 matching lines @@
    * Indicates the document and all subresources have been loaded.
    */
   static const String COMPLETE = "complete";
 }
 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 
 /**
- * A class for representing two-dimensional rectangles.
+ * A base class for representing two-dimensional rectangles. This will hopefully
+ * be moved merged with the dart:math Rect.
  */
-class Rect {
-  final num left;
-  final num top;
-  final num width;
-  final num height;
-
-  const Rect(this.left, this.top, this.width, this.height);
-
-  factory Rect.fromPoints(Point a, Point b) {
-    var left;
-    var width;
-    if (a.x < b.x) {
-      left = a.x;
-      width = b.x - left;
-    } else {
-      left = b.x;
-      width = a.x - left;
-    }
-    var top;
-    var height;
-    if (a.y < b.y) {
-      top = a.y;
-      height = b.y - top;
-    } else {
-      top = b.y;
-      height = a.y - top;
-    }
-
-    return new Rect(left, top, width, height);
-  }
+// TODO(efortuna): Merge with Math rect after finalizing with Florian.
+abstract class RectBase {
+  num get left;
+  num get top;
+  num get width;
+  num get height;
 
   num get right => left + width;
   num get bottom => top + height;
 
   // NOTE! All code below should be common with Rect.
-  // TODO: implement with mixins when available.
 
   String toString() {
     return '($left, $top, $width, $height)';
   }
 
   bool operator ==(other) {
     if (other is !Rect) return false;
     return left == other.left && top == other.top && width == other.width &&
         height == other.height;
   }
@@ skipping 70 matching lines @@
    * Truncates coordinates to integers and returns the result as a new
    * rectangle.
    */
   Rect toInt() => new Rect(left.toInt(), top.toInt(), width.toInt(),
       height.toInt());
 
   Point get topLeft => new Point(this.left, this.top);
   Point get bottomRight => new Point(this.left + this.width,
       this.top + this.height);
 }
+
+
+
+/**
+ * A class for representing two-dimensional rectangles.
+ */
+class Rect extends RectBase {
+  final num left;
+  final num top;
+  final num width;
+  final num height;
+
+  const Rect(this.left, this.top, this.width, this.height);
+
+  factory Rect.fromPoints(Point a, Point b) {
+    var left;
+    var width;
+    if (a.x < b.x) {
+      left = a.x;
+      width = b.x - left;
+    } else {
+      left = b.x;
+      width = a.x - left;
+    }
+    var top;
+    var height;
+    if (a.y < b.y) {
+      top = a.y;
+      height = b.y - top;
+    } else {
+      top = b.y;
+      height = a.y - top;
+    }
+
+    return new Rect(left, top, width, height);
+  }
+}
 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 
 class _HttpRequestUtils {
 
   // Helper for factory HttpRequest.get
   static HttpRequest get(String url,
                             onComplete(HttpRequest request),
@@ skipping 1207 matching lines @@
       _position = nextPosition;
       return true;
     }
     _current = null;
     _position = _array.length;
     return false;
   }
 
   T get current => _current;
 }