X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..6746dc89c47ed01b165cc1152533605f97eb8e8d:/docs/source/Surface.html diff --git a/docs/source/Surface.html b/docs/source/Surface.html index 2a260b8f..57d4e0fc 100644 --- a/docs/source/Surface.html +++ b/docs/source/Surface.html @@ -1,8 +1,22 @@ -Sencha Documentation Project
/**
- * @class Ext.draw.Surface
- * @extends Object
- *
- * A Surface is an interface to render methods inside a draw {@link Ext.draw.Component}.
+
+
+
+  
+  The source code
+  
+  
+  
+  
+
+
+  
/**
+ * A Surface is an interface to render methods inside a draw {@link Ext.draw.Component}.
  * A Surface contains methods to render sprites, get bounding boxes of sprites, add
  * sprites to the canvas, initialize other graphic components, etc. One of the most used
  * methods for this class is the `add` method, to add Sprites to the surface.
@@ -23,7 +37,7 @@
  * The configuration object passed in the `add` method is the same as described in the {@link Ext.draw.Sprite}
  * class documentation.
  *
- * ### Listeners
+ * # Listeners
  *
  * You can also add event listeners to the surface using the `Observable` listener syntax. Supported events are:
  *
@@ -38,11 +52,90 @@
  *
  * For example:
  *
-        drawComponent.surface.on({
-           'mousemove': function() {
-                console.log('moving the mouse over the surface');   
-            }
-        });
+ *     drawComponent.surface.on({
+ *        'mousemove': function() {
+ *             console.log('moving the mouse over the surface');   
+ *         }
+ *     });
+ *
+ * # Example
+ *
+ *     var drawComponent = Ext.create('Ext.draw.Component', {
+ *         width: 800,
+ *         height: 600,
+ *         renderTo: document.body
+ *     }), surface = drawComponent.surface;
+ *   
+ *     surface.add([{
+ *         type: 'circle',
+ *         radius: 10,
+ *         fill: '#f00',
+ *         x: 10,
+ *         y: 10,
+ *         group: 'circles'
+ *     }, {
+ *         type: 'circle',
+ *         radius: 10,
+ *         fill: '#0f0',
+ *         x: 50,
+ *         y: 50,
+ *         group: 'circles'
+ *     }, {
+ *         type: 'circle',
+ *         radius: 10,
+ *         fill: '#00f',
+ *         x: 100,
+ *         y: 100,
+ *         group: 'circles'
+ *     }, {
+ *         type: 'rect',
+ *         width: 20,
+ *         height: 20,
+ *         fill: '#f00',
+ *         x: 10,
+ *         y: 10,
+ *         group: 'rectangles'
+ *     }, {
+ *         type: 'rect',
+ *         width: 20,
+ *         height: 20,
+ *         fill: '#0f0',
+ *         x: 50,
+ *         y: 50,
+ *         group: 'rectangles'
+ *     }, {
+ *         type: 'rect',
+ *         width: 20,
+ *         height: 20,
+ *         fill: '#00f',
+ *         x: 100,
+ *         y: 100,
+ *         group: 'rectangles'
+ *     }]);
+ *   
+ *     // Get references to my groups
+ *     circles = surface.getGroup('circles');
+ *     rectangles = surface.getGroup('rectangles');
+ *
+ *     // Animate the circles down
+ *     circles.animate({
+ *         duration: 1000,
+ *         to: {
+ *             translate: {
+ *                 y: 200
+ *             }
+ *         }
+ *     });
+ *   
+ *     // Animate the rectangles across
+ *     rectangles.animate({
+ *         duration: 1000,
+ *         to: {
+ *             translate: {
+ *                 x: 200
+ *             }
+ *         }
+ *     });
  */
 Ext.define('Ext.draw.Surface', {
 
@@ -58,12 +151,13 @@ Ext.define('Ext.draw.Surface', {
     separatorRe: /[, ]+/,
 
     statics: {
-        /**
-         * Create and return a new concrete Surface instance appropriate for the current environment.
+        /**
+         * Creates and returns a new concrete Surface instance appropriate for the current environment.
          * @param {Object} config Initial configuration for the Surface instance
-         * @param {Array} enginePriority Optional order of implementations to use; the first one that is
-         *                available in the current environment will be used. Defaults to
-         *                <code>['Svg', 'Vml']</code>.
+         * @param {[String]} enginePriority Optional order of implementations to use; the first one that is
+         * available in the current environment will be used. Defaults to `['Svg', 'Vml']`.
+         * @return {Object} The created Surface or false.
+         * @static
          */
         create: function(config, enginePriority) {
             enginePriority = enginePriority || ['Svg', 'Vml'];
@@ -126,22 +220,27 @@ Ext.define('Ext.draw.Surface', {
         zIndex: 0
     },
 
- /**
-  * @cfg {Number} height
-  * The height of this component in pixels (defaults to auto).
-  * <b>Note</b> to express this dimension as a percentage or offset see {@link Ext.Component#anchor}.
-  */
- /**
-  * @cfg {Number} width
-  * The width of this component in pixels (defaults to auto).
-  * <b>Note</b> to express this dimension as a percentage or offset see {@link Ext.Component#anchor}.
-  */
+    /**
+     * @cfg {Number} height
+     * The height of this component in pixels (defaults to auto).
+     * **Note** to express this dimension as a percentage or offset see {@link Ext.Component#anchor}.
+     */
+    /**
+     * @cfg {Number} width
+     * The width of this component in pixels (defaults to auto).
+     * **Note** to express this dimension as a percentage or offset see {@link Ext.Component#anchor}.
+     */
+
     container: undefined,
     height: 352,
     width: 512,
     x: 0,
     y: 0,
 
+    /**
+     * Creates new Surface.
+     * @param {Object} config (optional) Config object.
+     */
     constructor: function(config) {
         var me = this;
         config = config || {};
@@ -188,41 +287,44 @@ Ext.define('Ext.draw.Surface', {
     // @private
     setViewBox: Ext.emptyFn,
 
-    /**
+    /**
      * Adds one or more CSS classes to the element. Duplicate classes are automatically filtered out.
      *
      * For example:
      *
-     *          drawComponent.surface.addCls(sprite, 'x-visible');
-     *      
+     *     drawComponent.surface.addCls(sprite, 'x-visible');
+     *
      * @param {Object} sprite The sprite to add the class to.
-     * @param {String/Array} className The CSS class to add, or an array of classes
+     * @param {String/[String]} className The CSS class to add, or an array of classes
+     * @method
      */
     addCls: Ext.emptyFn,
 
-    /**
+    /**
      * Removes one or more CSS classes from the element.
      *
      * For example:
      *
-     *      drawComponent.surface.removeCls(sprite, 'x-visible');
-     *      
+     *     drawComponent.surface.removeCls(sprite, 'x-visible');
+     *
      * @param {Object} sprite The sprite to remove the class from.
-     * @param {String/Array} className The CSS class to remove, or an array of classes
+     * @param {String/[String]} className The CSS class to remove, or an array of classes
+     * @method
      */
     removeCls: Ext.emptyFn,
 
-    /**
+    /**
      * Sets CSS style attributes to an element.
      *
      * For example:
      *
-     *      drawComponent.surface.setStyle(sprite, {
-     *          'cursor': 'pointer'
-     *      });
-     *      
+     *     drawComponent.surface.setStyle(sprite, {
+     *         'cursor': 'pointer'
+     *     });
+     *
      * @param {Object} sprite The sprite to add, or an array of classes to
      * @param {Object} styles An Object with CSS styles.
+     * @method
      */
     setStyle: Ext.emptyFn,
 
@@ -246,17 +348,16 @@ Ext.define('Ext.draw.Surface', {
     
     // @private
     initBackground: function(config) {
-        var gradientId, 
-            gradient,
-            backgroundSprite,
-            width = this.width,
-            height = this.height;
+        var me = this,
+            width = me.width,
+            height = me.height,
+            gradientId, gradient, backgroundSprite;
         if (config) {
             if (config.gradient) {
                 gradient = config.gradient;
                 gradientId = gradient.id;
-                this.addGradient(gradient);
-                this.background = this.add({
+                me.addGradient(gradient);
+                me.background = me.add({
                     type: 'rect',
                     x: 0,
                     y: 0,
@@ -265,7 +366,7 @@ Ext.define('Ext.draw.Surface', {
                     fill: 'url(#' + gradientId + ')'
                 });
             } else if (config.fill) {
-                this.background = this.add({
+                me.background = me.add({
                     type: 'rect',
                     x: 0,
                     y: 0,
@@ -274,7 +375,7 @@ Ext.define('Ext.draw.Surface', {
                     fill: config.fill
                 });
             } else if (config.image) {
-                this.background = this.add({
+                me.background = me.add({
                     type: 'image',
                     x: 0,
                     y: 0,
@@ -286,12 +387,12 @@ Ext.define('Ext.draw.Surface', {
         }
     },
     
-    /**
+    /**
      * Sets the size of the surface. Accomodates the background (if any) to fit the new size too.
      *
      * For example:
      *
-     *      drawComponent.surface.setSize(500, 500);
+     *     drawComponent.surface.setSize(500, 500);
      *
      * This method is generally called when also setting the size of the draw Component.
      * 
@@ -365,8 +466,8 @@ Ext.define('Ext.draw.Surface', {
     // @private
     onMouseLeave: Ext.emptyFn,
 
-    /**
-     * Add a gradient definition to the Surface. Note that in some surface engines, adding
+    /**
+     * Adds a gradient definition to the Surface. Note that in some surface engines, adding
      * a gradient via this method will not take effect if the surface has already been rendered.
      * Therefore, it is preferred to pass the gradients as an item to the surface config, rather
      * than calling this method, especially if the surface is rendered immediately (e.g. due to
@@ -375,30 +476,32 @@ Ext.define('Ext.draw.Surface', {
      *
      * The gradient object to be passed into this method is composed by:
      * 
-     * 
-     *  - **id** - string - The unique name of the gradient.
-     *  - **angle** - number, optional - The angle of the gradient in degrees.
-     *  - **stops** - object - An object with numbers as keys (from 0 to 100) and style objects as values.
-     * 
+     * - **id** - string - The unique name of the gradient.
+     * - **angle** - number, optional - The angle of the gradient in degrees.
+     * - **stops** - object - An object with numbers as keys (from 0 to 100) and style objects as values.
      *
-     For example:
-                drawComponent.surface.addGradient({
-                    id: 'gradientId',
-                    angle: 45,
-                    stops: {
-                        0: {
-                            color: '#555'
-                        },
-                        100: {
-                            color: '#ddd'
-                        }
-                    }
-                });
+     * For example:
+     *
+     *    drawComponent.surface.addGradient({
+     *        id: 'gradientId',
+     *        angle: 45,
+     *        stops: {
+     *            0: {
+     *                color: '#555'
+     *            },
+     *            100: {
+     *                color: '#ddd'
+     *            }
+     *        }
+     *    });
+     *
+     * @method
      */
     addGradient: Ext.emptyFn,
 
-    /**
-     * Add a Sprite to the surface. See {@link Ext.draw.Sprite} for the configuration object to be passed into this method.
+    /**
+     * Adds a Sprite to the surface. See {@link Ext.draw.Sprite} for the configuration object to be
+     * passed into this method.
      *
      * For example:
      *
@@ -410,7 +513,7 @@ Ext.define('Ext.draw.Surface', {
      *         y: 100
      *     });
      *
-    */
+     */
     add: function() {
         var args = Array.prototype.slice.call(arguments),
             sprite,
@@ -436,9 +539,9 @@ Ext.define('Ext.draw.Surface', {
         return sprite;
     },
 
-    /**
+    /**
      * @private
-     * Insert or move a given sprite into the correct position in the items
+     * Inserts or moves a given sprite into the correct position in the items
      * MixedCollection, according to its zIndex. Will be inserted at the end of
      * an existing series of sprites with the same or lower zIndex. If the sprite
      * is already positioned within an appropriate zIndex group, it will not be moved.
@@ -484,16 +587,16 @@ Ext.define('Ext.draw.Surface', {
         }
     },
 
-    /**
-     * Remove a given sprite from the surface, optionally destroying the sprite in the process.
+    /**
+     * Removes a given sprite from the surface, optionally destroying the sprite in the process.
      * You can also call the sprite own `remove` method.
      *
      * For example:
      *
-     *      drawComponent.surface.remove(sprite);
-     *      //or...
-     *      sprite.remove();
-     *      
+     *     drawComponent.surface.remove(sprite);
+     *     //or...
+     *     sprite.remove();
+     *
      * @param {Ext.draw.Sprite} sprite
      * @param {Boolean} destroySprite
      * @return {Number} the sprite's new index in the list
@@ -511,13 +614,13 @@ Ext.define('Ext.draw.Surface', {
         }
     },
 
-    /**
-     * Remove all sprites from the surface, optionally destroying the sprites in the process.
+    /**
+     * Removes all sprites from the surface, optionally destroying the sprites in the process.
      *
      * For example:
      *
-     *      drawComponent.surface.removeAll();
-     *      
+     *     drawComponent.surface.removeAll();
+     *
      * @param {Boolean} destroySprites Whether to destroy all sprites when removing them.
      * @return {Number} The sprite's new index in the list.
      */
@@ -644,7 +747,9 @@ Ext.define('Ext.draw.Surface', {
     // @private
     getPathellipse: function (el) {
         var a = el.attr;
-        return this.ellipsePath(a.x, a.y, a.radiusX, a.radiusY);
+        return this.ellipsePath(a.x, a.y,
+                                a.radiusX || (a.width / 2) || 0,
+                                a.radiusY || (a.height / 2) || 0);
     },
 
     // @private
@@ -677,14 +782,14 @@ Ext.define('Ext.draw.Surface', {
         return group;
     },
 
-    /**
+    /**
      * Returns a new group or an existent group associated with the current surface.
      * The group returned is a {@link Ext.draw.CompositeSprite} group.
      *
      * For example:
      *
-     *      var spriteGroup = drawComponent.surface.getGroup('someGroupId');
-     *      
+     *     var spriteGroup = drawComponent.surface.getGroup('someGroupId');
+     *
      * @param {String} id The unique identifier of the group.
      * @return {Object} The {@link Ext.draw.CompositeSprite}.
      */
@@ -718,16 +823,17 @@ Ext.define('Ext.draw.Surface', {
         return items;
     },
     
-    /**
+    /**
      * Changes the text in the sprite element. The sprite must be a `text` sprite.
      * This method can also be called from {@link Ext.draw.Sprite}.
      *
      * For example:
      *
-     *      var spriteGroup = drawComponent.surface.setText(sprite, 'my new text');
-     *      
+     *     var spriteGroup = drawComponent.surface.setText(sprite, 'my new text');
+     *
      * @param {Object} sprite The Sprite to change the text.
      * @param {String} text The new text to be set.
+     * @method
      */
     setText: Ext.emptyFn,
     
@@ -735,7 +841,7 @@ Ext.define('Ext.draw.Surface', {
     //as an internal method when calling `add`.
     createItem: Ext.emptyFn,
 
-    /**
+    /**
      * Retrieves the id of this component.
      * Will autogenerate an id if one has not already been set.
      */
@@ -743,7 +849,7 @@ Ext.define('Ext.draw.Surface', {
         return this.id || (this.id = Ext.id(null, 'ext-surface-'));
     },
 
-    /**
+    /**
      * Destroys the surface. This is done by removing all components from it and
      * also removing its reference to a DOM element.
      *
@@ -755,4 +861,6 @@ Ext.define('Ext.draw.Surface', {
         delete this.domRef;
         this.removeAll();
     }
-});
\ No newline at end of file +});
+ +