docs/source/Sprite.html

   1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-draw.Sprite'>/**
   2 </span> * @class Ext.draw.Sprite
   3  * @extends Object
   4  *
   5  * A Sprite is an object rendered in a Drawing surface. There are different options and types of sprites.
   6  * The configuration of a Sprite is an object with the following properties:
   7  *
   8  * - **type** - (String) The type of the sprite. Possible options are 'circle', 'path', 'rect', 'text', 'square'.
   9  * - **width** - (Number) Used in rectangle sprites, the width of the rectangle.
  10  * - **height** - (Number) Used in rectangle sprites, the height of the rectangle.
  11  * - **size** - (Number) Used in square sprites, the dimension of the square.
  12  * - **radius** - (Number) Used in circle sprites, the radius of the circle.
  13  * - **x** - (Number) The position along the x-axis.
  14  * - **y** - (Number) The position along the y-axis.
  15  * - **path** - (Array) Used in path sprites, the path of the sprite written in SVG-like path syntax.
  16  * - **opacity** - (Number) The opacity of the sprite.
  17  * - **fill** - (String) The fill color.
  18  * - **stroke** - (String) The stroke color.
  19  * - **stroke-width** - (Number) The width of the stroke.
  20  * - **font** - (String) Used with text type sprites. The full font description. Uses the same syntax as the CSS `font` parameter.
  21  * - **text** - (String) Used with text type sprites. The text itself.
  22  *
  23  * Additionally there are three transform objects that can be set with `setAttributes` which are `translate`, `rotate` and
  24  * `scale`.
  25  *
  26  * For translate, the configuration object contains x and y attributes that indicate where to
  27  * translate the object. For example:
  28  *
  29  *     sprite.setAttributes({
  30  *       translate: {
  31  *        x: 10,
  32  *        y: 10
  33  *       }
  34  *     }, true);
  35  *
  36  * For rotation, the configuration object contains x and y attributes for the center of the rotation (which are optional),
  37  * and a `degrees` attribute that specifies the rotation in degrees. For example:
  38  *
  39  *     sprite.setAttributes({
  40  *       rotate: {
  41  *        degrees: 90
  42  *       }
  43  *     }, true);
  44  *
  45  * For scaling, the configuration object contains x and y attributes for the x-axis and y-axis scaling. For example:
  46  *
  47  *     sprite.setAttributes({
  48  *       scale: {
  49  *        x: 10,
  50  *        y: 3
  51  *       }
  52  *     }, true);
  53  *
  54  * Sprites can be created with a reference to a {@link Ext.draw.Surface}
  55  *
  56  *      var drawComponent = Ext.create('Ext.draw.Component', options here...);
  57  *
  58  *      var sprite = Ext.create('Ext.draw.Sprite', {
  59  *          type: 'circle',
  60  *          fill: '#ff0',
  61  *          surface: drawComponent.surface,
  62  *          radius: 5
  63  *      });
  64  *
  65  * Sprites can also be added to the surface as a configuration object:
  66  *
  67  *      var sprite = drawComponent.surface.add({
  68  *          type: 'circle',
  69  *          fill: '#ff0',
  70  *          radius: 5
  71  *      });
  72  *
  73  * In order to properly apply properties and render the sprite we have to
  74  * `show` the sprite setting the option `redraw` to `true`:
  75  *
  76  *      sprite.show(true);
  77  *
  78  * The constructor configuration object of the Sprite can also be used and passed into the {@link Ext.draw.Surface}
  79  * add method to append a new sprite to the canvas. For example:
  80  *
  81  *     drawComponent.surface.add({
  82  *         type: 'circle',
  83  *         fill: '#ffc',
  84  *         radius: 100,
  85  *         x: 100,
  86  *         y: 100
  87  *     });
  88  */
  89 Ext.define('Ext.draw.Sprite', {
  90     /* Begin Definitions */
  91
  92     mixins: {
  93         observable: 'Ext.util.Observable',
  94         animate: 'Ext.util.Animate'
  95     },
  96
  97     requires: ['Ext.draw.SpriteDD'],
  98
  99     /* End Definitions */
 100
 101     dirty: false,
 102     dirtyHidden: false,
 103     dirtyTransform: false,
 104     dirtyPath: true,
 105     dirtyFont: true,
 106     zIndexDirty: true,
 107     isSprite: true,
 108     zIndex: 0,
 109     fontProperties: [
 110         'font',
 111         'font-size',
 112         'font-weight',
 113         'font-style',
 114         'font-family',
 115         'text-anchor',
 116         'text'
 117     ],
 118     pathProperties: [
 119         'x',
 120         'y',
 121         'd',
 122         'path',
 123         'height',
 124         'width',
 125         'radius',
 126         'r',
 127         'rx',
 128         'ry',
 129         'cx',
 130         'cy'
 131     ],
 132     constructor: function(config) {
 133         var me = this;
 134         config = config || {};
 135         me.id = Ext.id(null, 'ext-sprite-');
 136         me.transformations = [];
 137         Ext.copyTo(this, config, 'surface,group,type,draggable');
 138         //attribute bucket
 139         me.bbox = {};
 140         me.attr = {
 141             zIndex: 0,
 142             translation: {
 143                 x: null,
 144                 y: null
 145             },
 146             rotation: {
 147                 degrees: null,
 148                 x: null,
 149                 y: null
 150             },
 151             scaling: {
 152                 x: null,
 153                 y: null,
 154                 cx: null,
 155                 cy: null
 156             }
 157         };
 158         //delete not bucket attributes
 159         delete config.surface;
 160         delete config.group;
 161         delete config.type;
 162         delete config.draggable;
 163         me.setAttributes(config);
 164         me.addEvents(
 165             'beforedestroy',
 166             'destroy',
 167             'render',
 168             'mousedown',
 169             'mouseup',
 170             'mouseover',
 171             'mouseout',
 172             'mousemove',
 173             'click'
 174         );
 175         me.mixins.observable.constructor.apply(this, arguments);
 176     },
 177
 178 <span id='Ext-draw.Sprite-property-dd'>    /**
 179 </span>     * &lt;p&gt;If this Sprite is configured {@link #draggable}, this property will contain
 180      * an instance of {@link Ext.dd.DragSource} which handles dragging the Sprite.&lt;/p&gt;
 181      * The developer must provide implementations of the abstract methods of {@link Ext.dd.DragSource}
 182      * in order to supply behaviour for each stage of the drag/drop process. See {@link #draggable}.
 183      * @type Ext.dd.DragSource.
 184      * @property dd
 185      */
 186     initDraggable: function() {
 187         var me = this;
 188         me.draggable = true;
 189         //create element if it doesn't exist.
 190         if (!me.el) {
 191             me.surface.createSprite(me);
 192         }
 193         me.dd = Ext.create('Ext.draw.SpriteDD', me, Ext.isBoolean(me.draggable) ? null : me.draggable);
 194         me.on('beforedestroy', me.dd.destroy, me.dd);
 195     },
 196
 197 <span id='Ext-draw.Sprite-method-setAttributes'>    /**
 198 </span>     * Change the attributes of the sprite.
 199      * @param {Object} attrs attributes to be changed on the sprite.
 200      * @param {Boolean} redraw Flag to immediatly draw the change.
 201      * @return {Ext.draw.Sprite} this
 202      */
 203     setAttributes: function(attrs, redraw) {
 204         var me = this,
 205             fontProps = me.fontProperties,
 206             fontPropsLength = fontProps.length,
 207             pathProps = me.pathProperties,
 208             pathPropsLength = pathProps.length,
 209             hasSurface = !!me.surface,
 210             custom = hasSurface &amp;&amp; me.surface.customAttributes || {},
 211             spriteAttrs = me.attr,
 212             attr, i, translate, translation, rotate, rotation, scale, scaling;
 213
 214         for (attr in custom) {
 215             if (attrs.hasOwnProperty(attr) &amp;&amp; typeof custom[attr] == &quot;function&quot;) {
 216                 Ext.apply(attrs, custom[attr].apply(me, [].concat(attrs[attr])));
 217             }
 218         }
 219
 220         // Flag a change in hidden
 221         if (!!attrs.hidden !== !!spriteAttrs.hidden) {
 222             me.dirtyHidden = true;
 223         }
 224
 225         // Flag path change
 226         for (i = 0; i &lt; pathPropsLength; i++) {
 227             attr = pathProps[i];
 228             if (attr in attrs &amp;&amp; attrs[attr] !== spriteAttrs[attr]) {
 229                 me.dirtyPath = true;
 230                 break;
 231             }
 232         }
 233
 234         // Flag zIndex change
 235         if ('zIndex' in attrs) {
 236             me.zIndexDirty = true;
 237         }
 238
 239         // Flag font/text change
 240         for (i = 0; i &lt; fontPropsLength; i++) {
 241             attr = fontProps[i];
 242             if (attr in attrs &amp;&amp; attrs[attr] !== spriteAttrs[attr]) {
 243                 me.dirtyFont = true;
 244                 break;
 245             }
 246         }
 247
 248         translate = attrs.translate;
 249         translation = spriteAttrs.translation;
 250         if (translate) {
 251             if ((translate.x &amp;&amp; translate.x !== translation.x) ||
 252                 (translate.y &amp;&amp; translate.y !== translation.y)) {
 253                 Ext.apply(translation, translate);
 254                 me.dirtyTransform = true;
 255             }
 256             delete attrs.translate;
 257         }
 258
 259         rotate = attrs.rotate;
 260         rotation = spriteAttrs.rotation;
 261         if (rotate) {
 262             if ((rotate.x &amp;&amp; rotate.x !== rotation.x) ||
 263                 (rotate.y &amp;&amp; rotate.y !== rotation.y) ||
 264                 (rotate.degrees &amp;&amp; rotate.degrees !== rotation.degrees)) {
 265                 Ext.apply(rotation, rotate);
 266                 me.dirtyTransform = true;
 267             }
 268             delete attrs.rotate;
 269         }
 270
 271         scale = attrs.scale;
 272         scaling = spriteAttrs.scaling;
 273         if (scale) {
 274             if ((scale.x &amp;&amp; scale.x !== scaling.x) ||
 275                 (scale.y &amp;&amp; scale.y !== scaling.y) ||
 276                 (scale.cx &amp;&amp; scale.cx !== scaling.cx) ||
 277                 (scale.cy &amp;&amp; scale.cy !== scaling.cy)) {
 278                 Ext.apply(scaling, scale);
 279                 me.dirtyTransform = true;
 280             }
 281             delete attrs.scale;
 282         }
 283
 284         Ext.apply(spriteAttrs, attrs);
 285         me.dirty = true;
 286
 287         if (redraw === true &amp;&amp; hasSurface) {
 288             me.redraw();
 289         }
 290         return this;
 291     },
 292
 293 <span id='Ext-draw.Sprite-method-getBBox'>    /**
 294 </span>     * Retrieve the bounding box of the sprite. This will be returned as an object with x, y, width, and height properties.
 295      * @return {Object} bbox
 296      */
 297     getBBox: function() {
 298         return this.surface.getBBox(this);
 299     },
 300
 301     setText: function(text) {
 302         return this.surface.setText(this, text);
 303     },
 304
 305 <span id='Ext-draw.Sprite-method-hide'>    /**
 306 </span>     * Hide the sprite.
 307      * @param {Boolean} redraw Flag to immediatly draw the change.
 308      * @return {Ext.draw.Sprite} this
 309      */
 310     hide: function(redraw) {
 311         this.setAttributes({
 312             hidden: true
 313         }, redraw);
 314         return this;
 315     },
 316
 317 <span id='Ext-draw.Sprite-method-show'>    /**
 318 </span>     * Show the sprite.
 319      * @param {Boolean} redraw Flag to immediatly draw the change.
 320      * @return {Ext.draw.Sprite} this
 321      */
 322     show: function(redraw) {
 323         this.setAttributes({
 324             hidden: false
 325         }, redraw);
 326         return this;
 327     },
 328
 329 <span id='Ext-draw.Sprite-method-remove'>    /**
 330 </span>     * Remove the sprite.
 331      */
 332     remove: function() {
 333         if (this.surface) {
 334             this.surface.remove(this);
 335             return true;
 336         }
 337         return false;
 338     },
 339
 340     onRemove: function() {
 341         this.surface.onRemove(this);
 342     },
 343
 344 <span id='Ext-draw.Sprite-method-destroy'>    /**
 345 </span>     * Removes the sprite and clears all listeners.
 346      */
 347     destroy: function() {
 348         var me = this;
 349         if (me.fireEvent('beforedestroy', me) !== false) {
 350             me.remove();
 351             me.surface.onDestroy(me);
 352             me.clearListeners();
 353             me.fireEvent('destroy');
 354         }
 355     },
 356
 357 <span id='Ext-draw.Sprite-method-redraw'>    /**
 358 </span>     * Redraw the sprite.
 359      * @return {Ext.draw.Sprite} this
 360      */
 361     redraw: function() {
 362         this.surface.renderItem(this);
 363         return this;
 364     },
 365
 366 <span id='Ext-draw.Sprite-method-setStyle'>    /**
 367 </span>     * Wrapper for setting style properties, also takes single object parameter of multiple styles.
 368      * @param {String/Object} property The style property to be set, or an object of multiple styles.
 369      * @param {String} value (optional) The value to apply to the given property, or null if an object was passed.
 370      * @return {Ext.draw.Sprite} this
 371      */
 372     setStyle: function() {
 373         this.el.setStyle.apply(this.el, arguments);
 374         return this;
 375     },
 376
 377 <span id='Ext-draw.Sprite-method-addCls'>    /**
 378 </span>     * Adds one or more CSS classes to the element. Duplicate classes are automatically filtered out.  Note this method
 379      * is severly limited in VML.
 380      * @param {String/Array} className The CSS class to add, or an array of classes
 381      * @return {Ext.draw.Sprite} this
 382      */
 383     addCls: function(obj) {
 384         this.surface.addCls(this, obj);
 385         return this;
 386     },
 387
 388 <span id='Ext-draw.Sprite-method-removeCls'>    /**
 389 </span>     * Removes one or more CSS classes from the element.
 390      * @param {String/Array} className The CSS class to remove, or an array of classes.  Note this method
 391      * is severly limited in VML.
 392      * @return {Ext.draw.Sprite} this
 393      */
 394     removeCls: function(obj) {
 395         this.surface.removeCls(this, obj);
 396         return this;
 397     }
 398 });
 399 </pre></pre></body></html>