even more documentation

2025-09-18 09:50:05 +08:00 · 2013-05-18 22:30:57 -07:00
parent 2ea5f83204
commit 056346c14d
8 changed files with 133 additions and 40 deletions
--- a/src/Animation.js
+++ b/src/Animation.js
@@ -3,8 +3,23 @@
     * Animation constructor.  A stage is used to contain multiple layers and handle
     * @constructor
     * @memberof Kinetic
-     * @param {Function} func function executed on each animation frame
-     * @param {Kinetic.Layer|Array} [layers] layer(s) to be redrawn.&nbsp; Can be a layer, an array of layers, or null.  Not specifying a node will result in no redraw.
+     * @param {Function} func function executed on each animation frame.  The function is passed a frame object, which contains
+     *  timeDiff, lastTime, time, and frameRate properties.  The timeDiff property is the number of milliseconds that have passed
+     *  since the last animation frame.  The lastTime property is time in milliseconds that elapsed from the moment the animation started
+     *  to the last animation frame.  The time property is the time in milliseconds that ellapsed from the moment the animation started
+     *  to the current animation frame.  The frameRate property is the current frame rate in frames / second
+     * @param {Kinetic.Layer|Array} [layers] layer(s) to be redrawn on each animation frame. Can be a layer, an array of layers, or null.  
+     *  Not specifying a node will result in no redraw.
+     * @example
+     * // move a node to the right at 50 pixels / second<br>
+     * var velocity = 50;<br><br>
+     *
+     * var anim = new Kinetic.Animation(function(frame) {<br>
+     *   var dist = velocity * (frame.timeDiff / 1000);<br>
+     *   node.move(dist, 0);<br>
+     * }, layer);<br><br>
+     *
+     * anim.start();
     */
    Kinetic.Animation = function(func, layers) {
        this.func = func;
--- a/src/Tween.js
+++ b/src/Tween.js
@@ -30,7 +30,7 @@
     *   node: node,<br>
     *   rotationDeg: 360,<br>
     *   duration: 1,<br>
-     *   Kinetic.Easings.EaseInOut<br>   
+     *   easing: Kinetic.Easings.EaseInOut<br>   
     * });<br><br>
     * 
     * // play tween<br>
--- a/src/plugins/Label.js
+++ b/src/plugins/Label.js
@@ -13,7 +13,7 @@
     attrChangeListLen = ATTR_CHANGE_LIST.length;
        
    /**
-     * Label constructor.&nbsp; Labels are groups that contain Text and LabelRect shape 
+     * Label constructor.&nbsp; Labels are groups that contain a Text and Tag shape 
     * @constructor
     * @memberof Kinetic
     * @param {Object} config
@@ -25,13 +25,53 @@
     * @param {String} [config.text.align] can be left, center, or right
     * @param {Number} [config.text.padding]
     * @param {Number} [config.text.lineHeight] default is 1
-     * @param {Object} [config.rect] LabelRect config
-     * @param {String} [config.rect.pointerDirection] can be up, right, down, left, or none; the default
+     * @param {Object} [config.tag] Tag config
+     * @param {String} [config.tag.pointerDirection] can be up, right, down, left, or none; the default
     *  is none.  When a pointer is present, the positioning of the label is relative to the tip of the pointer.
-     * @param {Number} [config.rect.pointerWidth]
-     * @param {Number} [config.rect.pointerHeight]
-     * @param {Number} [config.rect.cornerRadius] 
+     * @param {Number} [config.tag.pointerWidth]
+     * @param {Number} [config.tag.pointerHeight]
+     * @param {Number} [config.tag.cornerRadius] 
     * {{NodeParams}}
+     * @example
+     * var label = new Kinetic.Label({<br>
+     *   x: 350,<br>
+     *   y: 50,<br>
+     *   opacity: 0.75,<br>
+     *   text: {<br>
+     *     text: 'Simple label',<br>
+     *     fontFamily: 'Calibri',<br>
+     *     fontSize: 18,<br>
+     *     padding: 5,<br>
+     *     fill: 'black'<br>
+     *   },<br>
+     *   tag: {<br>
+     *     fill: 'yellow',<br>
+     *   }<br>
+     * });<br><br>
+     *
+     * var tooltip = new Kinetic.Label({<br>
+     *   x: 170,<br>
+     *   y: 75,<br>
+     *   opacity: 0.75,<br>
+     *   text: {<br>
+     *     text: 'Tooltip pointing down',<br>
+     *     fontFamily: 'Calibri',<br>
+     *     fontSize: 18,<br>
+     *     padding: 5,<br>
+     *     fill: 'white'<br>
+     *   },<br>
+     *   tag: {<br>
+     *     fill: 'black',<br>
+     *     pointerDirection: 'down',<br>
+     *     pointerWidth: 10,<br>
+     *     pointerHeight: 10,<br>
+     *     lineJoin: 'round',<br>
+     *     shadowColor: 'black',<br>
+     *     shadowBlur: 10,<br>
+     *     shadowOffset: 10,<br>
+     *     shadowOpacity: 0.5<br>
+     *   }<br>
+     * });
     */
    Kinetic.Label = function(config) {
        this._initLabel(config);
@@ -48,8 +88,8 @@
            Kinetic.Group.call(this, config);
            text = new Kinetic.Text(config.text);
            this.setText(text);
-            this.setRect(new Kinetic.LabelRect(config.rect));
-            this.innerGroup.add(this.getRect());
+            this.setTag(new Kinetic.Tag(config.tag));
+            this.innerGroup.add(this.getTag());
            this.innerGroup.add(text); 
            this.add(this.innerGroup);   
            
@@ -72,10 +112,10 @@
            var text = this.getText(),
                width = text.getWidth(),
                height = text.getHeight(),
-                rect = this.getRect(),
-                pointerDirection = rect.getPointerDirection(),
-                pointerWidth = rect.getPointerWidth(),
-                pointerHeight = rect.getPointerHeight(),
+                tag = this.getTag(),
+                pointerDirection = tag.getPointerDirection(),
+                pointerWidth = tag.getPointerWidth(),
+                pointerHeight = tag.getPointerHeight(),
                x = 0, 
                y = 0;
            
@@ -117,23 +157,21 @@
     * @memberof Kinetic.Label.prototype
     */

-    Kinetic.Node.addGetterSetter(Kinetic.Label, 'rect');
+    Kinetic.Node.addGetterSetter(Kinetic.Label, 'tag');
       
    /**
-     * get LabelRect shape for the label.  You need to access the LabelRect shape in order to update
+     * get Tag shape for the label.  You need to access the Tag shape in order to update
     * the pointer properties and the corner radius
-     * @name getRect
+     * @name getTag
     * @method
     * @memberof Kinetic.Label.prototype
     */

-
    /**
-     * LabelRect constructor.&nbsp; A LabelRect is similar to a Rect, except that it can be configured
+     * Tag constructor.&nbsp; A Tag can be configured
     *  to have a pointer element that points up, right, down, or left 
     * @constructor
     * @memberof Kinetic
-     * @abstract
     * @param {Object} config
     * @param {String} [config.pointerDirection] can be up, right, down, left, or none; the default
     *  is none.  When a pointer is present, the positioning of the label is relative to the tip of the pointer.
@@ -141,15 +179,15 @@
     * @param {Number} [config.pointerHeight]
     * @param {Number} [config.cornerRadius] 
     */ 
-    Kinetic.LabelRect = function(config) {
-        this._initLabelRect(config);
+    Kinetic.Tag = function(config) {
+        this._initTag(config);
    };

-    Kinetic.LabelRect.prototype = {
-        _initLabelRect: function(config) {
+    Kinetic.Tag.prototype = {
+        _initTag: function(config) {
            this.createAttrs();
            Kinetic.Shape.call(this, config);
-            this.shapeType = 'LabelRect';
+            this.shapeType = 'Tag';
            this._setDrawFuncs();
        },
        drawFunc: function(canvas) {
@@ -200,14 +238,14 @@
        }
    };
    
-    Kinetic.Util.extend(Kinetic.LabelRect, Kinetic.Shape);
-    Kinetic.Node.addGetterSetter(Kinetic.LabelRect, 'pointerDirection', NONE);
+    Kinetic.Util.extend(Kinetic.Tag, Kinetic.Shape);
+    Kinetic.Node.addGetterSetter(Kinetic.Tag, 'pointerDirection', NONE);

    /**
     * set pointer Direction
     * @name setPointerDirection
     * @method
-     * @memberof Kinetic.LabelRect.prototype
+     * @memberof Kinetic.Tag.prototype
     * @param {String} pointerDirection can be up, right, down, left, or none.  The
     *  default is none 
     */
@@ -216,16 +254,16 @@
     * get pointer Direction
     * @name getPointerDirection
     * @method
-     * @memberof Kinetic.LabelRect.prototype
+     * @memberof Kinetic.Tag.prototype
     */

-    Kinetic.Node.addGetterSetter(Kinetic.LabelRect, 'pointerWidth', 0);
+    Kinetic.Node.addGetterSetter(Kinetic.Tag, 'pointerWidth', 0);

    /**
     * set pointer width 
     * @name setPointerWidth
     * @method
-     * @memberof Kinetic.LabelRect.prototype
+     * @memberof Kinetic.Tag.prototype
     * @param {Number} pointerWidth 
     */

@@ -233,16 +271,16 @@
     * get pointer width 
     * @name getPointerWidth
     * @method
-     * @memberof Kinetic.LabelRect.prototype
+     * @memberof Kinetic.Tag.prototype
     */

-    Kinetic.Node.addGetterSetter(Kinetic.LabelRect, 'pointerHeight', 0);
+    Kinetic.Node.addGetterSetter(Kinetic.Tag, 'pointerHeight', 0);

    /**
     * set pointer height 
     * @name setPointerHeight
     * @method
-     * @memberof Kinetic.LabelRect.prototype
+     * @memberof Kinetic.Tag.prototype
     * @param {Number} pointerHeight
     */

@@ -250,16 +288,16 @@
     * get pointer height 
     * @name getPointerHeight
     * @method
-     * @memberof Kinetic.LabelRect.prototype
+     * @memberof Kinetic.Tag.prototype
     */

-    Kinetic.Node.addGetterSetter(Kinetic.LabelRect, 'cornerRadius', 0);
+    Kinetic.Node.addGetterSetter(Kinetic.Tag, 'cornerRadius', 0);

    /**
     * set corner radius
     * @name setCornerRadius
     * @method
-     * @memberof Kinetic.LabelRect.prototype
+     * @memberof Kinetic.Tag.prototype
     * @param {Number} corner radius
     */

@@ -267,6 +305,6 @@
     * get corner radius
     * @name getCornerRadius
     * @method
-     * @memberof Kinetic.LabelRect.prototype
+     * @memberof Kinetic.Tag.prototype
     */
 })();
--- a/src/plugins/Path.js
+++ b/src/plugins/Path.js
@@ -9,6 +9,14 @@
     * @param {String} config.data SVG data string
     * {{ShapeParams}}
     * {{NodeParams}}
+     * @example
+     * var path = new Kinetic.Path({<br>
+     *   x: 240,<br>
+     *   y: 40,<br>
+     *   data: 'M12.582,9.551C3.251,16.237,0.921,29.021,7.08,38.564l-2.36,1.689l4.893,2.262l4.893,2.262l-0.568-5.36l-0.567-5.359l-2.365,1.694c-4.657-7.375-2.83-17.185,4.352-22.33c7.451-5.338,17.817-3.625,23.156,3.824c5.337,7.449,3.625,17.813-3.821,23.152l2.857,3.988c9.617-6.893,11.827-20.277,4.935-29.896C35.591,4.87,22.204,2.658,12.582,9.551z',<br>
+     *   fill: 'green',<br>
+     *   scale: 2<br>
+     * });
     */
    Kinetic.Path = function(config) {
        this._initPath(config);
--- a/src/plugins/RegularPolygon.js
+++ b/src/plugins/RegularPolygon.js
@@ -9,6 +9,16 @@
     * @param {Number} config.radius
     * {{ShapeParams}}
     * {{NodeParams}}
+     * @example
+     * var hexagon = new Kinetic.RegularPolygon({<br>
+     *   x: 100,<br>
+     *   y: 200,<br>
+     *   sides: 6,<br>
+     *   radius: 70,<br>
+     *   fill: 'red',<br>
+     *   stroke: 'black',<br>
+     *   strokeWidth: 4<br>
+     * });
     */
    Kinetic.RegularPolygon = function(config) {
        this._initRegularPolygon(config);
--- a/src/plugins/Star.js
+++ b/src/plugins/Star.js
@@ -10,6 +10,17 @@
     * @param {Number} config.outerRadius
     * {{ShapeParams}}
     * {{NodeParams}}
+     * @example
+     * var star = new Kinetic.Star({<br>
+     *   x: 100,<br>
+     *   y: 200,<br>
+     *   numPoints: 5,<br>
+     *   innerRadius: 70,<br>
+     *   outerRadius: 70,<br>
+     *   fill: 'red',<br>
+     *   stroke: 'black',<br>
+     *   strokeWidth: 4<br>
+     * });
     */
    Kinetic.Star = function(config) {
        this._initStar(config);
--- a/src/plugins/TextPath.js
+++ b/src/plugins/TextPath.js
@@ -14,8 +14,19 @@
     * @param {Number} [config.fontSize] default is 12
     * @param {String} [config.fontStyle] can be normal, bold, or italic.  Default is normal
     * @param {String} config.text
+     * @param {String} config.data SVG data string
     * {{ShapeParams}}
     * {{NodeParams}}
+     * @example
+     * var textpath = new Kinetic.TextPath({<br>
+     *   x: 100,<br>
+     *   y: 50,<br>
+     *   fill: '#333',<br>
+     *   fontSize: '24',<br>
+     *   fontFamily: 'Arial',<br>
+     *   text: 'All the world\'s a stage, and all the men and women merely players.',<br>
+     *   data: 'M10,10 C0,0 10,150 100,100 S300,150 400,50'<br>
+     * });
     */
    Kinetic.TextPath = function(config) {
        this._initTextPath(config);
--- a/tests/js/unit/plugins/labelTests.js
+++ b/tests/js/unit/plugins/labelTests.js
@@ -20,7 +20,7 @@ Test.Modules.LABEL = {
                //padding: 10,
                fill: 'green'
            }, 
-            rect: {
+            tag: {
                fill: '#bbb',
                stroke: '#333',
                shadowColor: 'black',