Specs: make sure all layout/paint/hitTest APIs are relative to the right coordinate space

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 327 matching lines @@
     readonly attribute Boolean needsLayout; // means that a property with needsLayout:true has changed on this node or one of its descendants
     readonly attribute LayoutManager layoutManager;
 
     readonly attribute LayoutManager ownerLayoutManager; // defaults to the parentNode.layoutManager
       // if you are not the ownerLayoutManager, then ignore this StyleNode in layout() and paintChildren()
       // using walkChildren() does this for you
 
     readonly attribute Boolean needsPaint; // means that either needsLayout is true or a property with needsPaint:true has changed on this node or one of its descendants
 
     // only the ownerLayoutManager can change these
-    readonly attribute Float x;
-    readonly attribute Float y;
+    readonly attribute Float x; // relative to left edge of ownerLayoutManager
+    readonly attribute Float y; // relative to top edge of ownerLayoutManager
     readonly attribute Float width;
     readonly attribute Float height;
   }
 
 The flattened tree is represented as a hierarchy of Node objects. For
 any element that only contains text node children, the "text" property
 is set accordingly. For elements with mixed text node and non-text
 node children, each run of text nodes is represented as a separate
 Node with the "text" property set accordingly and the styles set as if
 the Node inherited everything inheritable from its parent.
@@ skipping 69 matching lines @@
     virtual LayoutValueRange getIntrinsicHeight(Float? defaultHeight = null);
       // returns min-height, height, and max-height, normalised, defaulting to values given in LayoutValueRange
       // if argument is provided, it overrides height
 
     virtual Dimensions layout(Number? width, Number? height);
       // returns { }
       // the return value should include the final value for whichever of the width and height arguments that is null
       // TODO(ianh): should we just grab the width and height from assumeDimensions()?
 
     void paint(RenderingSurface canvas);
-      // set a clip rect on the canvas
+      // set a clip rect on the canvas for rect(0,0,this.width,this.height)
       // call the painter of each property, in order they were registered, which on this element has a painter
       // call this.paintChildren()
       // unset the clip
 
     virtual void paintChildren(RenderingSurface canvas);
-      // just calls paint() for each child returned by walkChildren() whose needsPaint is true
+      // just calls paint() for each child returned by walkChildren() whose needsPaint is true,
+      // after transforming the coordinate space by translate(child.x,child.y)
 
     virtual Node hitTest(Float x, Float y);
       // default implementation uses the node's children nodes' x, y,
       // width, and height, skipping any that have width=0 or height=0, or
       // whose ownerLayoutManager is not |this|
       // default implementation walks the tree backwards from its built-in order
       // if no child is hit, then return this.node
       // override this if you changed your children's z-order, or if you used take() to
       // hoist some descendants up to be your responsibility, or if your children aren't
       // rectangular (e.g. you lay them out in a hex grid)
+      // make sure to offset the value you pass your children: child.layoutManager.hitTest(x-child.x, y-child.y)
 
   }
 
   dictionary LayoutValueRange {
     // negative values here should be treated as zero
     Float minimum = 0;
     Float value = 0; // ideal desired width; if it's not in the range minimum .. maximum then it overrides minimum and maximum
     (Float or Infinity) maximum = Infinity; 
   }
 
@@ skipping 13 matching lines @@
 
 Paint
 -----
 
   callback void Painter (StyleNode node, RenderingSurface canvas);
 
   class RenderingSurface {
     // ...
   }
 
+The convention is that the layout manager who calls your paint will
+have transformed the coordinate space so that you should assume that
+your top-left pixel is at 0,0.
+
 
 Default Styles
 --------------
 
 In the constructors for the default elements, they add to themselves
 StyleDeclaration objects as follows:
 
 * ``import``
 * ``template``
 * ``style``
@@ skipping 23 matching lines @@
 * ``error``
   This adds to itself the declaration with value:
   ``{ display: { value: sky.ErrorLayoutManager } }``
 
 The ``div`` element doesn't have any default styles.
 
 These declarations are all shared between all the elements (so e.g. if
 you reach in and change the declaration that was added to a ``title``
 element, you're going to change the styles of all the other
 default-hidden elements).