Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Sprite.html
index 0a8e9c3..c9e5d72 100644 (file)
   </script>
 </head>
 <body onload="prettyPrint(); highlight();">
-  <pre class="prettyprint lang-js"><span id='Ext-draw-Sprite'>/**
-</span> * @class Ext.draw.Sprite
- * @extends Object
- *
- * A Sprite is an object rendered in a Drawing surface. There are different options and types of sprites.
- * The configuration of a Sprite is an object with the following properties:
- *
- * - **type** - (String) The type of the sprite. Possible options are 'circle', 'path', 'rect', 'text', 'square', 'image'. 
- * - **width** - (Number) Used in rectangle sprites, the width of the rectangle.
- * - **height** - (Number) Used in rectangle sprites, the height of the rectangle.
- * - **size** - (Number) Used in square sprites, the dimension of the square.
- * - **radius** - (Number) Used in circle sprites, the radius of the circle.
- * - **x** - (Number) The position along the x-axis.
- * - **y** - (Number) The position along the y-axis.
- * - **path** - (Array) Used in path sprites, the path of the sprite written in SVG-like path syntax.
- * - **opacity** - (Number) The opacity of the sprite.
- * - **fill** - (String) The fill color.
- * - **stroke** - (String) The stroke color.
- * - **stroke-width** - (Number) The width of the stroke.
- * - **font** - (String) Used with text type sprites. The full font description. Uses the same syntax as the CSS `font` parameter.
- * - **text** - (String) Used with text type sprites. The text itself.
- * 
- * Additionally there are three transform objects that can be set with `setAttributes` which are `translate`, `rotate` and
- * `scale`.
- * 
- * For translate, the configuration object contains x and y attributes that indicate where to
- * translate the object. For example:
- * 
- *     sprite.setAttributes({
- *       translate: {
- *        x: 10,
- *        y: 10
- *       }
- *     }, true);
- * 
- * For rotation, the configuration object contains x and y attributes for the center of the rotation (which are optional),
- * and a `degrees` attribute that specifies the rotation in degrees. For example:
- * 
- *     sprite.setAttributes({
- *       rotate: {
- *        degrees: 90
- *       }
- *     }, true);
- * 
- * For scaling, the configuration object contains x and y attributes for the x-axis and y-axis scaling. For example:
- * 
- *     sprite.setAttributes({
- *       scale: {
- *        x: 10,
- *        y: 3
- *       }
- *     }, true);
- *
- * Sprites can be created with a reference to a {@link Ext.draw.Surface}
- *
- *      var drawComponent = Ext.create('Ext.draw.Component', options here...);
- *
- *      var sprite = Ext.create('Ext.draw.Sprite', {
- *          type: 'circle',
- *          fill: '#ff0',
- *          surface: drawComponent.surface,
- *          radius: 5
- *      });
- *
- * Sprites can also be added to the surface as a configuration object:
- *
- *      var sprite = drawComponent.surface.add({
- *          type: 'circle',
- *          fill: '#ff0',
- *          radius: 5
- *      });
- *
- * In order to properly apply properties and render the sprite we have to
- * `show` the sprite setting the option `redraw` to `true`:
- *
- *      sprite.show(true);
- *
- * The constructor configuration object of the Sprite can also be used and passed into the {@link Ext.draw.Surface}
- * add method to append a new sprite to the canvas. For example:
- *
- *     drawComponent.surface.add({
- *         type: 'circle',
- *         fill: '#ffc',
- *         radius: 100,
- *         x: 100,
- *         y: 100
- *     });
- */
-Ext.define('Ext.draw.Sprite', {
-    /* Begin Definitions */
-
-    mixins: {
-        observable: 'Ext.util.Observable',
-        animate: 'Ext.util.Animate'
-    },
+  <pre class="prettyprint lang-js"><span id='Ext-fx-target-Sprite'>/**
+</span> * @class Ext.fx.target.Sprite
+ * @extends Ext.fx.target.Target
 
-    requires: ['Ext.draw.SpriteDD'],
+This class represents a animation target for a {@link Ext.draw.Sprite}. In general this class will not be
+created directly, the {@link Ext.draw.Sprite} will be passed to the animation and
+and the appropriate target will be created.
 
-    /* End Definitions */
-
-    dirty: false,
-    dirtyHidden: false,
-    dirtyTransform: false,
-    dirtyPath: true,
-    dirtyFont: true,
-    zIndexDirty: true,
-    isSprite: true,
-    zIndex: 0,
-    fontProperties: [
-        'font',
-        'font-size',
-        'font-weight',
-        'font-style',
-        'font-family',
-        'text-anchor',
-        'text'
-    ],
-    pathProperties: [
-        'x',
-        'y',
-        'd',
-        'path',
-        'height',
-        'width',
-        'radius',
-        'r',
-        'rx',
-        'ry',
-        'cx',
-        'cy'
-    ],
-    constructor: function(config) {
-        var me = this;
-        config = config || {};
-        me.id = Ext.id(null, 'ext-sprite-');
-        me.transformations = [];
-        Ext.copyTo(this, config, 'surface,group,type,draggable');
-        //attribute bucket
-        me.bbox = {};
-        me.attr = {
-            zIndex: 0,
-            translation: {
-                x: null,
-                y: null
-            },
-            rotation: {
-                degrees: null,
-                x: null,
-                y: null
-            },
-            scaling: {
-                x: null,
-                y: null,
-                cx: null,
-                cy: null
-            }
-        };
-        //delete not bucket attributes
-        delete config.surface;
-        delete config.group;
-        delete config.type;
-        delete config.draggable;
-        me.setAttributes(config);
-        me.addEvents(
-            'beforedestroy',
-            'destroy',
-            'render',
-            'mousedown',
-            'mouseup',
-            'mouseover',
-            'mouseout',
-            'mousemove',
-            'click'
-        );
-        me.mixins.observable.constructor.apply(this, arguments);
-    },
-
-<span id='Ext-draw-Sprite-property-dd'>    /**
-</span>     * &lt;p&gt;If this Sprite is configured {@link #draggable}, this property will contain
-     * an instance of {@link Ext.dd.DragSource} which handles dragging the Sprite.&lt;/p&gt;
-     * The developer must provide implementations of the abstract methods of {@link Ext.dd.DragSource}
-     * in order to supply behaviour for each stage of the drag/drop process. See {@link #draggable}.
-     * @type Ext.dd.DragSource.
-     * @property dd
-     */
-    initDraggable: function() {
-        var me = this;
-        me.draggable = true;
-        //create element if it doesn't exist.
-        if (!me.el) {
-            me.surface.createSpriteElement(me);
-        }
-        me.dd = Ext.create('Ext.draw.SpriteDD', me, Ext.isBoolean(me.draggable) ? null : me.draggable);
-        me.on('beforedestroy', me.dd.destroy, me.dd);
-    },
+ * @markdown
+ */
 
-<span id='Ext-draw-Sprite-method-setAttributes'>    /**
-</span>     * Change the attributes of the sprite.
-     * @param {Object} attrs attributes to be changed on the sprite.
-     * @param {Boolean} redraw Flag to immediatly draw the change.
-     * @return {Ext.draw.Sprite} this
-     */
-    setAttributes: function(attrs, redraw) {
-        var me = this,
-            fontProps = me.fontProperties,
-            fontPropsLength = fontProps.length,
-            pathProps = me.pathProperties,
-            pathPropsLength = pathProps.length,
-            hasSurface = !!me.surface,
-            custom = hasSurface &amp;&amp; me.surface.customAttributes || {},
-            spriteAttrs = me.attr,
-            attr, i, translate, translation, rotate, rotation, scale, scaling;
+Ext.define('Ext.fx.target.Sprite', {
 
-        attrs = Ext.apply({}, attrs);
-        for (attr in custom) {
-            if (attrs.hasOwnProperty(attr) &amp;&amp; typeof custom[attr] == &quot;function&quot;) {
-                Ext.apply(attrs, custom[attr].apply(me, [].concat(attrs[attr])));
-            }
-        }
+    /* Begin Definitions */
 
-        // Flag a change in hidden
-        if (!!attrs.hidden !== !!spriteAttrs.hidden) {
-            me.dirtyHidden = true;
-        }
+    extend: 'Ext.fx.target.Target',
 
-        // Flag path change
-        for (i = 0; i &lt; pathPropsLength; i++) {
-            attr = pathProps[i];
-            if (attr in attrs &amp;&amp; attrs[attr] !== spriteAttrs[attr]) {
-                me.dirtyPath = true;
-                break;
-            }
-        }
+    /* End Definitions */
 
-        // Flag zIndex change
-        if ('zIndex' in attrs) {
-            me.zIndexDirty = true;
-        }
+    type: 'draw',
 
-        // Flag font/text change
-        for (i = 0; i &lt; fontPropsLength; i++) {
-            attr = fontProps[i];
-            if (attr in attrs &amp;&amp; attrs[attr] !== spriteAttrs[attr]) {
-                me.dirtyFont = true;
-                break;
-            }
+    getFromPrim: function(sprite, attr) {
+        var o;
+        if (attr == 'translate') {
+            o = {
+                x: sprite.attr.translation.x || 0,
+                y: sprite.attr.translation.y || 0
+            };
         }
-
-        translate = attrs.translate;
-        translation = spriteAttrs.translation;
-        if (translate) {
-            if ((translate.x &amp;&amp; translate.x !== translation.x) ||
-                (translate.y &amp;&amp; translate.y !== translation.y)) {
-                Ext.apply(translation, translate);
-                me.dirtyTransform = true;
-            }
-            delete attrs.translate;
+        else if (attr == 'rotate') {
+            o = {
+                degrees: sprite.attr.rotation.degrees || 0,
+                x: sprite.attr.rotation.x,
+                y: sprite.attr.rotation.y
+            };
         }
-
-        rotate = attrs.rotate;
-        rotation = spriteAttrs.rotation;
-        if (rotate) {
-            if ((rotate.x &amp;&amp; rotate.x !== rotation.x) || 
-                (rotate.y &amp;&amp; rotate.y !== rotation.y) ||
-                (rotate.degrees &amp;&amp; rotate.degrees !== rotation.degrees)) {
-                Ext.apply(rotation, rotate);
-                me.dirtyTransform = true;
-            }
-            delete attrs.rotate;
+        else {
+            o = sprite.attr[attr];
         }
-
-        scale = attrs.scale;
-        scaling = spriteAttrs.scaling;
-        if (scale) {
-            if ((scale.x &amp;&amp; scale.x !== scaling.x) || 
-                (scale.y &amp;&amp; scale.y !== scaling.y) ||
-                (scale.cx &amp;&amp; scale.cx !== scaling.cx) ||
-                (scale.cy &amp;&amp; scale.cy !== scaling.cy)) {
-                Ext.apply(scaling, scale);
-                me.dirtyTransform = true;
-            }
-            delete attrs.scale;
-        }
-
-        Ext.apply(spriteAttrs, attrs);
-        me.dirty = true;
-
-        if (redraw === true &amp;&amp; hasSurface) {
-            me.redraw();
-        }
-        return this;
+        return o;
     },
 
-<span id='Ext-draw-Sprite-method-getBBox'>    /**
-</span>     * Retrieve the bounding box of the sprite. This will be returned as an object with x, y, width, and height properties.
-     * @return {Object} bbox
-     */
-    getBBox: function() {
-        return this.surface.getBBox(this);
-    },
-    
-    setText: function(text) {
-        return this.surface.setText(this, text);
-    },
-
-<span id='Ext-draw-Sprite-method-hide'>    /**
-</span>     * Hide the sprite.
-     * @param {Boolean} redraw Flag to immediatly draw the change.
-     * @return {Ext.draw.Sprite} this
-     */
-    hide: function(redraw) {
-        this.setAttributes({
-            hidden: true
-        }, redraw);
-        return this;
+    getAttr: function(attr, val) {
+        return [[this.target, val != undefined ? val : this.getFromPrim(this.target, attr)]];
     },
 
-<span id='Ext-draw-Sprite-method-show'>    /**
-</span>     * Show the sprite.
-     * @param {Boolean} redraw Flag to immediatly draw the change.
-     * @return {Ext.draw.Sprite} this
-     */
-    show: function(redraw) {
-        this.setAttributes({
-            hidden: false
-        }, redraw);
-        return this;
-    },
-
-<span id='Ext-draw-Sprite-method-remove'>    /**
-</span>     * Remove the sprite.
-     */
-    remove: function() {
-        if (this.surface) {
-            this.surface.remove(this);
-            return true;
+    setAttr: function(targetData) {
+        var ln = targetData.length,
+            spriteArr = [],
+            attrs, attr, attrArr, attPtr, spritePtr, idx, value, i, j, x, y, ln2;
+        for (i = 0; i &lt; ln; i++) {
+            attrs = targetData[i].attrs;
+            for (attr in attrs) {
+                attrArr = attrs[attr];
+                ln2 = attrArr.length;
+                for (j = 0; j &lt; ln2; j++) {
+                    spritePtr = attrArr[j][0];
+                    attPtr = attrArr[j][1];
+                    if (attr === 'translate') {
+                        value = {
+                            x: attPtr.x,
+                            y: attPtr.y
+                        };
+                    }
+                    else if (attr === 'rotate') {
+                        x = attPtr.x;
+                        if (isNaN(x)) {
+                            x = null;
+                        }
+                        y = attPtr.y;
+                        if (isNaN(y)) {
+                            y = null;
+                        }
+                        value = {
+                            degrees: attPtr.degrees,
+                            x: x,
+                            y: y
+                        };
+                    }
+                    else if (attr === 'width' || attr === 'height' || attr === 'x' || attr === 'y') {
+                        value = parseFloat(attPtr);
+                    }
+                    else {
+                        value = attPtr;
+                    }
+                    idx = Ext.Array.indexOf(spriteArr, spritePtr);
+                    if (idx == -1) {
+                        spriteArr.push([spritePtr, {}]);
+                        idx = spriteArr.length - 1;
+                    }
+                    spriteArr[idx][1][attr] = value;
+                }
+            }
         }
-        return false;
-    },
-
-    onRemove: function() {
-        this.surface.onRemove(this);
-    },
-
-<span id='Ext-draw-Sprite-method-destroy'>    /**
-</span>     * Removes the sprite and clears all listeners.
-     */
-    destroy: function() {
-        var me = this;
-        if (me.fireEvent('beforedestroy', me) !== false) {
-            me.remove();
-            me.surface.onDestroy(me);
-            me.clearListeners();
-            me.fireEvent('destroy');
+        ln = spriteArr.length;
+        for (i = 0; i &lt; ln; i++) {
+            spritePtr = spriteArr[i];
+            spritePtr[0].setAttributes(spritePtr[1]);
         }
-    },
-
-<span id='Ext-draw-Sprite-method-redraw'>    /**
-</span>     * Redraw the sprite.
-     * @return {Ext.draw.Sprite} this
-     */
-    redraw: function() {
-        this.surface.renderItem(this);
-        return this;
-    },
-
-<span id='Ext-draw-Sprite-method-setStyle'>    /**
-</span>     * Wrapper for setting style properties, also takes single object parameter of multiple styles.
-     * @param {String/Object} property The style property to be set, or an object of multiple styles.
-     * @param {String} value (optional) The value to apply to the given property, or null if an object was passed.
-     * @return {Ext.draw.Sprite} this
-     */
-    setStyle: function() {
-        this.el.setStyle.apply(this.el, arguments);
-        return this;
-    },
-
-<span id='Ext-draw-Sprite-method-addCls'>    /**
-</span>     * Adds one or more CSS classes to the element. Duplicate classes are automatically filtered out.  Note this method
-     * is severly limited in VML.
-     * @param {String/Array} className The CSS class to add, or an array of classes
-     * @return {Ext.draw.Sprite} this
-     */
-    addCls: function(obj) {
-        this.surface.addCls(this, obj);
-        return this;
-    },
-
-<span id='Ext-draw-Sprite-method-removeCls'>    /**
-</span>     * Removes one or more CSS classes from the element.
-     * @param {String/Array} className The CSS class to remove, or an array of classes.  Note this method
-     * is severly limited in VML.
-     * @return {Ext.draw.Sprite} this
-     */
-    removeCls: function(obj) {
-        this.surface.removeCls(this, obj);
-        return this;
+        this.target.redraw();
     }
 });
 </pre>