add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / util / Animate.js

/**\r
 * This animation class is a mixin.\r
 *\r
 * Ext.util.Animate provides an API for the creation of animated transitions of properties and styles.\r
 * This class is used as a mixin and currently applied to {@link Ext.dom.Element}, {@link Ext.CompositeElement},\r
 * {@link Ext.draw.sprite.Sprite}, {@link Ext.draw.sprite.Composite}, and {@link Ext.Component}.  Note that Components\r
 * have a limited subset of what attributes can be animated such as top, left, x, y, height, width, and\r
 * opacity (color, paddings, and margins can not be animated).\r
 *\r
 * ## Animation Basics\r
 *\r
 * All animations require three things - `easing`, `duration`, and `to` (the final end value for each property)\r
 * you wish to animate. Easing and duration are defaulted values specified below.\r
 * Easing describes how the intermediate values used during a transition will be calculated.\r
 * {@link Ext.fx.Anim#easing Easing} allows for a transition to change speed over its duration.\r
 * You may use the defaults for easing and duration, but you must always set a\r
 * {@link Ext.fx.Anim#to to} property which is the end value for all animations.\r
 *\r
 * Popular element 'to' configurations are:\r
 *\r
 *  - opacity\r
 *  - x\r
 *  - y\r
 *  - color\r
 *  - height\r
 *  - width\r
 *\r
 * Popular sprite 'to' configurations are:\r
 *\r
 *  - translation\r
 *  - path\r
 *  - scale\r
 *  - stroke\r
 *  - rotation\r
 *\r
 * The default duration for animations is 250 (which is a 1/4 of a second).  Duration is denoted in\r
 * milliseconds.  Therefore 1 second is 1000, 1 minute would be 60000, and so on. The default easing curve\r
 * used for all animations is 'ease'.  Popular easing functions are included and can be found in {@link Ext.fx.Anim#easing Easing}.\r
 *\r
 * For example, a simple animation to fade out an element with a default easing and duration:\r
 *\r
 *     var p1 = Ext.get('myElementId');\r
 *\r
 *     p1.animate({\r
 *         to: {\r
 *             opacity: 0\r
 *         }\r
 *     });\r
 *\r
 * To make this animation fade out in a tenth of a second:\r
 *\r
 *     var p1 = Ext.get('myElementId');\r
 *\r
 *     p1.animate({\r
 *        duration: 100,\r
 *         to: {\r
 *             opacity: 0\r
 *         }\r
 *     });\r
 *\r
 * ## Animation Queues\r
 *\r
 * By default all animations are added to a queue which allows for animation via a chain-style API.\r
 * For example, the following code will queue 4 animations which occur sequentially (one right after the other):\r
 *\r
 *     p1.animate({\r
 *         to: {\r
 *             x: 500\r
 *         }\r
 *     }).animate({\r
 *         to: {\r
 *             y: 150\r
 *         }\r
 *     }).animate({\r
 *         to: {\r
 *             backgroundColor: '#f00'  //red\r
 *         }\r
 *     }).animate({\r
 *         to: {\r
 *             opacity: 0\r
 *         }\r
 *     });\r
 *\r
 * You can change this behavior by calling the {@link Ext.util.Animate#syncFx syncFx} method and all\r
 * subsequent animations for the specified target will be run concurrently (at the same time).\r
 *\r
 *     p1.syncFx();  //this will make all animations run at the same time\r
 *\r
 *     p1.animate({\r
 *         to: {\r
 *             x: 500\r
 *         }\r
 *     }).animate({\r
 *         to: {\r
 *             y: 150\r
 *         }\r
 *     }).animate({\r
 *         to: {\r
 *             backgroundColor: '#f00'  //red\r
 *         }\r
 *     }).animate({\r
 *         to: {\r
 *             opacity: 0\r
 *         }\r
 *     });\r
 *\r
 * This works the same as:\r
 *\r
 *     p1.animate({\r
 *         to: {\r
 *             x: 500,\r
 *             y: 150,\r
 *             backgroundColor: '#f00'  //red\r
 *             opacity: 0\r
 *         }\r
 *     });\r
 *\r
 * The {@link Ext.util.Animate#stopAnimation stopAnimation} method can be used to stop any\r
 * currently running animations and clear any queued animations.\r
 *\r
 * ## Animation Keyframes\r
 *\r
 * You can also set up complex animations with {@link Ext.fx.Anim#keyframes keyframes} which follow the\r
 * CSS3 Animation configuration pattern. Note rotation, translation, and scaling can only be done for sprites.\r
 * The previous example can be written with the following syntax:\r
 *\r
 *     p1.animate({\r
 *         duration: 1000,  //one second total\r
 *         keyframes: {\r
 *             25: {     //from 0 to 250ms (25%)\r
 *                 x: 0\r
 *             },\r
 *             50: {   //from 250ms to 500ms (50%)\r
 *                 y: 0\r
 *             },\r
 *             75: {  //from 500ms to 750ms (75%)\r
 *                 backgroundColor: '#f00'  //red\r
 *             },\r
 *             100: {  //from 750ms to 1sec\r
 *                 opacity: 0\r
 *             }\r
 *         }\r
 *     });\r
 *\r
 * ## Animation Events\r
 *\r
 * Each animation you create has events for {@link Ext.fx.Anim#beforeanimate beforeanimate},\r
 * {@link Ext.fx.Anim#afteranimate afteranimate}, and {@link Ext.fx.Anim#lastframe lastframe}.\r
 * Keyframed animations adds an additional {@link Ext.fx.Animator#keyframe keyframe} event which\r
 * fires for each keyframe in your animation.\r
 *\r
 * All animations support the {@link Ext.util.Observable#listeners listeners} configuration to attact functions to these events.\r
 *\r
 *     startAnimate: function() {\r
 *         var p1 = Ext.get('myElementId');\r
 *         p1.animate({\r
 *            duration: 100,\r
 *             to: {\r
 *                 opacity: 0\r
 *             },\r
 *             listeners: {\r
 *                 beforeanimate:  function() {\r
 *                     // Execute my custom method before the animation\r
 *                     this.myBeforeAnimateFn();\r
 *                 },\r
 *                 afteranimate: function() {\r
 *                     // Execute my custom method after the animation\r
 *                     this.myAfterAnimateFn();\r
 *                 },\r
 *                 scope: this\r
 *         });\r
 *     },\r
 *     myBeforeAnimateFn: function() {\r
 *       // My custom logic\r
 *     },\r
 *     myAfterAnimateFn: function() {\r
 *       // My custom logic\r
 *     }\r
 *\r
 * Due to the fact that animations run asynchronously, you can determine if an animation is currently\r
 * running on any target by using the {@link Ext.util.Animate#getActiveAnimation getActiveAnimation}\r
 * method.  This method will return false if there are no active animations or return the currently\r
 * running {@link Ext.fx.Anim} instance.\r
 *\r
 * In this example, we're going to wait for the current animation to finish, then stop any other\r
 * queued animations before we fade our element's opacity to 0:\r
 *\r
 *     var curAnim = p1.getActiveAnimation();\r
 *     if (curAnim) {\r
 *         curAnim.on('afteranimate', function() {\r
 *             p1.stopAnimation();\r
 *             p1.animate({\r
 *                 to: {\r
 *                     opacity: 0\r
 *                 }\r
 *             });\r
 *         });\r
 *     }\r
 */\r
Ext.define('Ext.util.Animate', {\r
    mixinId: 'animate',\r
\r
    requires: [\r
        'Ext.fx.Manager', \r
        'Ext.fx.Anim'\r
    ],\r
    \r
    isAnimate: true,\r
\r
    /**\r
     * Performs custom animation on this object.\r
     *\r
     * This method is applicable to both the {@link Ext.Component Component} class and the {@link Ext.draw.sprite.Sprite Sprite}\r
     * class. It performs animated transitions of certain properties of this object over a specified timeline.\r
     *\r
     * ### Animating a {@link Ext.Component Component}\r
     *\r
     * When animating a Component, the following properties may be specified in `from`, `to`, and `keyframe` objects:\r
     *\r
     *   - `x` - The Component's page X position in pixels.\r
     *\r
     *   - `y` - The Component's page Y position in pixels\r
     *\r
     *   - `left` - The Component's `left` value in pixels.\r
     *\r
     *   - `top` - The Component's `top` value in pixels.\r
     *\r
     *   - `width` - The Component's `width` value in pixels.\r
     *\r
     *   - `height` - The Component's `height` value in pixels.\r
     *\r
     *   - `dynamic` - Specify as true to update the Component's layout (if it is a Container) at every frame of the animation.\r
     *     *Use sparingly as laying out on every intermediate size change is an expensive operation.*\r
     *\r
     * For example, to animate a Window to a new size, ensuring that its internal layout and any shadow is correct:\r
     *\r
     *     myWindow = Ext.create('Ext.window.Window', {\r
     *         title: 'Test Component animation',\r
     *         width: 500,\r
     *         height: 300,\r
     *         layout: {\r
     *             type: 'hbox',\r
     *             align: 'stretch'\r
     *         },\r
     *         items: [{\r
     *             title: 'Left: 33%',\r
     *             margin: '5 0 5 5',\r
     *             flex: 1\r
     *         }, {\r
     *             title: 'Left: 66%',\r
     *             margin: '5 5 5 5',\r
     *             flex: 2\r
     *         }]\r
     *     });\r
     *     myWindow.show();\r
     *     myWindow.header.el.on('click', function() {\r
     *         myWindow.animate({\r
     *             to: {\r
     *                 width: (myWindow.getWidth() == 500) ? 700 : 500,\r
     *                 height: (myWindow.getHeight() == 300) ? 400 : 300\r
     *             }\r
     *         });\r
     *     });\r
     *\r
     * For performance reasons, by default, the internal layout is only updated when the Window reaches its final `"to"`\r
     * size. If dynamic updating of the Window's child Components is required, then configure the animation with\r
     * `dynamic: true` and the two child items will maintain their proportions during the animation.\r
     *\r
     * @param {Object} config  Configuration for {@link Ext.fx.Anim}.\r
     * Note that the {@link Ext.fx.Anim#to to} config is required.\r
     * @return {Object} this\r
     */\r
    animate: function(animObj) {\r
        var me = this;\r
        if (Ext.fx.Manager.hasFxBlock(me.id)) {\r
            return me;\r
        }\r
        Ext.fx.Manager.queueFx(new Ext.fx.Anim(me.anim(animObj)));\r
        return this;\r
    },\r
\r
    /**\r
     * @private\r
     * Process the passed fx configuration.\r
     */\r
    anim: function(config) {\r
        if (!Ext.isObject(config)) {\r
            return (config) ? {} : false;\r
        }\r
\r
        var me = this;\r
\r
        if (config.stopAnimation) {\r
            me.stopAnimation();\r
        }\r
\r
        Ext.applyIf(config, Ext.fx.Manager.getFxDefaults(me.id));\r
\r
        return Ext.apply({\r
            target: me,\r
            paused: true\r
        }, config);\r
    },\r
    \r
    /**\r
     * @private\r
     * Get animation properties\r
     */\r
    getAnimationProps: function() {\r
        var me = this,\r
            layout = me.layout;\r
        \r
        return layout && layout.animate ? layout.animate : {};\r
    },\r
\r
    /**\r
     * Stops any running effects and clears this object's internal effects queue if it contains any additional effects\r
     * that haven't started yet.\r
     * @deprecated 4.0 Replaced by {@link #stopAnimation}\r
     * @return {Ext.dom.Element} The Element\r
     * @method\r
     */\r
    stopFx: Ext.Function.alias(Ext.util.Animate, 'stopAnimation'),\r
\r
    /**\r
     * Stops any running effects and clears this object's internal effects queue if it contains any additional effects\r
     * that haven't started yet.\r
     * @return {Ext.dom.Element} The Element\r
     */\r
    stopAnimation: function() {\r
        Ext.fx.Manager.stopAnimation(this.id);\r
        return this;\r
    },\r
\r
    /**\r
     * Ensures that all effects queued after syncFx is called on this object are run concurrently. This is the opposite\r
     * of {@link #sequenceFx}.\r
     * @return {Object} this\r
     */\r
    syncFx: function() {\r
        Ext.fx.Manager.setFxDefaults(this.id, {\r
            concurrent: true\r
        });\r
        return this;\r
    },\r
\r
    /**\r
     * Ensures that all effects queued after sequenceFx is called on this object are run in sequence. This is the\r
     * opposite of {@link #syncFx}.\r
     * @return {Object} this\r
     */\r
    sequenceFx: function() {\r
        Ext.fx.Manager.setFxDefaults(this.id, {\r
            concurrent: false\r
        });\r
        return this;\r
    },\r
\r
    /**\r
     * @deprecated 4.0 Replaced by {@link #getActiveAnimation}\r
     * @inheritdoc Ext.util.Animate#getActiveAnimation\r
     * @method\r
     */\r
    hasActiveFx: Ext.Function.alias(Ext.util.Animate, 'getActiveAnimation'),\r
\r
    /**\r
     * Returns the current animation if this object has any effects actively running or queued, else returns false.\r
     * @return {Ext.fx.Anim/Boolean} Anim if element has active effects, else false\r
     */\r
    getActiveAnimation: function() {\r
        return Ext.fx.Manager.getActiveAnimation(this.id);\r
    }\r
});\r