Added offset document measurement to Element.

tools/dom/templates/html/impl/impl_Element.darttemplate

 // 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.
 
 part of $LIBRARYNAME;
 
 class _ChildrenElementList extends ListBase<Element> {
   // Raw Element.
   final Element _element;
   final HtmlCollection _childElements;
@@ skipping 1072 matching lines @@
    * can be used to retrieve jQuery's
    * [outerHeight](http://api.jquery.com/outerHeight/) value for an element.
    * 
    * _Important_ _note_: use of this method will perform CSS calculations that
    * can trigger a browser reflow. Therefore, use of this property _during_ an 
    * animation frame is discouraged. See also: 
    * [Browser Reflow](https://developers.google.com/speed/articles/reflow)
    */
   @Experimental()
   CssRect get marginEdge => new _MarginCssRect(this);
+
+  /** 
+   * Provides the coordinates of the element relative to the top of the 
+   * document. 
+   *
+   * This method is the Dart equivalent to jQuery's 
+   * [offset](http://api.jquery.com/offset/) method.
+   */
+  Point get docOffset => offsetTo(document.documentElement);

[Jennifer Messerly, 2013/07/24 23:26:23]

personally, I would call this "documentOffset". That name seems more consistent
with the existing DOM APIs (e.g. documentElement)

[Emily Fortuna, 2013/07/25 00:20:07]

Done.

+
+  /** 
+   * Provides the offset of this element's [borderEdge] relative to the
+   * specified [parent].
+   * 
+   * This is the Dart equivalent of jQuery's
+   * [position](http://api.jquery.com/position/) method. Unlike jQuery's
+   * position, however, [parent] can be any parent element of `this`, 
+   * rather than only `this`'s immediate offsetParent. If the specified element
+   * is _not_ an offset parent or transitive offset parent to this element,
+   * an ArgumentError is thrown.

[Jennifer Messerly, 2013/07/24 23:26:23]

could use code links for [ArgumentError] and [offsetParent]

[Emily Fortuna, 2013/07/25 00:20:07]

Done.

+   */
+  Point offsetTo(Element parent) {
+    return _offsetToHelper(this, 
+        parent, parent == this || parent.tagName == 'HTML');

[Jennifer Messerly, 2013/07/24 23:26:23]

can we remove this extra arg? suggestion below.

[Jennifer Messerly, 2013/07/24 23:26:23]

use "identical(parent, this)"? one thing to watch out for with CustomElements...
once we can "extend Element", we might be able to override equals :)

+  }
+
+  Point _offsetToHelper(Element current, Element parent, bool foundAsParent) {

[Jennifer Messerly, 2013/07/24 23:26:23]

can this be static?

[Emily Fortuna, 2013/07/25 00:20:07]

Done.

+    if (current == null || current == parent) {

[Jennifer Messerly, 2013/07/24 23:26:23]

can we remove "foundAsParent"? it seems to duplicate what this is already
checking.

it seems like this is equivalent:

Point _offsetToHelper(Element current, Element parent) {
  bool foundAsParent = identical(current, parent) || parent.tagName == 'HTML';
  if (current == null || identical(current, parent)) {
    if (foundAsParent) return new Point(0, 0);
    throw new ArgumentError(...);
  }
  ...
}

there's probably a little more refactoring there; it seems like the
ArgumentError can only be thrown if (current == null && parent.tagName !=
'HTML')

I'm not quite clear what the special case is for tagname HTML--is it basically
saying that even if the node isn't attached to the document, we'll pretend it is
for the purpose of "offsetTo"? Might be good to add that to the comment.

[Emily Fortuna, 2013/07/25 00:20:07]

HTML discussed offline and added comment. and refactored!

+      return foundAsParent? new Point(0, 0) : throw new ArgumentError(

[Jennifer Messerly, 2013/07/24 23:26:23]

this might be cleaner as:

if (foundAsParent) return new Point(0, 0);
throw new ArgumentError( ... );

[Emily Fortuna, 2013/07/25 00:20:07]

Done.

+          "Specified element is not a transitive offset parent of this "
+          "element.");
+    } 
+    Element parentOffset = current.offsetParent;
+    Point p = _offsetToHelper(
+        parentOffset, parent, foundAsParent || parentOffset == parent);
+    return new Point(p.x + current.offsetLeft, p.y + current.offsetTop);
+  }
 $!MEMBERS
 }
 
 
 final _START_TAG_REGEXP = new RegExp('<(\\w+)');
 class _ElementFactoryProvider {
   static const _CUSTOM_PARENT_TAG_MAP = const {
     'body' : 'html',
     'head' : 'html',
     'caption' : 'table',
@@ skipping 127 matching lines @@
   const ScrollAlignment._internal(this._value);
   toString() => 'ScrollAlignment.$_value';
 
   /// Attempt to align the element to the top of the scrollable area.
   static const TOP = const ScrollAlignment._internal('TOP');
   /// Attempt to center the element in the scrollable area.
   static const CENTER = const ScrollAlignment._internal('CENTER');
   /// Attempt to align the element to the bottom of the scrollable area.
   static const BOTTOM = const ScrollAlignment._internal('BOTTOM');
 }