Specs: hit testing (and some cleanup)

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 392 matching lines @@
     void setChildY(child, y); // sets child.y
     void setChildSize(child, width, height); // sets child.width, child.height
     void setChildWidth(child, width); // sets child.width
     void setChildHeight(child, height); // sets child.height
       // these set needsPaint on the node and on any node impacted by this (?)
       // for setChildSize/Width/Height: if the new dimension is different than the last assumed dimensions, and
       // any StyleNodes with an ownerLayoutManager==this have cached values for getProperty() that are marked
       // as provisional, clear them
 
     Generator<StyleNode> walkChildren();
-      // returns a generator that iterates over the children, skipping any whose ownerLayoutManager is not this
+      // returns a generator that iterates over the children, skipping any whose ownerLayoutManager is not |this|
 
-    void paint(RenderingSurface canvas);
-      // set a clip rect on the canvas
-      // 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
+    Generator<StyleNode> walkChildrenBackwards();
+      // returns a generator that iterates over the children backwards, skipping any whose ownerLayoutManager is not |this|
 
     void assumeDimensions(Float width, Float height);
       // sets the assumed dimensions for calls to getProperty() on StyleNodes that have this as an ownerLayoutManager
       // if the new dimension is different than the last assumed dimensions, and any StyleNodes with an
       // ownerLayoutManager==this have cached values for getProperty() that are marked as provisional, clear them
       // TODO(ianh): should we force this to match the input to layout(), when called from inside layout() and when
       // layout() has a forced width and/or height?
 
     virtual LayoutValueRange getIntrinsicWidth(Float? defaultWidth = null);
       // returns min-width, width, and max-width, normalised, defaulting to values given in LayoutValueRange
       // if argument is provided, it overrides width
 
     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
+      // 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
+
+    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)
+
   }
 
   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; 
   }
 
   dictionary Dimensions {
@@ skipping 55 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).