Specs: lay groundwork for scrolling widget

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 325 matching lines @@
        // otherwise, get the default value; cache it; return it
 
     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
+      // needsPaint is set to false by the ownerLayoutManager's default paint() method
 
     // only the ownerLayoutManager can change these
     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
@@ skipping 72 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);
+    void markAsPainted(); // sets this.node.needsPaint to false
+    virtual void paint(RenderingSurface 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
+      // call markAsPainted()
 
     virtual void paintChildren(RenderingSurface canvas);
       // just calls paint() for each child returned by walkChildren() whose needsPaint is true,
       // after transforming the coordinate space by translate(child.x,child.y)
+      // you should skip children that will be clipped out of yourself because they're outside your bounds
 
     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)
@@ skipping 71 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).