docs/source/Sprite.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-draw-Sprite'>/**
  19 </span> * A Sprite is an object rendered in a Drawing surface.
  20  *
  21  * # Translation
  22  *
  23  * For translate, the configuration object contains x and y attributes that indicate where to
  24  * translate the object. For example:
  25  *
  26  *     sprite.setAttributes({
  27  *       translate: {
  28  *        x: 10,
  29  *        y: 10
  30  *       }
  31  *     }, true);
  32  *
  33  *
  34  * # Rotation
  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  * That example will create a 90 degrees rotation using the centroid of the Sprite as center of rotation, whereas:
  46  *
  47  *     sprite.setAttributes({
  48  *       rotate: {
  49  *        x: 0,
  50  *        y: 0,
  51  *        degrees: 90
  52  *       }
  53  *     }, true);
  54  *
  55  * will create a rotation around the `(0, 0)` axis.
  56  *
  57  *
  58  * # Scaling
  59  *
  60  * For scaling, the configuration object contains x and y attributes for the x-axis and y-axis scaling. For example:
  61  *
  62  *     sprite.setAttributes({
  63  *       scale: {
  64  *        x: 10,
  65  *        y: 3
  66  *       }
  67  *     }, true);
  68  *
  69  * You can also specify the center of scaling by adding `cx` and `cy` as properties:
  70  *
  71  *     sprite.setAttributes({
  72  *       scale: {
  73  *        cx: 0,
  74  *        cy: 0,
  75  *        x: 10,
  76  *        y: 3
  77  *       }
  78  *     }, true);
  79  *
  80  * That last example will scale a sprite taking as centers of scaling the `(0, 0)` coordinate.
  81  *
  82  *
  83  * # Creating and adding a Sprite to a Surface
  84  *
  85  * Sprites can be created with a reference to a {@link Ext.draw.Surface}
  86  *
  87  *     var drawComponent = Ext.create('Ext.draw.Component', options here...);
  88  *
  89  *     var sprite = Ext.create('Ext.draw.Sprite', {
  90  *         type: 'circle',
  91  *         fill: '#ff0',
  92  *         surface: drawComponent.surface,
  93  *         radius: 5
  94  *     });
  95  *
  96  * Sprites can also be added to the surface as a configuration object:
  97  *
  98  *     var sprite = drawComponent.surface.add({
  99  *         type: 'circle',
 100  *         fill: '#ff0',
 101  *         radius: 5
 102  *     });
 103  *
 104  * In order to properly apply properties and render the sprite we have to
 105  * `show` the sprite setting the option `redraw` to `true`:
 106  *
 107  *     sprite.show(true);
 108  *
 109  * The constructor configuration object of the Sprite can also be used and passed into the {@link Ext.draw.Surface}
 110  * add method to append a new sprite to the canvas. For example:
 111  *
 112  *     drawComponent.surface.add({
 113  *         type: 'circle',
 114  *         fill: '#ffc',
 115  *         radius: 100,
 116  *         x: 100,
 117  *         y: 100
 118  *     });
 119  */
 120 Ext.define('Ext.draw.Sprite', {
 121
 122     /* Begin Definitions */
 123
 124     mixins: {
 125         observable: 'Ext.util.Observable',
 126         animate: 'Ext.util.Animate'
 127     },
 128
 129     requires: ['Ext.draw.SpriteDD'],
 130
 131     /* End Definitions */
 132
 133 <span id='Ext-draw-Sprite-cfg-type'>    /**
 134 </span>     * @cfg {String} type The type of the sprite. Possible options are 'circle', 'path', 'rect', 'text', 'square', 'image'
 135      */
 136
 137 <span id='Ext-draw-Sprite-cfg-width'>    /**
 138 </span>     * @cfg {Number} width Used in rectangle sprites, the width of the rectangle
 139      */
 140
 141 <span id='Ext-draw-Sprite-cfg-height'>    /**
 142 </span>     * @cfg {Number} height Used in rectangle sprites, the height of the rectangle
 143      */
 144
 145 <span id='Ext-draw-Sprite-cfg-size'>    /**
 146 </span>     * @cfg {Number} size Used in square sprites, the dimension of the square
 147      */
 148
 149 <span id='Ext-draw-Sprite-cfg-radius'>    /**
 150 </span>     * @cfg {Number} radius Used in circle sprites, the radius of the circle
 151      */
 152
 153 <span id='Ext-draw-Sprite-cfg-x'>    /**
 154 </span>     * @cfg {Number} x The position along the x-axis
 155      */
 156
 157 <span id='Ext-draw-Sprite-cfg-y'>    /**
 158 </span>     * @cfg {Number} y The position along the y-axis
 159      */
 160
 161 <span id='Ext-draw-Sprite-cfg-path'>    /**
 162 </span>     * @cfg {Array} path Used in path sprites, the path of the sprite written in SVG-like path syntax
 163      */
 164
 165 <span id='Ext-draw-Sprite-cfg-opacity'>    /**
 166 </span>     * @cfg {Number} opacity The opacity of the sprite
 167      */
 168
 169 <span id='Ext-draw-Sprite-cfg-fill'>    /**
 170 </span>     * @cfg {String} fill The fill color
 171      */
 172
 173 <span id='Ext-draw-Sprite-cfg-stroke'>    /**
 174 </span>     * @cfg {String} stroke The stroke color
 175      */
 176
 177 <span id='Ext-draw-Sprite-cfg-stroke'>    /**
 178 </span>     * @cfg {Number} stroke-width The width of the stroke
 179      */
 180
 181 <span id='Ext-draw-Sprite-cfg-font'>    /**
 182 </span>     * @cfg {String} font Used with text type sprites. The full font description. Uses the same syntax as the CSS font parameter
 183      */
 184
 185 <span id='Ext-draw-Sprite-cfg-text'>    /**
 186 </span>     * @cfg {String} text Used with text type sprites. The text itself
 187      */
 188
 189 <span id='Ext-draw-Sprite-cfg-group'>    /**
 190 </span>     * @cfg {String/String[]} group The group that this sprite belongs to, or an array of groups. Only relevant when added to a
 191      * {@link Ext.draw.Surface}
 192      */
 193
 194 <span id='Ext-draw-Sprite-cfg-draggable'>    /**
 195 </span>     * @cfg {Boolean} draggable True to make the sprite draggable.
 196      */
 197
 198     dirty: false,
 199     dirtyHidden: false,
 200     dirtyTransform: false,
 201     dirtyPath: true,
 202     dirtyFont: true,
 203     zIndexDirty: true,
 204     isSprite: true,
 205     zIndex: 0,
 206     fontProperties: [
 207         'font',
 208         'font-size',
 209         'font-weight',
 210         'font-style',
 211         'font-family',
 212         'text-anchor',
 213         'text'
 214     ],
 215     pathProperties: [
 216         'x',
 217         'y',
 218         'd',
 219         'path',
 220         'height',
 221         'width',
 222         'radius',
 223         'r',
 224         'rx',
 225         'ry',
 226         'cx',
 227         'cy'
 228     ],
 229     constructor: function(config) {
 230         var me = this;
 231         config = config || {};
 232         me.id = Ext.id(null, 'ext-sprite-');
 233         me.transformations = [];
 234         Ext.copyTo(this, config, 'surface,group,type,draggable');
 235         //attribute bucket
 236         me.bbox = {};
 237         me.attr = {
 238             zIndex: 0,
 239             translation: {
 240                 x: null,
 241                 y: null
 242             },
 243             rotation: {
 244                 degrees: null,
 245                 x: null,
 246                 y: null
 247             },
 248             scaling: {
 249                 x: null,
 250                 y: null,
 251                 cx: null,
 252                 cy: null
 253             }
 254         };
 255         //delete not bucket attributes
 256         delete config.surface;
 257         delete config.group;
 258         delete config.type;
 259         delete config.draggable;
 260         me.setAttributes(config);
 261         me.addEvents(
 262             'beforedestroy',
 263             'destroy',
 264             'render',
 265             'mousedown',
 266             'mouseup',
 267             'mouseover',
 268             'mouseout',
 269             'mousemove',
 270             'click'
 271         );
 272         me.mixins.observable.constructor.apply(this, arguments);
 273     },
 274
 275 <span id='Ext-draw-Sprite-property-dd'>    /**
 276 </span>     * @property {Ext.dd.DragSource} dd
 277      * If this Sprite is configured {@link #draggable}, this property will contain
 278      * an instance of {@link Ext.dd.DragSource} which handles dragging the Sprite.
 279      *
 280      * The developer must provide implementations of the abstract methods of {@link Ext.dd.DragSource}
 281      * in order to supply behaviour for each stage of the drag/drop process. See {@link #draggable}.
 282      */
 283
 284     initDraggable: function() {
 285         var me = this;
 286         me.draggable = true;
 287         //create element if it doesn't exist.
 288         if (!me.el) {
 289             me.surface.createSpriteElement(me);
 290         }
 291         me.dd = Ext.create('Ext.draw.SpriteDD', me, Ext.isBoolean(me.draggable) ? null : me.draggable);
 292         me.on('beforedestroy', me.dd.destroy, me.dd);
 293     },
 294
 295 <span id='Ext-draw-Sprite-method-setAttributes'>    /**
 296 </span>     * Change the attributes of the sprite.
 297      * @param {Object} attrs attributes to be changed on the sprite.
 298      * @param {Boolean} redraw Flag to immediatly draw the change.
 299      * @return {Ext.draw.Sprite} this
 300      */
 301     setAttributes: function(attrs, redraw) {
 302         var me = this,
 303             fontProps = me.fontProperties,
 304             fontPropsLength = fontProps.length,
 305             pathProps = me.pathProperties,
 306             pathPropsLength = pathProps.length,
 307             hasSurface = !!me.surface,
 308             custom = hasSurface &amp;&amp; me.surface.customAttributes || {},
 309             spriteAttrs = me.attr,
 310             attr, i, translate, translation, rotate, rotation, scale, scaling;
 311
 312         attrs = Ext.apply({}, attrs);
 313         for (attr in custom) {
 314             if (attrs.hasOwnProperty(attr) &amp;&amp; typeof custom[attr] == &quot;function&quot;) {
 315                 Ext.apply(attrs, custom[attr].apply(me, [].concat(attrs[attr])));
 316             }
 317         }
 318
 319         // Flag a change in hidden
 320         if (!!attrs.hidden !== !!spriteAttrs.hidden) {
 321             me.dirtyHidden = true;
 322         }
 323
 324         // Flag path change
 325         for (i = 0; i &lt; pathPropsLength; i++) {
 326             attr = pathProps[i];
 327             if (attr in attrs &amp;&amp; attrs[attr] !== spriteAttrs[attr]) {
 328                 me.dirtyPath = true;
 329                 break;
 330             }
 331         }
 332
 333         // Flag zIndex change
 334         if ('zIndex' in attrs) {
 335             me.zIndexDirty = true;
 336         }
 337
 338         // Flag font/text change
 339         for (i = 0; i &lt; fontPropsLength; i++) {
 340             attr = fontProps[i];
 341             if (attr in attrs &amp;&amp; attrs[attr] !== spriteAttrs[attr]) {
 342                 me.dirtyFont = true;
 343                 break;
 344             }
 345         }
 346
 347         translate = attrs.translate;
 348         translation = spriteAttrs.translation;
 349         if (translate) {
 350             if ((translate.x &amp;&amp; translate.x !== translation.x) ||
 351                 (translate.y &amp;&amp; translate.y !== translation.y)) {
 352                 Ext.apply(translation, translate);
 353                 me.dirtyTransform = true;
 354             }
 355             delete attrs.translate;
 356         }
 357
 358         rotate = attrs.rotate;
 359         rotation = spriteAttrs.rotation;
 360         if (rotate) {
 361             if ((rotate.x &amp;&amp; rotate.x !== rotation.x) ||
 362                 (rotate.y &amp;&amp; rotate.y !== rotation.y) ||
 363                 (rotate.degrees &amp;&amp; rotate.degrees !== rotation.degrees)) {
 364                 Ext.apply(rotation, rotate);
 365                 me.dirtyTransform = true;
 366             }
 367             delete attrs.rotate;
 368         }
 369
 370         scale = attrs.scale;
 371         scaling = spriteAttrs.scaling;
 372         if (scale) {
 373             if ((scale.x &amp;&amp; scale.x !== scaling.x) ||
 374                 (scale.y &amp;&amp; scale.y !== scaling.y) ||
 375                 (scale.cx &amp;&amp; scale.cx !== scaling.cx) ||
 376                 (scale.cy &amp;&amp; scale.cy !== scaling.cy)) {
 377                 Ext.apply(scaling, scale);
 378                 me.dirtyTransform = true;
 379             }
 380             delete attrs.scale;
 381         }
 382
 383         Ext.apply(spriteAttrs, attrs);
 384         me.dirty = true;
 385
 386         if (redraw === true &amp;&amp; hasSurface) {
 387             me.redraw();
 388         }
 389         return this;
 390     },
 391
 392 <span id='Ext-draw-Sprite-method-getBBox'>    /**
 393 </span>     * Retrieves the bounding box of the sprite.
 394      * This will be returned as an object with x, y, width, and height properties.
 395      * @return {Object} bbox
 396      */
 397     getBBox: function() {
 398         return this.surface.getBBox(this);
 399     },
 400
 401     setText: function(text) {
 402         return this.surface.setText(this, text);
 403     },
 404
 405 <span id='Ext-draw-Sprite-method-hide'>    /**
 406 </span>     * Hides the sprite.
 407      * @param {Boolean} redraw Flag to immediatly draw the change.
 408      * @return {Ext.draw.Sprite} this
 409      */
 410     hide: function(redraw) {
 411         this.setAttributes({
 412             hidden: true
 413         }, redraw);
 414         return this;
 415     },
 416
 417 <span id='Ext-draw-Sprite-method-show'>    /**
 418 </span>     * Shows the sprite.
 419      * @param {Boolean} redraw Flag to immediatly draw the change.
 420      * @return {Ext.draw.Sprite} this
 421      */
 422     show: function(redraw) {
 423         this.setAttributes({
 424             hidden: false
 425         }, redraw);
 426         return this;
 427     },
 428
 429 <span id='Ext-draw-Sprite-method-remove'>    /**
 430 </span>     * Removes the sprite.
 431      */
 432     remove: function() {
 433         if (this.surface) {
 434             this.surface.remove(this);
 435             return true;
 436         }
 437         return false;
 438     },
 439
 440     onRemove: function() {
 441         this.surface.onRemove(this);
 442     },
 443
 444 <span id='Ext-draw-Sprite-method-destroy'>    /**
 445 </span>     * Removes the sprite and clears all listeners.
 446      */
 447     destroy: function() {
 448         var me = this;
 449         if (me.fireEvent('beforedestroy', me) !== false) {
 450             me.remove();
 451             me.surface.onDestroy(me);
 452             me.clearListeners();
 453             me.fireEvent('destroy');
 454         }
 455     },
 456
 457 <span id='Ext-draw-Sprite-method-redraw'>    /**
 458 </span>     * Redraws the sprite.
 459      * @return {Ext.draw.Sprite} this
 460      */
 461     redraw: function() {
 462         this.surface.renderItem(this);
 463         return this;
 464     },
 465
 466 <span id='Ext-draw-Sprite-method-setStyle'>    /**
 467 </span>     * Wrapper for setting style properties, also takes single object parameter of multiple styles.
 468      * @param {String/Object} property The style property to be set, or an object of multiple styles.
 469      * @param {String} value (optional) The value to apply to the given property, or null if an object was passed.
 470      * @return {Ext.draw.Sprite} this
 471      */
 472     setStyle: function() {
 473         this.el.setStyle.apply(this.el, arguments);
 474         return this;
 475     },
 476
 477 <span id='Ext-draw-Sprite-method-addCls'>    /**
 478 </span>     * Adds one or more CSS classes to the element. Duplicate classes are automatically filtered out.  Note this method
 479      * is severly limited in VML.
 480      * @param {String/String[]} className The CSS class to add, or an array of classes
 481      * @return {Ext.draw.Sprite} this
 482      */
 483     addCls: function(obj) {
 484         this.surface.addCls(this, obj);
 485         return this;
 486     },
 487
 488 <span id='Ext-draw-Sprite-method-removeCls'>    /**
 489 </span>     * Removes one or more CSS classes from the element.
 490      * @param {String/String[]} className The CSS class to remove, or an array of classes.  Note this method
 491      * is severly limited in VML.
 492      * @return {Ext.draw.Sprite} this
 493      */
 494     removeCls: function(obj) {
 495         this.surface.removeCls(this, obj);
 496         return this;
 497     }
 498 });
 499 </pre>
 500 </body>
 501 </html>