updated overloaded docs for d&d, node, shape, stage, sprite, text, and wedge

2025-12-17 18:01:15 +08:00 · 2014-01-07 23:56:49 -08:00
parent 4d8ee45f71
commit fc8273e792
9 changed files with 129 additions and 174 deletions
--- a/src/DragAndDrop.js
+++ b/src/DragAndDrop.js
@@ -120,12 +120,6 @@
        dd._endDragAfter(evt);
    };

-    /**
-     * set draggable
-     * @method
-     * @memberof Kinetic.Node.prototype
-     * @param {String} draggable
-     */
    Kinetic.Node.prototype.setDraggable = function(draggable) {
        this._setAttr('draggable', draggable);
        this._dragChange();
@@ -232,23 +226,26 @@
     */

    Kinetic.Factory.addGetter(Kinetic.Node, 'draggable', false);
+    Kinetic.Factory.addOverloadedGetterSetter(Kinetic.Node, 'draggable');

     /**
-     * get draggable
-     * @name getDraggable
+     * get/set draggable flag
+     * @name draggable
     * @method
     * @memberof Kinetic.Node.prototype
+     * @param {Boolean} draggable
+     * @returns {Boolean}
+     * @example
+     * // get draggable flag
+     * var draggable = node.draggable();
+     *
+     * // enable drag and drop
+     * node.draggable(true);
+     *
+     * // disable drag and drop
+     * node.draggable(false);
     */

-    /**
-     * alias of getDraggable()
-     * @name isDraggable
-     * @method
-     * @memberof Kinetic.Node.prototype
-     */
-
-    Kinetic.Node.prototype.isDraggable = Kinetic.Node.prototype.getDraggable;
-
    var html = document.documentElement;
    html.addEventListener('mouseup', Kinetic.DD._endDragBefore, true);
    html.addEventListener('touchend', Kinetic.DD._endDragBefore, true);
--- a/src/Node.js
+++ b/src/Node.js
@@ -255,13 +255,6 @@
            context.drawImage(hitCanvas._canvas, 0, 0); 
            context.restore(); 
        },
-        /*
-         * the default isDraggable method returns false.
-         * if the DragAndDrop module is included, this is overwritten
-         */
-        isDraggable: function() {
-            return false;
-        },
        /**
         * bind events to the node. KineticJS supports mouseover, mousemove,
         *  mouseout, mouseenter, mouseleave, mousedown, mouseup, click, dblclick, touchstart, touchmove,
--- a/src/Shape.js
+++ b/src/Shape.js
@@ -240,7 +240,7 @@

            hitContext.clear();

-            //try {
+            try {
                sceneImageData = sceneContext.getImageData(0, 0, width, height);
                sceneData = sceneImageData.data;
                hitImageData = hitContext.getImageData(0, 0, width, height);
@@ -260,10 +260,10 @@
                }

                hitContext.putImageData(hitImageData, 0, 0);
-            // }
-            // catch(e) {
-            //     Kinetic.Util.warn('Unable to draw hit graph from cached scene canvas. ' + e.message);
-            // }
+            }
+            catch(e) {
+                Kinetic.Util.warn('Unable to draw hit graph from cached scene canvas. ' + e.message);
+            }

            return this;
        },
--- a/src/Stage.js
+++ b/src/Stage.js
@@ -659,7 +659,12 @@
     * @returns {DomElement} container
     * @example
     * // get container<br>
-     * var container = stage.container();
+     * var container = stage.container();<br><br>
+     * 
+     * // set container<br>
+     * var container = document.createElement('div');<br>
+     * body.appendChild(container);<br>
+     * stage.container(container);
     */

 })();
--- a/src/shapes/Sprite.js
+++ b/src/shapes/Sprite.js
@@ -7,7 +7,7 @@
     * @param {Object} config
     * @param {String} config.animation animation key
     * @param {Object} config.animations animation map
-     * @param {Integer} [config.index] animation index
+     * @param {Integer} [config.frameIndex] animation frame index
     * @param {Image} config.image image object
     * @@shapeParams
     * @@nodeParams
--- a/src/shapes/Text.js
+++ b/src/shapes/Text.js
@@ -44,7 +44,7 @@
     * @@nodeParams
     * @example
     * var text = new Kinetic.Text({<br>
-     *   x: stage.getWidth() / 2,<br>
+     *   x: 10,<br>
     *   y: 15,<br>
     *   text: 'Simple Text',<br>
     *   fontSize: 30,<br>
@@ -136,15 +136,10 @@
            context.closePath();
            context.fillStrokeShape(this);
        },
-        /**
-         * set text
-         * @method
-         * @memberof Kinetic.Text.prototype
-         * @param {String} text
-         */
        setText: function(text) {
            var str = Kinetic.Util._isString(text) ? text : text.toString();
            this._setAttr(TEXT, str);
+            return this;
        },
        /**
         * get width of text area, which includes padding
@@ -319,156 +314,139 @@
    Kinetic.Factory.addGetterSetter(Kinetic.Text, 'fontFamily', 'Arial');

    /**
-     * set font family
-     * @name setFontFamily
+     * get/set font family
+     * @name fontFamily
     * @method
     * @memberof Kinetic.Text.prototype
     * @param {String} fontFamily
-     */
-
-     /**
-     * get font family
-     * @name getFontFamily
-     * @method
-     * @memberof Kinetic.Text.prototype
     * @returns {String}
+     * @example
+     * // get font family<br>
+     * var fontFamily = text.fontFamily();<br><br><br>
+     *
+     * // set font family<br>
+     * text.fontFamily('Arial');
     */

    Kinetic.Factory.addGetterSetter(Kinetic.Text, 'fontSize', 12);

    /**
-     * set font size in pixels
-     * @name setFontSize
+     * get/set font size in pixels
+     * @name fontSize
     * @method
     * @memberof Kinetic.Text.prototype
     * @param {Number} fontSize
-     */
-
-     /**
-     * get font size
-     * @name getFontSize
-     * @method
-     * @memberof Kinetic.Text.prototype
     * @returns {Number}
+     * @example
+     * // get font size<br>
+     * var fontSize = text.fontSize();<br><br>
+     *
+     * // set font size to 22px<br>
+     * text.fontSize(22);
     */

    Kinetic.Factory.addGetterSetter(Kinetic.Text, 'fontStyle', NORMAL);

    /**
     * set font style.  Can be 'normal', 'italic', or 'bold'.  'normal' is the default.
-     * @name setFontStyle
+     * @name fontStyle
     * @method
     * @memberof Kinetic.Text.prototype
     * @param {String} fontStyle
-     */
-
-     /**
-     * get font style
-     * @name getFontStyle
-     * @method
-     * @memberof Kinetic.Text.prototype
     * @returns {String}
+     * @example
+     * // get font style<br>
+     * var fontStyle = text.fontStyle();<br><br>
+     *
+     * // set font style<br>
+     * text.fontStyle('bold');
     */

    Kinetic.Factory.addGetterSetter(Kinetic.Text, 'padding', 0);

    /**
     * set padding
-     * @name setPadding
-     * @method
-     * @memberof Kinetic.Text.prototype
-     * @param {int} padding
-     */
-
-     /**
-     * get padding
-     * @name getPadding
+     * @name padding
     * @method
     * @memberof Kinetic.Text.prototype
+     * @param {Number} padding
     * @returns {Number}
+     * @example
+     * // get padding<br>
+     * var padding = text.padding();<br><br>
+     * 
+     * // set padding to 10 pixels<br>
+     * text.padding(10);
     */

    Kinetic.Factory.addGetterSetter(Kinetic.Text, 'align', LEFT);

    /**
-     * set horizontal align of text
-     * @name setAlign
-     * @method
-     * @memberof Kinetic.Text.prototype
-     * @param {String} align align can be 'left', 'center', or 'right'
-     */
-
-     /**
-     * get horizontal align
-     * @name getAlign
+     * get/set horizontal align of text.  Can be 'left', 'center', or 'right'
+     * @name align
     * @method
     * @memberof Kinetic.Text.prototype
+     * @param {String} align
     * @returns {String}
+     * @example
+     * // get text align<br>
+     * var align = text.align();<br><br>
+     *
+     * // center text<br>
+     * text.align('center');<br><br>
+     *
+     * // align text to right<br>
+     * text.align('right');
     */

    Kinetic.Factory.addGetterSetter(Kinetic.Text, 'lineHeight', 1);

    /**
-     * set line height
-     * @name setLineHeight
-     * @method
-     * @memberof Kinetic.Text.prototype
-     * @param {Number} lineHeight default is 1
-     */
-
-     /**
-     * get line height
-     * @name getLineHeight
+     * get/set line height.  The default is 1.
+     * @name lineHeight
     * @method
     * @memberof Kinetic.Text.prototype
+     * @param {Number} lineHeight
     * @returns {Number}
+     * @example 
+     * // get line height<br>
+     * var lineHeight = text.lineHeight();<br><br><br>
+     *
+     * // set the line height<br>
+     * text.lineHeight(2);
     */

    Kinetic.Factory.addGetterSetter(Kinetic.Text, 'wrap', WORD);

    /**
-     * set wrap
-     * @name setWrap
-     * @method
-     * @memberof Kinetic.Text.prototype
-     * @param {String} wrap can be word, char, or none. Default is word
-     */
-
-     /**
-     * get wrap
-     * @name getWrap
+     * get/set wrap.  Can be word, char, or none. Default is word.
+     * @name wrap
     * @method
     * @memberof Kinetic.Text.prototype
+     * @param {String} wrap
     * @returns {String}
+     * @example
+     * // get wrap<br>
+     * var wrap = text.wrap();<br><br>
+     *
+     * // set wrap<br>
+     * text.wrap('word');
     */

    Kinetic.Factory.addGetter(Kinetic.Text, TEXT, EMPTY_STRING);

    /**
-     * get text
+     * get/set text
     * @name getText
     * @method
     * @memberof Kinetic.Text.prototype
+     * @param {String} text
     * @returns {String}
-     */
-
-    Kinetic.Factory.addSetter(Kinetic.Text, 'width');
-
-    /**
-     * set width
-     * @name setWidth
-     * @method
-     * @memberof Kinetic.Text.prototype
-     * @param {Number|String} width default is auto
-     */
-
-    Kinetic.Factory.addSetter(Kinetic.Text, 'height');
-
-    /**
-     * set height
-     * @name setHeight
-     * @method
-     * @memberof Kinetic.Text.prototype
-     * @param {Number|String} height default is auto
+     * @example
+     * // get text<br>
+     * var text = text.text();<br><br>
+     * 
+     * // set text<br>
+     * text.text('Hello world!');
     */
 })();
--- a/src/shapes/Wedge.js
+++ b/src/shapes/Wedge.js
@@ -4,8 +4,7 @@
     * @constructor
     * @augments Kinetic.Shape
     * @param {Object} config
-     * @param {Number} config.angle
-     * @param {Number} config.angleDeg angle in degrees
+     * @param {Number} config.angle in degrees
     * @param {Number} config.radius
     * @param {Boolean} [config.clockwise]
     * @@shapeParams
@@ -46,71 +45,54 @@
    Kinetic.Factory.addGetterSetter(Kinetic.Wedge, 'radius', 0);

    /**
-     * set radius
-     * @name setRadius
+     * get/set radius
+     * @name radius
     * @method
     * @memberof Kinetic.Wedge.prototype
     * @param {Number} radius
-     */
-
-     /**
-     * get radius
-     * @name getRadius
-     * @method
-     * @memberof Kinetic.Wedge.prototype
     * @returns {Number}
+     * @example
+     * // get radius<br>
+     * var radius = wedge.radius();<br><br>
+     *
+     * // set radius<br>
+     * wedge.radius(10);<br>
     */

    Kinetic.Factory.addGetterSetter(Kinetic.Wedge, 'angle', 0);

    /**
-     * set angle
-     * @name setAngle
+     * get/set angle in degrees
+     * @name angle
     * @method
     * @memberof Kinetic.Wedge.prototype
     * @param {Number} angle
-     */
-
-     /**
-     * set angle in degrees
-     * @name setAngleDeg
-     * @method
-     * @memberof Kinetic.Wedge.prototype
-     * @param {Number} angleDeg
-     */
-
-     /**
-     * get angle
-     * @name getAngle
-     * @method
-     * @memberof Kinetic.Wedge.prototype
-     * @returns {Number}
-     */
-
-     /**
-     * get angle in degrees
-     * @name getAngleDeg
-     * @method
-     * @memberof Kinetic.Wedge.prototype
     * @returns {Number}
+     * @example
+     * // get angle<br>
+     * var angle = wedge.angle();<br><br>
+     *
+     * // set angle<br>
+     * wedge.angle(20);
     */

    Kinetic.Factory.addGetterSetter(Kinetic.Wedge, 'clockwise', false);

    /**
-     * set clockwise draw direction.  If set to true, the wedge will be drawn clockwise
-     *  If set to false, the wedge will be drawn anti-clockwise.  The default is false.
-     * @name setClockwise
+     * get/set clockwise flag
+     * @name clockwise
     * @method
     * @memberof Kinetic.Wedge.prototype
-     * @param {Boolean} clockwise
-     */
-
-    /**
-     * get clockwise
-     * @name getClockwise
-     * @method
-     * @memberof Kinetic.Wedge.prototype
-     * @returns {Boolean}
+     * @param {Number} clockwise
+     * @returns {Number}
+     * @example
+     * // get clockwise flag<br>
+     * var clockwise = wedge.clockwise();<br><br>
+     *
+     * // draw wedge counter-clockwise<br>
+     * wedge.clockwise(false);<br><br>
+     *
+     * // draw wedge clockwise<br>
+     * wedge.clockwise(true);
     */
 })();
--- a/test/unit/DragAndDrop-test.js
+++ b/test/unit/DragAndDrop-test.js
@@ -19,7 +19,7 @@ suite('DragAndDrop', function() {
        layer.draw();

        // test defaults
-        assert.equal(circle.isDraggable(), false);
+        assert.equal(circle.draggable(), false);

        //change properties
        circle.setDraggable(true);
--- a/test/unit/Node-test.js
+++ b/test/unit/Node-test.js
@@ -523,7 +523,7 @@ suite('Node', function() {
        assert.equal(clone.getY(), 0);
        assert.equal(clone.getDraggable(), true);
        // test alias
-        assert.equal(clone.isDraggable(), true);
+        assert.equal(clone.draggable(), true);
        assert.equal(clone.getName(), 'groupClone');

        assert.equal(group.getChildren().length, 2);