PageRenderTime 36ms CodeModel.GetById 28ms app.highlight 5ms RepoModel.GetById 0ms app.codeStats 0ms

/ext-4.1.0_b3/docs/source/Animate.html

https://bitbucket.org/srogerf/javascript
HTML | 445 lines | 432 code | 13 blank | 0 comment | 0 complexity | 239e6eb19243ca6ea078425a7202ae24 MD5 | raw file
  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-util-Animate'>/**
 19</span> * This animation class is a mixin.
 20 *
 21 * Ext.util.Animate provides an API for the creation of animated transitions of properties and styles.
 22 * This class is used as a mixin and currently applied to {@link Ext.Element}, {@link Ext.CompositeElement},
 23 * {@link Ext.draw.Sprite}, {@link Ext.draw.CompositeSprite}, and {@link Ext.Component}.  Note that Components
 24 * have a limited subset of what attributes can be animated such as top, left, x, y, height, width, and
 25 * opacity (color, paddings, and margins can not be animated).
 26 *
 27 * ## Animation Basics
 28 *
 29 * All animations require three things - `easing`, `duration`, and `to` (the final end value for each property)
 30 * you wish to animate. Easing and duration are defaulted values specified below.
 31 * Easing describes how the intermediate values used during a transition will be calculated.
 32 * {@link Ext.fx.Anim#easing Easing} allows for a transition to change speed over its duration.
 33 * You may use the defaults for easing and duration, but you must always set a
 34 * {@link Ext.fx.Anim#to to} property which is the end value for all animations.
 35 *
 36 * Popular element 'to' configurations are:
 37 *
 38 *  - opacity
 39 *  - x
 40 *  - y
 41 *  - color
 42 *  - height
 43 *  - width
 44 *
 45 * Popular sprite 'to' configurations are:
 46 *
 47 *  - translation
 48 *  - path
 49 *  - scale
 50 *  - stroke
 51 *  - rotation
 52 *
 53 * The default duration for animations is 250 (which is a 1/4 of a second).  Duration is denoted in
 54 * milliseconds.  Therefore 1 second is 1000, 1 minute would be 60000, and so on. The default easing curve
 55 * used for all animations is 'ease'.  Popular easing functions are included and can be found in {@link Ext.fx.Anim#easing Easing}.
 56 *
 57 * For example, a simple animation to fade out an element with a default easing and duration:
 58 *
 59 *     var p1 = Ext.get('myElementId');
 60 *
 61 *     p1.animate({
 62 *         to: {
 63 *             opacity: 0
 64 *         }
 65 *     });
 66 *
 67 * To make this animation fade out in a tenth of a second:
 68 *
 69 *     var p1 = Ext.get('myElementId');
 70 *
 71 *     p1.animate({
 72 *        duration: 100,
 73 *         to: {
 74 *             opacity: 0
 75 *         }
 76 *     });
 77 *
 78 * ## Animation Queues
 79 *
 80 * By default all animations are added to a queue which allows for animation via a chain-style API.
 81 * For example, the following code will queue 4 animations which occur sequentially (one right after the other):
 82 *
 83 *     p1.animate({
 84 *         to: {
 85 *             x: 500
 86 *         }
 87 *     }).animate({
 88 *         to: {
 89 *             y: 150
 90 *         }
 91 *     }).animate({
 92 *         to: {
 93 *             backgroundColor: '#f00'  //red
 94 *         }
 95 *     }).animate({
 96 *         to: {
 97 *             opacity: 0
 98 *         }
 99 *     });
100 *
101 * You can change this behavior by calling the {@link Ext.util.Animate#syncFx syncFx} method and all
102 * subsequent animations for the specified target will be run concurrently (at the same time).
103 *
104 *     p1.syncFx();  //this will make all animations run at the same time
105 *
106 *     p1.animate({
107 *         to: {
108 *             x: 500
109 *         }
110 *     }).animate({
111 *         to: {
112 *             y: 150
113 *         }
114 *     }).animate({
115 *         to: {
116 *             backgroundColor: '#f00'  //red
117 *         }
118 *     }).animate({
119 *         to: {
120 *             opacity: 0
121 *         }
122 *     });
123 *
124 * This works the same as:
125 *
126 *     p1.animate({
127 *         to: {
128 *             x: 500,
129 *             y: 150,
130 *             backgroundColor: '#f00'  //red
131 *             opacity: 0
132 *         }
133 *     });
134 *
135 * The {@link Ext.util.Animate#stopAnimation stopAnimation} method can be used to stop any
136 * currently running animations and clear any queued animations.
137 *
138 * ## Animation Keyframes
139 *
140 * You can also set up complex animations with {@link Ext.fx.Anim#keyframes keyframes} which follow the
141 * CSS3 Animation configuration pattern. Note rotation, translation, and scaling can only be done for sprites.
142 * The previous example can be written with the following syntax:
143 *
144 *     p1.animate({
145 *         duration: 1000,  //one second total
146 *         keyframes: {
147 *             25: {     //from 0 to 250ms (25%)
148 *                 x: 0
149 *             },
150 *             50: {   //from 250ms to 500ms (50%)
151 *                 y: 0
152 *             },
153 *             75: {  //from 500ms to 750ms (75%)
154 *                 backgroundColor: '#f00'  //red
155 *             },
156 *             100: {  //from 750ms to 1sec
157 *                 opacity: 0
158 *             }
159 *         }
160 *     });
161 *
162 * ## Animation Events
163 *
164 * Each animation you create has events for {@link Ext.fx.Anim#beforeanimate beforeanimate},
165 * {@link Ext.fx.Anim#afteranimate afteranimate}, and {@link Ext.fx.Anim#lastframe lastframe}.
166 * Keyframed animations adds an additional {@link Ext.fx.Animator#keyframe keyframe} event which
167 * fires for each keyframe in your animation.
168 *
169 * All animations support the {@link Ext.util.Observable#listeners listeners} configuration to attact functions to these events.
170 *
171 *     startAnimate: function() {
172 *         var p1 = Ext.get('myElementId');
173 *         p1.animate({
174 *            duration: 100,
175 *             to: {
176 *                 opacity: 0
177 *             },
178 *             listeners: {
179 *                 beforeanimate:  function() {
180 *                     // Execute my custom method before the animation
181 *                     this.myBeforeAnimateFn();
182 *                 },
183 *                 afteranimate: function() {
184 *                     // Execute my custom method after the animation
185 *                     this.myAfterAnimateFn();
186 *                 },
187 *                 scope: this
188 *         });
189 *     },
190 *     myBeforeAnimateFn: function() {
191 *       // My custom logic
192 *     },
193 *     myAfterAnimateFn: function() {
194 *       // My custom logic
195 *     }
196 *
197 * Due to the fact that animations run asynchronously, you can determine if an animation is currently
198 * running on any target by using the {@link Ext.util.Animate#getActiveAnimation getActiveAnimation}
199 * method.  This method will return false if there are no active animations or return the currently
200 * running {@link Ext.fx.Anim} instance.
201 *
202 * In this example, we're going to wait for the current animation to finish, then stop any other
203 * queued animations before we fade our element's opacity to 0:
204 *
205 *     var curAnim = p1.getActiveAnimation();
206 *     if (curAnim) {
207 *         curAnim.on('afteranimate', function() {
208 *             p1.stopAnimation();
209 *             p1.animate({
210 *                 to: {
211 *                     opacity: 0
212 *                 }
213 *             });
214 *         });
215 *     }
216 */
217Ext.define('Ext.util.Animate', {
218
219    uses: ['Ext.fx.Manager', 'Ext.fx.Anim'],
220
221<span id='Ext-util-Animate-method-animate'>    /**
222</span>     * Perform custom animation on this object.
223     *
224     * This method is applicable to both the {@link Ext.Component Component} class and the {@link Ext.Element Element}
225     * class. It performs animated transitions of certain properties of this object over a specified timeline.
226     *
227     * The sole parameter is an object which specifies start property values, end property values, and properties which
228     * describe the timeline. 
229     *
230     * ### Animating an {@link Ext.Element Element}
231     *
232     * When animating an Element, the following properties may be specified in `from`, `to`, and `keyframe` objects:
233     *
234     *   - `x` - The page X position in pixels.
235     *
236     *   - `y` - The page Y position in pixels
237     *
238     *   - `left` - The element's CSS `left` value. Units must be supplied.
239     *
240     *   - `top` - The element's CSS `top` value. Units must be supplied.
241     *
242     *   - `width` - The element's CSS `width` value. Units must be supplied.
243     *
244     *   - `height` - The element's CSS `height` value. Units must be supplied.
245     *
246     *   - `scrollLeft` - The element's `scrollLeft` value.
247     *
248     *   - `scrollTop` - The element's `scrollLeft` value.
249     *
250     *   - `opacity` - The element's `opacity` value. This must be a value between `0` and `1`.
251     *
252     * **Be aware than animating an Element which is being used by an Ext Component without in some way informing the
253     * Component about the changed element state will result in incorrect Component behaviour. This is because the
254     * Component will be using the old state of the element. To avoid this problem, it is now possible to directly
255     * animate certain properties of Components.**
256     *
257     * ### Animating a {@link Ext.Component Component}
258     *
259     * When animating a Component, the following properties may be specified in `from`, `to`, and `keyframe` objects:
260     *
261     *   - `x` - The Component's page X position in pixels.
262     *
263     *   - `y` - The Component's page Y position in pixels
264     *
265     *   - `left` - The Component's `left` value in pixels.
266     *
267     *   - `top` - The Component's `top` value in pixels.
268     *
269     *   - `width` - The Component's `width` value in pixels.
270     *
271     *   - `width` - The Component's `width` value in pixels.
272     *
273     *   - `dynamic` - Specify as true to update the Component's layout (if it is a Container) at every frame of the animation.
274     *     *Use sparingly as laying out on every intermediate size change is an expensive operation.*
275     *
276     * For example, to animate a Window to a new size, ensuring that its internal layout, and any shadow is correct:
277     *
278     *     myWindow = Ext.create('Ext.window.Window', {
279     *         title: 'Test Component animation',
280     *         width: 500,
281     *         height: 300,
282     *         layout: {
283     *             type: 'hbox',
284     *             align: 'stretch'
285     *         },
286     *         items: [{
287     *             title: 'Left: 33%',
288     *             margins: '5 0 5 5',
289     *             flex: 1
290     *         }, {
291     *             title: 'Left: 66%',
292     *             margins: '5 5 5 5',
293     *             flex: 2
294     *         }]
295     *     });
296     *     myWindow.show();
297     *     myWindow.header.el.on('click', function() {
298     *         myWindow.animate({
299     *             to: {
300     *                 width: (myWindow.getWidth() == 500) ? 700 : 500,
301     *                 height: (myWindow.getHeight() == 300) ? 400 : 300,
302     *             }
303     *         });
304     *     });
305     *
306     * For performance reasons, by default, the internal layout is only updated when the Window reaches its final `&quot;to&quot;`
307     * size. If dynamic updating of the Window's child Components is required, then configure the animation with
308     * `dynamic: true` and the two child items will maintain their proportions during the animation.
309     *
310     * @param {Object} config An object containing properties which describe the animation's start and end states, and
311     * the timeline of the animation. Of the properties listed below, only **`to`** is mandatory.
312     * 
313     * Properties include:
314     *
315     * @param {Object} config.from
316     * An object which specifies start values for the properties being animated. If not supplied, properties are
317     * animated from current settings. The actual properties which may be animated depend upon ths object being
318     * animated. See the sections below on Element and Component animation.
319     *
320     * @param {Object} config.to
321     * An object which specifies end values for the properties being animated.
322     *
323     * @param {Number} config.duration
324     * The duration **in milliseconds** for which the animation will run.
325     *
326     * @param {String} config.easing
327     * A string value describing an easing type to modify the rate of change from the default linear to non-linear.
328     * Values may be one of:
329     *
330     *   - ease
331     *   - easeIn
332     *   - easeOut
333     *   - easeInOut
334     *   - backIn
335     *   - backOut
336     *   - elasticIn
337     *   - elasticOut
338     *   - bounceIn
339     *   - bounceOut
340     *
341     * @param {Object} config.keyframes
342     * This is an object which describes the state of animated properties at certain points along the timeline. it is an
343     * object containing properties who's names are the percentage along the timeline being described and who's values
344     * specify the animation state at that point.
345     *
346     * @param {Object} config.listeners
347     * This is a standard {@link Ext.util.Observable#listeners listeners} configuration object which may be used to
348     * inject behaviour at either the `beforeanimate` event or the `afteranimate` event.
349     *
350     * @return {Object} this
351     */
352    animate: function(animObj) {
353        var me = this;
354        if (Ext.fx.Manager.hasFxBlock(me.id)) {
355            return me;
356        }
357        Ext.fx.Manager.queueFx(new Ext.fx.Anim(me.anim(animObj)));
358        return this;
359    },
360
361    // @private - process the passed fx configuration.
362    anim: function(config) {
363        if (!Ext.isObject(config)) {
364            return (config) ? {} : false;
365        }
366
367        var me = this;
368
369        if (config.stopAnimation) {
370            me.stopAnimation();
371        }
372
373        Ext.applyIf(config, Ext.fx.Manager.getFxDefaults(me.id));
374
375        return Ext.apply({
376            target: me,
377            paused: true
378        }, config);
379    },
380
381<span id='Ext-util-Animate-method-stopFx'>    /**
382</span>     * Stops any running effects and clears this object's internal effects queue if it contains any additional effects
383     * that haven't started yet.
384     * @deprecated 4.0 Replaced by {@link #stopAnimation}
385     * @return {Ext.Element} The Element
386     * @method
387     */
388    stopFx: Ext.Function.alias(Ext.util.Animate, 'stopAnimation'),
389
390<span id='Ext-util-Animate-method-stopAnimation'>    /**
391</span>     * Stops any running effects and clears this object's internal effects queue if it contains any additional effects
392     * that haven't started yet.
393     * @return {Ext.Element} The Element
394     */
395    stopAnimation: function() {
396        Ext.fx.Manager.stopAnimation(this.id);
397        return this;
398    },
399
400<span id='Ext-util-Animate-method-syncFx'>    /**
401</span>     * Ensures that all effects queued after syncFx is called on this object are run concurrently. This is the opposite
402     * of {@link #sequenceFx}.
403     * @return {Object} this
404     */
405    syncFx: function() {
406        Ext.fx.Manager.setFxDefaults(this.id, {
407            concurrent: true
408        });
409        return this;
410    },
411
412<span id='Ext-util-Animate-method-sequenceFx'>    /**
413</span>     * Ensures that all effects queued after sequenceFx is called on this object are run in sequence. This is the
414     * opposite of {@link #syncFx}.
415     * @return {Object} this
416     */
417    sequenceFx: function() {
418        Ext.fx.Manager.setFxDefaults(this.id, {
419            concurrent: false
420        });
421        return this;
422    },
423
424<span id='Ext-util-Animate-method-hasActiveFx'>    /**
425</span>     * @deprecated 4.0 Replaced by {@link #getActiveAnimation}
426     * @inheritdoc Ext.util.Animate#getActiveAnimation
427     * @method
428     */
429    hasActiveFx: Ext.Function.alias(Ext.util.Animate, 'getActiveAnimation'),
430
431<span id='Ext-util-Animate-method-getActiveAnimation'>    /**
432</span>     * Returns the current animation if this object has any effects actively running or queued, else returns false.
433     * @return {Ext.fx.Anim/Boolean} Anim if element has active effects, else false
434     */
435    getActiveAnimation: function() {
436        return Ext.fx.Manager.getActiveAnimation(this.id);
437    }
438}, function(){
439    // Apply Animate mixin manually until Element is defined in the proper 4.x way
440    Ext.applyIf(Ext.Element.prototype, this.prototype);
441    // We need to call this again so the animation methods get copied over to CE
442    Ext.CompositeElementLite.importElementMethods();
443});</pre>
444</body>
445</html>