docs/source/Animator.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="../prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../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-fx-Animator'>/**
  19 </span> * @class Ext.fx.Animator
  20  * Animation instance
  21
  22 This class is used to run keyframe based animations, which follows the CSS3 based animation structure.
  23 Keyframe animations differ from typical from/to animations in that they offer the ability to specify values
  24 at various points throughout the animation.
  25
  26 __Using Keyframes__
  27 The {@link #keyframes} option is the most important part of specifying an animation when using this
  28 class. A key frame is a point in a particular animation. We represent this as a percentage of the
  29 total animation duration. At each key frame, we can specify the target values at that time. Note that
  30 you *must* specify the values at 0% and 100%, the start and ending values. There is also a {@link keyframe}
  31 event that fires after each key frame is reached.
  32
  33 __Example Usage__
  34 In the example below, we modify the values of the element at each fifth throughout the animation.
  35
  36     Ext.create('Ext.fx.Animator', {
  37         target: Ext.getBody().createChild({
  38             style: {
  39                 width: '100px',
  40                 height: '100px',
  41                 'background-color': 'red'
  42             }
  43         }),
  44         duration: 10000, // 10 seconds
  45         keyframes: {
  46             0: {
  47                 opacity: 1,
  48                 backgroundColor: 'FF0000'
  49             },
  50             20: {
  51                 x: 30,
  52                 opacity: 0.5
  53             },
  54             40: {
  55                 x: 130,
  56                 backgroundColor: '0000FF'
  57             },
  58             60: {
  59                 y: 80,
  60                 opacity: 0.3
  61             },
  62             80: {
  63                 width: 200,
  64                 y: 200
  65             },
  66             100: {
  67                 opacity: 1,
  68                 backgroundColor: '00FF00'
  69             }
  70         }
  71     });
  72
  73  * @markdown
  74  */
  75 Ext.define('Ext.fx.Animator', {
  76
  77     /* Begin Definitions */
  78
  79     mixins: {
  80         observable: 'Ext.util.Observable'
  81     },
  82
  83     requires: ['Ext.fx.Manager'],
  84
  85     /* End Definitions */
  86
  87     isAnimator: true,
  88
  89 <span id='Ext-fx-Animator-cfg-duration'>    /**
  90 </span>     * @cfg {Number} duration
  91      * Time in milliseconds for the animation to last. Defaults to 250.
  92      */
  93     duration: 250,
  94
  95 <span id='Ext-fx-Animator-cfg-delay'>    /**
  96 </span>     * @cfg {Number} delay
  97      * Time to delay before starting the animation. Defaults to 0.
  98      */
  99     delay: 0,
 100
 101     /* private used to track a delayed starting time */
 102     delayStart: 0,
 103
 104 <span id='Ext-fx-Animator-cfg-dynamic'>    /**
 105 </span>     * @cfg {Boolean} dynamic
 106      * Currently only for Component Animation: Only set a component's outer element size bypassing layouts.  Set to true to do full layouts for every frame of the animation.  Defaults to false.
 107      */
 108     dynamic: false,
 109
 110 <span id='Ext-fx-Animator-cfg-easing'>    /**
 111 </span>     * @cfg {String} easing
 112
 113 This describes how the intermediate values used during a transition will be calculated. It allows for a transition to change
 114 speed over its duration.
 115
 116 - backIn
 117 - backOut
 118 - bounceIn
 119 - bounceOut
 120 - ease
 121 - easeIn
 122 - easeOut
 123 - easeInOut
 124 - elasticIn
 125 - elasticOut
 126 - cubic-bezier(x1, y1, x2, y2)
 127
 128 Note that cubic-bezier will create a custom easing curve following the CSS3 transition-timing-function specification `{@link http://www.w3.org/TR/css3-transitions/#transition-timing-function_tag}`. The four values specify points P1 and P2 of the curve
 129 as (x1, y1, x2, y2). All values must be in the range [0, 1] or the definition is invalid.
 130
 131      * @markdown
 132      */
 133     easing: 'ease',
 134
 135 <span id='Ext-fx-Animator-property-running'>    /**
 136 </span>     * Flag to determine if the animation has started
 137      * @property running
 138      * @type boolean
 139      */
 140     running: false,
 141
 142 <span id='Ext-fx-Animator-property-paused'>    /**
 143 </span>     * Flag to determine if the animation is paused. Only set this to true if you need to
 144      * keep the Anim instance around to be unpaused later; otherwise call {@link #end}.
 145      * @property paused
 146      * @type boolean
 147      */
 148     paused: false,
 149
 150 <span id='Ext-fx-Animator-property-damper'>    /**
 151 </span>     * @private
 152      */
 153     damper: 1,
 154
 155 <span id='Ext-fx-Animator-cfg-iterations'>    /**
 156 </span>     * @cfg {Number} iterations
 157      * Number of times to execute the animation. Defaults to 1.
 158      */
 159     iterations: 1,
 160
 161 <span id='Ext-fx-Animator-property-currentIteration'>    /**
 162 </span>     * Current iteration the animation is running.
 163      * @property currentIteration
 164      * @type int
 165      */
 166     currentIteration: 0,
 167
 168 <span id='Ext-fx-Animator-property-keyframeStep'>    /**
 169 </span>     * Current keyframe step of the animation.
 170      * @property keyframeStep
 171      * @type Number
 172      */
 173     keyframeStep: 0,
 174
 175 <span id='Ext-fx-Animator-property-animKeyFramesRE'>    /**
 176 </span>     * @private
 177      */
 178     animKeyFramesRE: /^(from|to|\d+%?)$/,
 179
 180 <span id='Ext-fx-Animator-cfg-target'>    /**
 181 </span>     * @cfg {Ext.fx.target} target
 182      * The Ext.fx.target to apply the animation to.  If not specified during initialization, this can be passed to the applyAnimator
 183      * method to apply the same animation to many targets.
 184      */
 185
 186 <span id='Ext-fx-Animator-cfg-keyframes'>     /**
 187 </span>      * @cfg {Object} keyframes
 188       * Animation keyframes follow the CSS3 Animation configuration pattern. 'from' is always considered '0%' and 'to'
 189       * is considered '100%'.&lt;b&gt;Every keyframe declaration must have a keyframe rule for 0% and 100%, possibly defined using
 190       * &quot;from&quot; or &quot;to&quot;&lt;/b&gt;.  A keyframe declaration without these keyframe selectors is invalid and will not be available for
 191       * animation.  The keyframe declaration for a keyframe rule consists of properties and values. Properties that are unable to
 192       * be animated are ignored in these rules, with the exception of 'easing' which can be changed at each keyframe. For example:
 193  &lt;pre&gt;&lt;code&gt;
 194 keyframes : {
 195     '0%': {
 196         left: 100
 197     },
 198     '40%': {
 199         left: 150
 200     },
 201     '60%': {
 202         left: 75
 203     },
 204     '100%': {
 205         left: 100
 206     }
 207 }
 208  &lt;/code&gt;&lt;/pre&gt;
 209       */
 210     constructor: function(config) {
 211         var me = this;
 212         config = Ext.apply(me, config || {});
 213         me.config = config;
 214         me.id = Ext.id(null, 'ext-animator-');
 215         me.addEvents(
 216 <span id='Ext-fx-Animator-event-beforeanimate'>            /**
 217 </span>             * @event beforeanimate
 218              * Fires before the animation starts. A handler can return false to cancel the animation.
 219              * @param {Ext.fx.Animator} this
 220              */
 221             'beforeanimate',
 222 <span id='Ext-fx-Animator-event-keyframe'>            /**
 223 </span>              * @event keyframe
 224               * Fires at each keyframe.
 225               * @param {Ext.fx.Animator} this
 226               * @param {Number} keyframe step number
 227               */
 228             'keyframe',
 229 <span id='Ext-fx-Animator-event-afteranimate'>            /**
 230 </span>             * @event afteranimate
 231              * Fires when the animation is complete.
 232              * @param {Ext.fx.Animator} this
 233              * @param {Date} startTime
 234              */
 235             'afteranimate'
 236         );
 237         me.mixins.observable.constructor.call(me, config);
 238         me.timeline = [];
 239         me.createTimeline(me.keyframes);
 240         if (me.target) {
 241             me.applyAnimator(me.target);
 242             Ext.fx.Manager.addAnim(me);
 243         }
 244     },
 245
 246 <span id='Ext-fx-Animator-method-sorter'>    /**
 247 </span>     * @private
 248      */
 249     sorter: function (a, b) {
 250         return a.pct - b.pct;
 251     },
 252
 253 <span id='Ext-fx-Animator-method-createTimeline'>    /**
 254 </span>     * @private
 255      * Takes the given keyframe configuration object and converts it into an ordered array with the passed attributes per keyframe
 256      * or applying the 'to' configuration to all keyframes.  Also calculates the proper animation duration per keyframe.
 257      */
 258     createTimeline: function(keyframes) {
 259         var me = this,
 260             attrs = [],
 261             to = me.to || {},
 262             duration = me.duration,
 263             prevMs, ms, i, ln, pct, anim, nextAnim, attr;
 264
 265         for (pct in keyframes) {
 266             if (keyframes.hasOwnProperty(pct) &amp;&amp; me.animKeyFramesRE.test(pct)) {
 267                 attr = {attrs: Ext.apply(keyframes[pct], to)};
 268                 // CSS3 spec allow for from/to to be specified.
 269                 if (pct == &quot;from&quot;) {
 270                     pct = 0;
 271                 }
 272                 else if (pct == &quot;to&quot;) {
 273                     pct = 100;
 274                 }
 275                 // convert % values into integers
 276                 attr.pct = parseInt(pct, 10);
 277                 attrs.push(attr);
 278             }
 279         }
 280         // Sort by pct property
 281         Ext.Array.sort(attrs, me.sorter);
 282         // Only an end
 283         //if (attrs[0].pct) {
 284         //    attrs.unshift({pct: 0, attrs: element.attrs});
 285         //}
 286
 287         ln = attrs.length;
 288         for (i = 0; i &lt; ln; i++) {
 289             prevMs = (attrs[i - 1]) ? duration * (attrs[i - 1].pct / 100) : 0;
 290             ms = duration * (attrs[i].pct / 100);
 291             me.timeline.push({
 292                 duration: ms - prevMs,
 293                 attrs: attrs[i].attrs
 294             });
 295         }
 296     },
 297
 298 <span id='Ext-fx-Animator-property-applyAnimator'>    /**
 299 </span>     * Applies animation to the Ext.fx.target
 300      * @private
 301      * @param target
 302      * @type string/object
 303      */
 304     applyAnimator: function(target) {
 305         var me = this,
 306             anims = [],
 307             timeline = me.timeline,
 308             reverse = me.reverse,
 309             ln = timeline.length,
 310             anim, easing, damper, initial, attrs, lastAttrs, i;
 311
 312         if (me.fireEvent('beforeanimate', me) !== false) {
 313             for (i = 0; i &lt; ln; i++) {
 314                 anim = timeline[i];
 315                 attrs = anim.attrs;
 316                 easing = attrs.easing || me.easing;
 317                 damper = attrs.damper || me.damper;
 318                 delete attrs.easing;
 319                 delete attrs.damper;
 320                 anim = Ext.create('Ext.fx.Anim', {
 321                     target: target,
 322                     easing: easing,
 323                     damper: damper,
 324                     duration: anim.duration,
 325                     paused: true,
 326                     to: attrs
 327                 });
 328                 anims.push(anim);
 329             }
 330             me.animations = anims;
 331             me.target = anim.target;
 332             for (i = 0; i &lt; ln - 1; i++) {
 333                 anim = anims[i];
 334                 anim.nextAnim = anims[i + 1];
 335                 anim.on('afteranimate', function() {
 336                     this.nextAnim.paused = false;
 337                 });
 338                 anim.on('afteranimate', function() {
 339                     this.fireEvent('keyframe', this, ++this.keyframeStep);
 340                 }, me);
 341             }
 342             anims[ln - 1].on('afteranimate', function() {
 343                 this.lastFrame();
 344             }, me);
 345         }
 346     },
 347
 348     /*
 349      * @private
 350      * Fires beforeanimate and sets the running flag.
 351      */
 352     start: function(startTime) {
 353         var me = this,
 354             delay = me.delay,
 355             delayStart = me.delayStart,
 356             delayDelta;
 357         if (delay) {
 358             if (!delayStart) {
 359                 me.delayStart = startTime;
 360                 return;
 361             }
 362             else {
 363                 delayDelta = startTime - delayStart;
 364                 if (delayDelta &lt; delay) {
 365                     return;
 366                 }
 367                 else {
 368                     // Compensate for frame delay;
 369                     startTime = new Date(delayStart.getTime() + delay);
 370                 }
 371             }
 372         }
 373         if (me.fireEvent('beforeanimate', me) !== false) {
 374             me.startTime = startTime;
 375             me.running = true;
 376             me.animations[me.keyframeStep].paused = false;
 377         }
 378     },
 379
 380     /*
 381      * @private
 382      * Perform lastFrame cleanup and handle iterations
 383      * @returns a hash of the new attributes.
 384      */
 385     lastFrame: function() {
 386         var me = this,
 387             iter = me.iterations,
 388             iterCount = me.currentIteration;
 389
 390         iterCount++;
 391         if (iterCount &lt; iter) {
 392             me.startTime = new Date();
 393             me.currentIteration = iterCount;
 394             me.keyframeStep = 0;
 395             me.applyAnimator(me.target);
 396             me.animations[me.keyframeStep].paused = false;
 397         }
 398         else {
 399             me.currentIteration = 0;
 400             me.end();
 401         }
 402     },
 403
 404     /*
 405      * Fire afteranimate event and end the animation. Usually called automatically when the
 406      * animation reaches its final frame, but can also be called manually to pre-emptively
 407      * stop and destroy the running animation.
 408      */
 409     end: function() {
 410         var me = this;
 411         me.fireEvent('afteranimate', me, me.startTime, new Date() - me.startTime);
 412     }
 413 });</pre>
 414 </body>
 415 </html>