/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. */
  217. Ext.define('Ext.util.Animate', {
  218. uses: ['Ext.fx.Manager', 'Ext.fx.Anim'],
  219. <span id='Ext-util-Animate-method-animate'> /**
  220. </span> * Perform custom animation on this object.
  221. *
  222. * This method is applicable to both the {@link Ext.Component Component} class and the {@link Ext.Element Element}
  223. * class. It performs animated transitions of certain properties of this object over a specified timeline.
  224. *
  225. * The sole parameter is an object which specifies start property values, end property values, and properties which
  226. * describe the timeline.
  227. *
  228. * ### Animating an {@link Ext.Element Element}
  229. *
  230. * When animating an Element, the following properties may be specified in `from`, `to`, and `keyframe` objects:
  231. *
  232. * - `x` - The page X position in pixels.
  233. *
  234. * - `y` - The page Y position in pixels
  235. *
  236. * - `left` - The element's CSS `left` value. Units must be supplied.
  237. *
  238. * - `top` - The element's CSS `top` value. Units must be supplied.
  239. *
  240. * - `width` - The element's CSS `width` value. Units must be supplied.
  241. *
  242. * - `height` - The element's CSS `height` value. Units must be supplied.
  243. *
  244. * - `scrollLeft` - The element's `scrollLeft` value.
  245. *
  246. * - `scrollTop` - The element's `scrollLeft` value.
  247. *
  248. * - `opacity` - The element's `opacity` value. This must be a value between `0` and `1`.
  249. *
  250. * **Be aware than animating an Element which is being used by an Ext Component without in some way informing the
  251. * Component about the changed element state will result in incorrect Component behaviour. This is because the
  252. * Component will be using the old state of the element. To avoid this problem, it is now possible to directly
  253. * animate certain properties of Components.**
  254. *
  255. * ### Animating a {@link Ext.Component Component}
  256. *
  257. * When animating a Component, the following properties may be specified in `from`, `to`, and `keyframe` objects:
  258. *
  259. * - `x` - The Component's page X position in pixels.
  260. *
  261. * - `y` - The Component's page Y position in pixels
  262. *
  263. * - `left` - The Component's `left` value in pixels.
  264. *
  265. * - `top` - The Component's `top` value in pixels.
  266. *
  267. * - `width` - The Component's `width` value in pixels.
  268. *
  269. * - `width` - The Component's `width` value in pixels.
  270. *
  271. * - `dynamic` - Specify as true to update the Component's layout (if it is a Container) at every frame of the animation.
  272. * *Use sparingly as laying out on every intermediate size change is an expensive operation.*
  273. *
  274. * For example, to animate a Window to a new size, ensuring that its internal layout, and any shadow is correct:
  275. *
  276. * myWindow = Ext.create('Ext.window.Window', {
  277. * title: 'Test Component animation',
  278. * width: 500,
  279. * height: 300,
  280. * layout: {
  281. * type: 'hbox',
  282. * align: 'stretch'
  283. * },
  284. * items: [{
  285. * title: 'Left: 33%',
  286. * margins: '5 0 5 5',
  287. * flex: 1
  288. * }, {
  289. * title: 'Left: 66%',
  290. * margins: '5 5 5 5',
  291. * flex: 2
  292. * }]
  293. * });
  294. * myWindow.show();
  295. * myWindow.header.el.on('click', function() {
  296. * myWindow.animate({
  297. * to: {
  298. * width: (myWindow.getWidth() == 500) ? 700 : 500,
  299. * height: (myWindow.getHeight() == 300) ? 400 : 300,
  300. * }
  301. * });
  302. * });
  303. *
  304. * For performance reasons, by default, the internal layout is only updated when the Window reaches its final `&quot;to&quot;`
  305. * size. If dynamic updating of the Window's child Components is required, then configure the animation with
  306. * `dynamic: true` and the two child items will maintain their proportions during the animation.
  307. *
  308. * @param {Object} config An object containing properties which describe the animation's start and end states, and
  309. * the timeline of the animation. Of the properties listed below, only **`to`** is mandatory.
  310. *
  311. * Properties include:
  312. *
  313. * @param {Object} config.from
  314. * An object which specifies start values for the properties being animated. If not supplied, properties are
  315. * animated from current settings. The actual properties which may be animated depend upon ths object being
  316. * animated. See the sections below on Element and Component animation.
  317. *
  318. * @param {Object} config.to
  319. * An object which specifies end values for the properties being animated.
  320. *
  321. * @param {Number} config.duration
  322. * The duration **in milliseconds** for which the animation will run.
  323. *
  324. * @param {String} config.easing
  325. * A string value describing an easing type to modify the rate of change from the default linear to non-linear.
  326. * Values may be one of:
  327. *
  328. * - ease
  329. * - easeIn
  330. * - easeOut
  331. * - easeInOut
  332. * - backIn
  333. * - backOut
  334. * - elasticIn
  335. * - elasticOut
  336. * - bounceIn
  337. * - bounceOut
  338. *
  339. * @param {Object} config.keyframes
  340. * This is an object which describes the state of animated properties at certain points along the timeline. it is an
  341. * object containing properties who's names are the percentage along the timeline being described and who's values
  342. * specify the animation state at that point.
  343. *
  344. * @param {Object} config.listeners
  345. * This is a standard {@link Ext.util.Observable#listeners listeners} configuration object which may be used to
  346. * inject behaviour at either the `beforeanimate` event or the `afteranimate` event.
  347. *
  348. * @return {Object} this
  349. */
  350. animate: function(animObj) {
  351. var me = this;
  352. if (Ext.fx.Manager.hasFxBlock(me.id)) {
  353. return me;
  354. }
  355. Ext.fx.Manager.queueFx(new Ext.fx.Anim(me.anim(animObj)));
  356. return this;
  357. },
  358. // @private - process the passed fx configuration.
  359. anim: function(config) {
  360. if (!Ext.isObject(config)) {
  361. return (config) ? {} : false;
  362. }
  363. var me = this;
  364. if (config.stopAnimation) {
  365. me.stopAnimation();
  366. }
  367. Ext.applyIf(config, Ext.fx.Manager.getFxDefaults(me.id));
  368. return Ext.apply({
  369. target: me,
  370. paused: true
  371. }, config);
  372. },
  373. <span id='Ext-util-Animate-method-stopFx'> /**
  374. </span> * Stops any running effects and clears this object's internal effects queue if it contains any additional effects
  375. * that haven't started yet.
  376. * @deprecated 4.0 Replaced by {@link #stopAnimation}
  377. * @return {Ext.Element} The Element
  378. * @method
  379. */
  380. stopFx: Ext.Function.alias(Ext.util.Animate, 'stopAnimation'),
  381. <span id='Ext-util-Animate-method-stopAnimation'> /**
  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. * @return {Ext.Element} The Element
  385. */
  386. stopAnimation: function() {
  387. Ext.fx.Manager.stopAnimation(this.id);
  388. return this;
  389. },
  390. <span id='Ext-util-Animate-method-syncFx'> /**
  391. </span> * Ensures that all effects queued after syncFx is called on this object are run concurrently. This is the opposite
  392. * of {@link #sequenceFx}.
  393. * @return {Object} this
  394. */
  395. syncFx: function() {
  396. Ext.fx.Manager.setFxDefaults(this.id, {
  397. concurrent: true
  398. });
  399. return this;
  400. },
  401. <span id='Ext-util-Animate-method-sequenceFx'> /**
  402. </span> * Ensures that all effects queued after sequenceFx is called on this object are run in sequence. This is the
  403. * opposite of {@link #syncFx}.
  404. * @return {Object} this
  405. */
  406. sequenceFx: function() {
  407. Ext.fx.Manager.setFxDefaults(this.id, {
  408. concurrent: false
  409. });
  410. return this;
  411. },
  412. <span id='Ext-util-Animate-method-hasActiveFx'> /**
  413. </span> * @deprecated 4.0 Replaced by {@link #getActiveAnimation}
  414. * @inheritdoc Ext.util.Animate#getActiveAnimation
  415. * @method
  416. */
  417. hasActiveFx: Ext.Function.alias(Ext.util.Animate, 'getActiveAnimation'),
  418. <span id='Ext-util-Animate-method-getActiveAnimation'> /**
  419. </span> * Returns the current animation if this object has any effects actively running or queued, else returns false.
  420. * @return {Ext.fx.Anim/Boolean} Anim if element has active effects, else false
  421. */
  422. getActiveAnimation: function() {
  423. return Ext.fx.Manager.getActiveAnimation(this.id);
  424. }
  425. }, function(){
  426. // Apply Animate mixin manually until Element is defined in the proper 4.x way
  427. Ext.applyIf(Ext.Element.prototype, this.prototype);
  428. // We need to call this again so the animation methods get copied over to CE
  429. Ext.CompositeElementLite.importElementMethods();
  430. });</pre>
  431. </body>
  432. </html>