Adds API documentation for SkyGames

sky/examples/game/lib/sprite_box.dart

Index: sky/examples/game/lib/sprite_box.dart
diff --git a/sky/examples/game/lib/sprite_box.dart b/sky/examples/game/lib/sprite_box.dart
index 131c4d01fad6b7ff92580b5b55e6044827f5b5f5..173b1d894de0eed2c9f5819812105858640e56e5 100644
--- a/sky/examples/game/lib/sprite_box.dart
+++ b/sky/examples/game/lib/sprite_box.dart
@@ -1,5 +1,17 @@
 part of sprites;
 
+/// Options for setting up a [SpriteBox].
+///
+///  * [nativePoints], use the same points as the parent [Widget].
+///  * [letterbox], use the size of the root node for the coordinate system, constrain the aspect ratio and trim off
+///  areas that end up outside the screen.
+///  * [stretch], use the size of the root node for the coordinate system, scale it to fit the size of the box.
+///  * [scaleToFit], similar to the letterbox option, but instead of trimming areas the sprite system will be scaled
+///  down to fit the box.
+///  * [fixedWidth], uses the width of the root node to set the size of the coordinate system, this option will change
+///  the height of the root node to fit the box.
+///  * [fixedHeight], uses the height of the root node to set the size of the coordinate system, this option will change
+///  the width of the root node to fit the box.
 enum SpriteBoxTransformMode {
   nativePoints,
   letterbox,
@@ -22,9 +34,10 @@ class SpriteBox extends RenderBox {
   double _frameRate = 0.0;
 
   // Transformation mode
-  SpriteBoxTransformMode transformMode;
-//  double _systemWidth;
-//  double _systemHeight;
+  SpriteBoxTransformMode _transformMode;
+
+  /// The transform mode used by the [SpriteBox].
+  SpriteBoxTransformMode get transformMode => _transformMode;
 
   // Cached transformation matrix
   Matrix4 _transformMatrix;
@@ -33,7 +46,14 @@ class SpriteBox extends RenderBox {
 
   // Setup
 
-  SpriteBox(NodeWithSize rootNode, [SpriteBoxTransformMode mode = SpriteBoxTransformMode.nativePoints]) {
+  /// Creates a new SpriteBox with a node as its content, by default uses letterboxing.
+  ///
+  /// The [rootNode] provides the content of the node tree, typically it's a custom subclass of [NodeWithSize]. The
+  /// [mode] provides different ways to scale the content to best fit it to the screen. In most cases it's preferred to
+  /// use a [SpriteWidget] that automatically wraps the SpriteBox.
+  ///
+  ///     var spriteBox = new SpriteBox(myNode, SpriteBoxTransformMode.fixedHeight);
+  SpriteBox(NodeWithSize rootNode, [SpriteBoxTransformMode mode = SpriteBoxTransformMode.letterbox]) {
     assert(rootNode != null);
     assert(rootNode._spriteBox == null);
 
@@ -44,9 +64,7 @@ class SpriteBox extends RenderBox {
     _addSpriteBoxReference(_rootNode);
 
     // Setup transform mode
-    transformMode = mode;
-//    _systemWidth = rootNode.size.width;
-//    _systemHeight = rootNode.size.height;
+    _transformMode = mode;
 
     _scheduleTick();
   }
@@ -60,9 +78,9 @@ class SpriteBox extends RenderBox {
 
   // Properties
 
-  double get systemWidth => rootNode.size.width;
-  double get systemHeight => rootNode.size.height;
-
+  /// The root node of the node tree that is rendered by this box.
+  ///
+  ///     var rootNode = mySpriteBox.rootNode;
   NodeWithSize get rootNode => _rootNode;
 
   void performLayout() {
@@ -98,7 +116,7 @@ class SpriteBox extends RenderBox {
     }
   }
 
-  void handleEvent(Event event, SpriteBoxHitTestEntry entry) {
+  void handleEvent(Event event, _SpriteBoxHitTestEntry entry) {
     if (event is PointerEvent) {
 
       if (event.type == 'pointerdown') {
@@ -148,12 +166,17 @@ class SpriteBox extends RenderBox {
   }
 
   bool hitTest(HitTestResult result, { Point position }) {
-    result.add(new SpriteBoxHitTestEntry(this, position));
+    result.add(new _SpriteBoxHitTestEntry(this, position));
     return true;
   }
 
   // Rendering
 
+  /// The transformation matrix used to transform the root node to the space of the box.
+  ///
+  /// It's uncommon to need access to this property.
+  ///
+  ///     var matrix = mySpriteBox.transformMatrix;
   Matrix4 get transformMatrix {
     // Get cached matrix if available
     if (_transformMatrix != null) {
@@ -171,7 +194,7 @@ class SpriteBox extends RenderBox {
     double systemWidth = rootNode.size.width;
     double systemHeight = rootNode.size.height;
 
-    switch(transformMode) {
+    switch(_transformMode) {
       case SpriteBoxTransformMode.stretch:
         scaleX = size.width/systemWidth;
         scaleY = size.height/systemHeight;
@@ -287,6 +310,12 @@ class SpriteBox extends RenderBox {
 
   // Hit tests
 
+  /// Finds all nodes at a position defined in the box's coordinates.
+  ///
+  /// Use this method with caution. It searches the complete node tree to locate the nodes, which can be slow if the
+  /// node tree is large.
+  ///
+  ///     List nodes = mySpriteBox.findNodesAtPosition(new Point(50.0, 50.0));
   List<Node> findNodesAtPosition(Point position) {
     assert(position != null);
 
@@ -311,15 +340,44 @@ class SpriteBox extends RenderBox {
   }
 }
 
-class SpriteBoxHitTestEntry extends BoxHitTestEntry {
+class _SpriteBoxHitTestEntry extends BoxHitTestEntry {
   List<Node> nodeTargets;
-  SpriteBoxHitTestEntry(RenderBox target, Point localPosition) : super(target, localPosition);
+  _SpriteBoxHitTestEntry(RenderBox target, Point localPosition) : super(target, localPosition);
 }
 
+/// An event that is passed down the node tree when pointer events occur. The SpriteBoxEvent is typically handled in
+/// the handleEvent method of [Node].
 class SpriteBoxEvent {
-  Point boxPosition;
-  String type;
-  int pointer;
 
+  /// The position of the event in box coordinates.
+  ///
+  /// You can use the convertPointToNodeSpace of [Node] to convert the position to local coordinates.
+  ///
+  ///     bool handleEvent(SpriteBoxEvent event) {
+  ///       Point localPosition = convertPointToNodeSpace(event.boxPosition);
+  ///       if (event.type == 'pointerdown') {
+  ///         // Do something!
+  ///       }
+  ///     }
+  final Point boxPosition;
+
+  /// The type of event, there are currently four valid types, 'pointerdown', 'pointermoved', 'pointerup', and
+  /// 'pointercancel'.
+  ///
+  ///     if (event.type == 'pointerdown') {
+  ///       // Do something!
+  ///     }
+  final String type;
+
+  /// The id of the pointer. Each pointer on the screen will have a unique pointer id.
+  ///
+  ///     if (event.pointer == firstPointerId) {
+  ///       // Do something
+  ///     }
+  final int pointer;
+
+  /// Creates a new SpriteBoxEvent, typically this is done internally inside the SpriteBox.
+  ///
+  ///     var event = new SpriteBoxEvent(new Point(50.0, 50.0), 'pointerdown', 0);
   SpriteBoxEvent(this.boxPosition, this.type, this.pointer);
 }