Specs: the paint model where each node is responsible for its children

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 500 matching lines @@
          maximum: maxHeight,
        };
      }
   */
 
   void markAsLaidOut(); // sets this.node.needsLayout and this.node.descendantNeedsLayout to false
   virtual Dimensions layout(Number? width, Number? height);
     // call markAsLaidOut();
     // if width is null, set width to getIntrinsicWidth().value
     // if height is null, set width height getIntrinsicHeight().value
+    // call this.assumeDimensions(width, height);
     // call this.layoutChildren(width, height);
     // return { width: width, height: height }
     // - this should always call this.markAsLaidOut() to reset needsLayout
     // - the return value should include the final value for whichever of the width and height arguments
     //   that is null
     // - subclasses that want to make 'auto' values dependent on the children should override this
     //   entirely, rather than overriding layoutChildren
 
   virtual void layoutChildren(Number width, Number height);
     // default implementation does nothing
     // - override this if you want to lay out children but not have the children affect your dimensions
 
   void markAsPainted(); // sets this.node.needsPaint and this.node.descendantNeedsPaint to false
   virtual void paint(RenderingSurface canvas);
-    // set a clip rect on the canvas for rect(0,0,this.width,this.height)
-    // if needsPaint is true:
+    // if needsPaint:
+    //   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(canvas)
     // (the default implementation doesn't paint anything on top of the children)
     // unset the clip
     // call markAsPainted()
 
   virtual void paintChildren(RenderingSurface canvas);
-    // if descendantNeedsPaint is true:
+    // if this.needsPaint or this.descendantNeedsPaint:
     //   for each child returned by walkChildren():
-    //     if child.needsPaint or child.descendantNeedsPaint:
-    //       call this.paintChild(canvas, child)
+    //     call this.paintChild(canvas, child)
     // - you should skip children that will be clipped out of yourself because they're outside your bounds
 
   virtual void paintChild(RenderingSurface canvas, LayoutManager child);
-    // insert a "paint this child" instruction in our canvas instruction list (we should probably make sure we expose that API directly, too)
-    // start a new canvas for the child:
+    // if this.needsPaint():
+    //   insert a "paint this child" instruction in our canvas instruction list (we should probably make sure we expose that API directly, too)
+    // if child.needsPaint or child.descendantNeedsPaint:
+    //   start a new canvas for the child:
     //   transform the coordinate space by translate(child.x, child.y)
-    //   call child.paint(canvas)
+    //     call child.paint(canvas)
 
   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 86 matching lines @@
 ```javascript
 { 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).