/ext-4.1.0_b3/docs/source/Animate.html
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 `"to"`
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>