docs/source/Anim.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-Anim'>/**
  19 </span> * @class Ext.fx.Anim
  20  *
  21  * This class manages animation for a specific {@link #target}. The animation allows
  22  * animation of various properties on the target, such as size, position, color and others.
  23  *
  24  * ## Starting Conditions
  25  * The starting conditions for the animation are provided by the {@link #from} configuration.
  26  * Any/all of the properties in the {@link #from} configuration can be specified. If a particular
  27  * property is not defined, the starting value for that property will be read directly from the target.
  28  *
  29  * ## End Conditions
  30  * The ending conditions for the animation are provided by the {@link #to} configuration. These mark
  31  * the final values once the animations has finished. The values in the {@link #from} can mirror
  32  * those in the {@link #to} configuration to provide a starting point.
  33  *
  34  * ## Other Options
  35  *  - {@link #duration}: Specifies the time period of the animation.
  36  *  - {@link #easing}: Specifies the easing of the animation.
  37  *  - {@link #iterations}: Allows the animation to repeat a number of times.
  38  *  - {@link #alternate}: Used in conjunction with {@link #iterations}, reverses the direction every second iteration.
  39  *
  40  * ## Example Code
  41  *
  42  *     var myComponent = Ext.create('Ext.Component', {
  43  *         renderTo: document.body,
  44  *         width: 200,
  45  *         height: 200,
  46  *         style: 'border: 1px solid red;'
  47  *     });
  48  *
  49  *     new Ext.fx.Anim({
  50  *         target: myComponent,
  51  *         duration: 1000,
  52  *         from: {
  53  *             width: 400 //starting width 400
  54  *         },
  55  *         to: {
  56  *             width: 300, //end width 300
  57  *             height: 300 // end width 300
  58  *         }
  59  *     });
  60  */
  61 Ext.define('Ext.fx.Anim', {
  62
  63     /* Begin Definitions */
  64
  65     mixins: {
  66         observable: 'Ext.util.Observable'
  67     },
  68
  69     requires: ['Ext.fx.Manager', 'Ext.fx.Animator', 'Ext.fx.Easing', 'Ext.fx.CubicBezier', 'Ext.fx.PropertyHandler'],
  70
  71     /* End Definitions */
  72
  73     isAnimation: true,
  74 <span id='Ext-fx-Anim-cfg-duration'>    /**
  75 </span>     * @cfg {Number} duration
  76      * Time in milliseconds for a single animation to last. Defaults to 250. If the {@link #iterations} property is
  77      * specified, then each animate will take the same duration for each iteration.
  78      */
  79     duration: 250,
  80
  81 <span id='Ext-fx-Anim-cfg-delay'>    /**
  82 </span>     * @cfg {Number} delay
  83      * Time to delay before starting the animation. Defaults to 0.
  84      */
  85     delay: 0,
  86
  87     /* private used to track a delayed starting time */
  88     delayStart: 0,
  89
  90 <span id='Ext-fx-Anim-cfg-dynamic'>    /**
  91 </span>     * @cfg {Boolean} dynamic
  92      * 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.
  93      */
  94     dynamic: false,
  95
  96 <span id='Ext-fx-Anim-cfg-easing'>    /**
  97 </span>     * @cfg {String} easing
  98 This describes how the intermediate values used during a transition will be calculated. It allows for a transition to change
  99 speed over its duration.
 100
 101          -backIn
 102          -backOut
 103          -bounceIn
 104          -bounceOut
 105          -ease
 106          -easeIn
 107          -easeOut
 108          -easeInOut
 109          -elasticIn
 110          -elasticOut
 111          -cubic-bezier(x1, y1, x2, y2)
 112
 113 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
 114 as (x1, y1, x2, y2). All values must be in the range [0, 1] or the definition is invalid.
 115      * @markdown
 116      */
 117     easing: 'ease',
 118
 119 <span id='Ext-fx-Anim-cfg-keyframes'>     /**
 120 </span>      * @cfg {Object} keyframes
 121       * Animation keyframes follow the CSS3 Animation configuration pattern. 'from' is always considered '0%' and 'to'
 122       * is considered '100%'.&lt;b&gt;Every keyframe declaration must have a keyframe rule for 0% and 100%, possibly defined using
 123       * &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
 124       * animation.  The keyframe declaration for a keyframe rule consists of properties and values. Properties that are unable to
 125       * be animated are ignored in these rules, with the exception of 'easing' which can be changed at each keyframe. For example:
 126  &lt;pre&gt;&lt;code&gt;
 127 keyframes : {
 128     '0%': {
 129         left: 100
 130     },
 131     '40%': {
 132         left: 150
 133     },
 134     '60%': {
 135         left: 75
 136     },
 137     '100%': {
 138         left: 100
 139     }
 140 }
 141  &lt;/code&gt;&lt;/pre&gt;
 142       */
 143
 144 <span id='Ext-fx-Anim-property-damper'>    /**
 145 </span>     * @private
 146      */
 147     damper: 1,
 148
 149 <span id='Ext-fx-Anim-property-bezierRE'>    /**
 150 </span>     * @private
 151      */
 152     bezierRE: /^(?:cubic-)?bezier\(([^,]+),([^,]+),([^,]+),([^\)]+)\)/,
 153
 154 <span id='Ext-fx-Anim-cfg-reverse'>    /**
 155 </span>     * Run the animation from the end to the beginning
 156      * Defaults to false.
 157      * @cfg {Boolean} reverse
 158      */
 159     reverse: false,
 160
 161 <span id='Ext-fx-Anim-property-running'>    /**
 162 </span>     * Flag to determine if the animation has started
 163      * @property running
 164      * @type boolean
 165      */
 166     running: false,
 167
 168 <span id='Ext-fx-Anim-property-paused'>    /**
 169 </span>     * Flag to determine if the animation is paused. Only set this to true if you need to
 170      * keep the Anim instance around to be unpaused later; otherwise call {@link #end}.
 171      * @property paused
 172      * @type boolean
 173      */
 174     paused: false,
 175
 176 <span id='Ext-fx-Anim-cfg-iterations'>    /**
 177 </span>     * Number of times to execute the animation. Defaults to 1.
 178      * @cfg {int} iterations
 179      */
 180     iterations: 1,
 181
 182 <span id='Ext-fx-Anim-cfg-alternate'>    /**
 183 </span>     * Used in conjunction with iterations to reverse the animation each time an iteration completes.
 184      * @cfg {Boolean} alternate
 185      * Defaults to false.
 186      */
 187     alternate: false,
 188
 189 <span id='Ext-fx-Anim-property-currentIteration'>    /**
 190 </span>     * Current iteration the animation is running.
 191      * @property currentIteration
 192      * @type int
 193      */
 194     currentIteration: 0,
 195
 196 <span id='Ext-fx-Anim-property-startTime'>    /**
 197 </span>     * Starting time of the animation.
 198      * @property startTime
 199      * @type Date
 200      */
 201     startTime: 0,
 202
 203 <span id='Ext-fx-Anim-property-propHandlers'>    /**
 204 </span>     * Contains a cache of the interpolators to be used.
 205      * @private
 206      * @property propHandlers
 207      * @type Object
 208      */
 209
 210 <span id='Ext-fx-Anim-cfg-target'>    /**
 211 </span>     * @cfg {String/Object} target
 212      * The {@link Ext.fx.target.Target} to apply the animation to.  This should only be specified when creating an Ext.fx.Anim directly.
 213      * The target does not need to be a {@link Ext.fx.target.Target} instance, it can be the underlying object. For example, you can
 214      * pass a Component, Element or Sprite as the target and the Anim will create the appropriate {@link Ext.fx.target.Target} object
 215      * automatically.
 216      */
 217
 218 <span id='Ext-fx-Anim-cfg-from'>    /**
 219 </span>     * @cfg {Object} from
 220      * An object containing property/value pairs for the beginning of the animation.  If not specified, the current state of the
 221      * Ext.fx.target will be used. For example:
 222 &lt;pre&gt;&lt;code&gt;
 223 from : {
 224     opacity: 0,       // Transparent
 225     color: '#ffffff', // White
 226     left: 0
 227 }
 228 &lt;/code&gt;&lt;/pre&gt;
 229      */
 230
 231 <span id='Ext-fx-Anim-cfg-to'>    /**
 232 </span>     * @cfg {Object} to
 233      * An object containing property/value pairs for the end of the animation. For example:
 234  &lt;pre&gt;&lt;code&gt;
 235  to : {
 236      opacity: 1,       // Opaque
 237      color: '#00ff00', // Green
 238      left: 500
 239  }
 240  &lt;/code&gt;&lt;/pre&gt;
 241      */
 242
 243     // @private
 244     constructor: function(config) {
 245         var me = this;
 246         config = config || {};
 247         // If keyframes are passed, they really want an Animator instead.
 248         if (config.keyframes) {
 249             return Ext.create('Ext.fx.Animator', config);
 250         }
 251         config = Ext.apply(me, config);
 252         if (me.from === undefined) {
 253             me.from = {};
 254         }
 255         me.propHandlers = {};
 256         me.config = config;
 257         me.target = Ext.fx.Manager.createTarget(me.target);
 258         me.easingFn = Ext.fx.Easing[me.easing];
 259         me.target.dynamic = me.dynamic;
 260
 261         // If not a pre-defined curve, try a cubic-bezier
 262         if (!me.easingFn) {
 263             me.easingFn = String(me.easing).match(me.bezierRE);
 264             if (me.easingFn &amp;&amp; me.easingFn.length == 5) {
 265                 var curve = me.easingFn;
 266                 me.easingFn = Ext.fx.cubicBezier(+curve[1], +curve[2], +curve[3], +curve[4]);
 267             }
 268         }
 269         me.id = Ext.id(null, 'ext-anim-');
 270         Ext.fx.Manager.addAnim(me);
 271         me.addEvents(
 272 <span id='Ext-fx-Anim-event-beforeanimate'>            /**
 273 </span>             * @event beforeanimate
 274              * Fires before the animation starts. A handler can return false to cancel the animation.
 275              * @param {Ext.fx.Anim} this
 276              */
 277             'beforeanimate',
 278 <span id='Ext-fx-Anim-event-afteranimate'>             /**
 279 </span>              * @event afteranimate
 280               * Fires when the animation is complete.
 281               * @param {Ext.fx.Anim} this
 282               * @param {Date} startTime
 283               */
 284             'afteranimate',
 285 <span id='Ext-fx-Anim-event-lastframe'>             /**
 286 </span>              * @event lastframe
 287               * Fires when the animation's last frame has been set.
 288               * @param {Ext.fx.Anim} this
 289               * @param {Date} startTime
 290               */
 291             'lastframe'
 292         );
 293         me.mixins.observable.constructor.call(me, config);
 294         if (config.callback) {
 295             me.on('afteranimate', config.callback, config.scope);
 296         }
 297         return me;
 298     },
 299
 300 <span id='Ext-fx-Anim-method-setAttr'>    /**
 301 </span>     * @private
 302      * Helper to the target
 303      */
 304     setAttr: function(attr, value) {
 305         return Ext.fx.Manager.items.get(this.id).setAttr(this.target, attr, value);
 306     },
 307
 308     /*
 309      * @private
 310      * Set up the initial currentAttrs hash.
 311      */
 312     initAttrs: function() {
 313         var me = this,
 314             from = me.from,
 315             to = me.to,
 316             initialFrom = me.initialFrom || {},
 317             out = {},
 318             start, end, propHandler, attr;
 319
 320         for (attr in to) {
 321             if (to.hasOwnProperty(attr)) {
 322                 start = me.target.getAttr(attr, from[attr]);
 323                 end = to[attr];
 324                 // Use default (numeric) property handler
 325                 if (!Ext.fx.PropertyHandler[attr]) {
 326                     if (Ext.isObject(end)) {
 327                         propHandler = me.propHandlers[attr] = Ext.fx.PropertyHandler.object;
 328                     } else {
 329                         propHandler = me.propHandlers[attr] = Ext.fx.PropertyHandler.defaultHandler;
 330                     }
 331                 }
 332                 // Use custom handler
 333                 else {
 334                     propHandler = me.propHandlers[attr] = Ext.fx.PropertyHandler[attr];
 335                 }
 336                 out[attr] = propHandler.get(start, end, me.damper, initialFrom[attr], attr);
 337             }
 338         }
 339         me.currentAttrs = out;
 340     },
 341
 342     /*
 343      * @private
 344      * Fires beforeanimate and sets the running flag.
 345      */
 346     start: function(startTime) {
 347         var me = this,
 348             delay = me.delay,
 349             delayStart = me.delayStart,
 350             delayDelta;
 351         if (delay) {
 352             if (!delayStart) {
 353                 me.delayStart = startTime;
 354                 return;
 355             }
 356             else {
 357                 delayDelta = startTime - delayStart;
 358                 if (delayDelta &lt; delay) {
 359                     return;
 360                 }
 361                 else {
 362                     // Compensate for frame delay;
 363                     startTime = new Date(delayStart.getTime() + delay);
 364                 }
 365             }
 366         }
 367         if (me.fireEvent('beforeanimate', me) !== false) {
 368             me.startTime = startTime;
 369             if (!me.paused &amp;&amp; !me.currentAttrs) {
 370                 me.initAttrs();
 371             }
 372             me.running = true;
 373         }
 374     },
 375
 376     /*
 377      * @private
 378      * Calculate attribute value at the passed timestamp.
 379      * @returns a hash of the new attributes.
 380      */
 381     runAnim: function(elapsedTime) {
 382         var me = this,
 383             attrs = me.currentAttrs,
 384             duration = me.duration,
 385             easingFn = me.easingFn,
 386             propHandlers = me.propHandlers,
 387             ret = {},
 388             easing, values, attr, lastFrame;
 389
 390         if (elapsedTime &gt;= duration) {
 391             elapsedTime = duration;
 392             lastFrame = true;
 393         }
 394         if (me.reverse) {
 395             elapsedTime = duration - elapsedTime;
 396         }
 397
 398         for (attr in attrs) {
 399             if (attrs.hasOwnProperty(attr)) {
 400                 values = attrs[attr];
 401                 easing = lastFrame ? 1 : easingFn(elapsedTime / duration);
 402                 ret[attr] = propHandlers[attr].set(values, easing);
 403             }
 404         }
 405         return ret;
 406     },
 407
 408     /*
 409      * @private
 410      * Perform lastFrame cleanup and handle iterations
 411      * @returns a hash of the new attributes.
 412      */
 413     lastFrame: function() {
 414         var me = this,
 415             iter = me.iterations,
 416             iterCount = me.currentIteration;
 417
 418         iterCount++;
 419         if (iterCount &lt; iter) {
 420             if (me.alternate) {
 421                 me.reverse = !me.reverse;
 422             }
 423             me.startTime = new Date();
 424             me.currentIteration = iterCount;
 425             // Turn off paused for CSS3 Transitions
 426             me.paused = false;
 427         }
 428         else {
 429             me.currentIteration = 0;
 430             me.end();
 431             me.fireEvent('lastframe', me, me.startTime);
 432         }
 433     },
 434
 435     /*
 436      * Fire afteranimate event and end the animation. Usually called automatically when the
 437      * animation reaches its final frame, but can also be called manually to pre-emptively
 438      * stop and destroy the running animation.
 439      */
 440     end: function() {
 441         var me = this;
 442         me.startTime = 0;
 443         me.paused = false;
 444         me.running = false;
 445         Ext.fx.Manager.removeAnim(me);
 446         me.fireEvent('afteranimate', me, me.startTime);
 447     }
 448 });
 449 // Set flag to indicate that Fx is available. Class might not be available immediately.
 450 Ext.enableFx = true;
 451 </pre>
 452 </body>
 453 </html>