add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / ProgressBar.js

/**\r
 * An updateable progress bar component. The progress bar supports two different modes: manual and automatic.\r
 *\r
 * In manual mode, you are responsible for showing, updating (via {@link #updateProgress}) and clearing the progress bar\r
 * as needed from your own code. This method is most appropriate when you want to show progress throughout an operation\r
 * that has predictable points of interest at which you can update the control.\r
 *\r
 * In automatic mode, you simply call {@link #wait} and let the progress bar run indefinitely, only clearing it once the\r
 * operation is complete. You can optionally have the progress bar wait for a specific amount of time and then clear\r
 * itself. Automatic mode is most appropriate for timed operations or asynchronous operations in which you have no need\r
 * for indicating intermediate progress.\r
 *\r
 *     @example\r
 *     var p = Ext.create('Ext.ProgressBar', {\r
 *        renderTo: Ext.getBody(),\r
 *        width: 300\r
 *     });\r
 *\r
 *     // Wait for 5 seconds, then update the status el (progress bar will auto-reset)\r
 *     p.wait({\r
 *         interval: 500, //bar will move fast!\r
 *         duration: 50000,\r
 *         increment: 15,\r
 *         text: 'Updating...',\r
 *         scope: this,\r
 *         fn: function(){\r
 *             p.updateText('Done!');\r
 *         }\r
 *     });\r
 */\r
Ext.define('Ext.ProgressBar', {\r
    extend: 'Ext.Component',\r
    xtype: 'progressbar',\r
    mixins: [\r
        'Ext.ProgressBase'\r
    ],\r
\r
    requires: [\r
        'Ext.Template',\r
        'Ext.CompositeElement',\r
        'Ext.TaskManager',\r
        'Ext.layout.component.ProgressBar'\r
    ],\r
\r
    uses: ['Ext.fx.Anim'],\r
\r
    /**\r
     * @cfg {String/HTMLElement/Ext.dom.Element} textEl\r
     * The element to render the progress text to (defaults to the progress bar's internal text element)\r
     */\r
\r
    /**\r
     * @cfg {String} id\r
     * The progress bar element's id (defaults to an auto-generated id)\r
     */\r
\r
    /**\r
     * @cfg {String} [baseCls='x-progress']\r
     * The base CSS class to apply to the progress bar's wrapper element.\r
     */\r
    baseCls: Ext.baseCSSPrefix + 'progress',\r
\r
    /**\r
     * @cfg {Boolean/Object} animate\r
     * True to animate the progress bar during transitions, or an animation configuration\r
     * (see the {@link #method-animate} method for details).\r
     */\r
    animate: false,\r
\r
    /**\r
     * @cfg {String} text\r
     * The text shown in the progress bar.\r
     */\r
    text: '',\r
\r
    /**\r
     * @private\r
     */\r
    waitTimer: null,\r
\r
    childEls: [\r
        'bar'\r
    ],\r
\r
    defaultBindProperty: 'value',\r
\r
    renderTpl: [\r
        '<tpl if="internalText">',\r
            '<div class="{baseCls}-text {baseCls}-text-back">{text}</div>',\r
        '</tpl>',\r
        '<div id="{id}-bar" data-ref="bar" class="{baseCls}-bar {baseCls}-bar-{ui}" role="presentation" style="width:{percentage}%">',\r
            '<tpl if="internalText">',\r
                '<div class="{baseCls}-text">',\r
                    '<div>{text}</div>',\r
                '</div>',\r
            '</tpl>',\r
        '</div>'\r
    ],\r
\r
    componentLayout: 'progressbar',\r
    \r
    ariaRole: 'progressbar',\r
\r
    /**\r
     * @event update\r
     * Fires after each update interval\r
     * @param {Ext.ProgressBar} this\r
     * @param {Number} value The current progress value\r
     * @param {String} text The current progress text\r
     */\r
\r
    initRenderData: function() {\r
        var me = this,\r
            value = me.value || 0;\r
\r
        return Ext.apply(me.callParent(), {\r
            internalText : !me.hasOwnProperty('textEl'),\r
            text         : me.text || '&#160;',\r
            percentage   : value * 100\r
        });\r
    },\r
\r
    onRender : function() {\r
        var me = this;\r
\r
        me.callParent(arguments);\r
\r
        // External text display\r
        if (me.textEl) {\r
            me.textEl = Ext.get(me.textEl);\r
            me.updateText(me.text);\r
        }\r
        // Inline text display\r
        else {\r
            // This produces a composite w/2 el's (which is why we cannot use childEls or\r
            // renderSelectors):\r
            me.textEl = me.el.select('.' + me.baseCls + '-text');\r
        }\r
    },\r
\r
    updateValue: function(value) {\r
        this.updateProgress(value, Math.round(value * 100) + '%');\r
    },\r
\r
    /**\r
     * Updates the progress bar value, and optionally its text.\r
     * \r
     * If the text argument is not specified, then the {@link #textTpl} will be used to generate the text.\r
     * If there is no `textTpl`, any existing text value will be unchanged. To blank out existing text, pass `""`.\r
     *\r
     * Note that even if the progress bar value exceeds 1, it will never automatically reset --\r
     * you are responsible for determining when the progress is complete and\r
     * calling {@link #reset} to clear and/or hide the control.\r
     * @param {Number} [value=0] A floating point value between 0 and 1 (e.g., .5)\r
     * @param {String} [text=''] The string to display in the progress text element\r
     * @param {Boolean} [animate=false] Whether to animate the transition of the progress bar. If this value is not\r
     * specified, the default for the class is used\r
     * @return {Ext.ProgressBar} this\r
     */\r
    updateProgress: function(value, text, animate) {\r
        value = value || 0;\r
\r
        var me = this,\r
            oldValue = me.value,\r
            textTpl = me.getTextTpl();\r
\r
        // Ensure value is not undefined.\r
        me.value = value || (value = 0);\r
\r
        // Empty string (falsy) must blank out the text as per docs.\r
        if (text != null) {\r
            me.updateText(text);\r
        }\r
        // Generate text using template and progress values.\r
        else if (textTpl) {\r
            me.updateText(textTpl.apply({\r
                value: value,\r
                percent: value * 100\r
            }));\r
        }\r
        if (me.rendered && !me.destroyed) {\r
            if (animate === true || (animate !== false && me.animate)) {\r
                me.bar.stopAnimation();\r
                me.bar.animate(Ext.apply({\r
                    from: {\r
                        width: (oldValue * 100) + '%'\r
                    },\r
                    to: {\r
                        width: (value * 100) + '%'\r
                    }\r
                }, me.animate));\r
            } else {\r
                me.bar.setStyle('width', (value * 100) + '%');\r
            }\r
        }\r
        me.fireEvent('update', me, value, text);\r
        return me;\r
    },\r
\r
    /**\r
     * Updates the progress bar text. If specified, textEl will be updated, otherwise the progress bar itself will\r
     * display the updated text.\r
     * @param {String} [text=''] The string to display in the progress text element\r
     * @return {Ext.ProgressBar} this\r
     */\r
    updateText: function(text) {\r
        var me = this;\r
        \r
        me.text = text;\r
        if (me.rendered) {\r
            me.textEl.setHtml(me.text);\r
        }\r
        return me;\r
    },\r
\r
    applyText : function(text) {\r
        this.updateText(text);\r
    },\r
    \r
    getText: function(){\r
        return this.text;    \r
    },\r
\r
    /**\r
     * Initiates an auto-updating progress bar. A duration can be specified, in which case the progress bar will\r
     * automatically reset after a fixed amount of time and optionally call a callback function if specified. If no\r
     * duration is passed in, then the progress bar will run indefinitely and must be manually cleared by calling\r
     * {@link #reset}.\r
     *\r
     * Example usage:\r
     *\r
     *     var p = new Ext.ProgressBar({\r
     *        renderTo: 'my-el'\r
     *     });\r
     *\r
     *     //Wait for 5 seconds, then update the status el (progress bar will auto-reset)\r
     *     var p = Ext.create('Ext.ProgressBar', {\r
     *        renderTo: Ext.getBody(),\r
     *        width: 300\r
     *     });\r
     *\r
     *     //Wait for 5 seconds, then update the status el (progress bar will auto-reset)\r
     *     p.wait({\r
     *        interval: 500, //bar will move fast!\r
     *        duration: 50000,\r
     *        increment: 15,\r
     *        text: 'Updating...',\r
     *        scope: this,\r
     *        fn: function(){\r
     *           p.updateText('Done!');\r
     *        }\r
     *     });\r
     *\r
     *     //Or update indefinitely until some async action completes, then reset manually\r
     *     p.wait();\r
     *     myAction.on('complete', function(){\r
     *         p.reset();\r
     *         p.updateText('Done!');\r
     *     });\r
     *\r
     * @param {Object} config (optional) Configuration options\r
     * @param {Number} config.duration The length of time in milliseconds that the progress bar should\r
     * run before resetting itself (defaults to undefined, in which case it will run indefinitely\r
     * until reset is called)\r
     * @param {Number} config.interval The length of time in milliseconds between each progress update\r
     * (defaults to 1000 ms)\r
     * @param {Boolean} config.animate Whether to animate the transition of the progress bar. If this\r
     * value is not specified, the default for the class is used.\r
     * @param {Number} config.increment The number of progress update segments to display within the\r
     * progress bar (defaults to 10).  If the bar reaches the end and is still updating, it will\r
     * automatically wrap back to the beginning.\r
     * @param {String} config.text Optional text to display in the progress bar element (defaults to '').\r
     * @param {Function} config.fn A callback function to execute after the progress bar finishes auto-\r
     * updating.  The function will be called with no arguments.  This function will be ignored if\r
     * duration is not specified since in that case the progress bar can only be stopped programmatically,\r
     * so any required function should be called by the same code after it resets the progress bar.\r
     * @param {Object} config.scope The scope that is passed to the callback function (only applies when\r
     * duration and fn are both passed).\r
     * @return {Ext.ProgressBar} this\r
     */\r
    wait: function(o) {\r
        var me = this, scope;\r
            \r
        if (!me.waitTimer) {\r
            scope = me;\r
            o = o || {};\r
            me.updateText(o.text);\r
            me.waitTimer = Ext.TaskManager.start({\r
                run: function(i){\r
                    var inc = o.increment || 10;\r
                    i -= 1;\r
                    me.updateProgress(((((i+inc)%inc)+1)*(100/inc))*0.01, null, o.animate);\r
                },\r
                interval: o.interval || 1000,\r
                duration: o.duration,\r
                onStop: function(){\r
                    if (o.fn) {\r
                        o.fn.apply(o.scope || me);\r
                    }\r
                    me.reset();\r
                },\r
                scope: scope\r
            });\r
        }\r
        return me;\r
    },\r
\r
    /**\r
     * Returns true if the progress bar is currently in a {@link #wait} operation\r
     * @return {Boolean} True if waiting, else false\r
     */\r
    isWaiting: function(){\r
        return this.waitTimer !== null;\r
    },\r
\r
    /**\r
     * Resets the progress bar value to 0 and text to empty string. If hide = true, the progress bar will also be hidden\r
     * (using the {@link #hideMode} property internally).\r
     * @param {Boolean} [hide=false] True to hide the progress bar.\r
     * @return {Ext.ProgressBar} this\r
     */\r
    reset: function(hide){\r
        var me = this;\r
        \r
        me.updateProgress(0);\r
        me.clearTimer();\r
        if (hide === true) {\r
            me.hide();\r
        }\r
        return me;\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    clearTimer: function(){\r
        var me = this;\r
        \r
        if (me.waitTimer) {\r
            me.waitTimer.onStop = null; //prevent recursion\r
            Ext.TaskManager.stop(me.waitTimer);\r
            me.waitTimer = null;\r
        }\r
    },\r
\r
    onDestroy: function(){\r
        var me = this,\r
            bar = me.bar;\r
        \r
        me.clearTimer();\r
        if (me.rendered) {\r
            if (me.textEl.isComposite) {\r
                me.textEl.clear();\r
            }\r
            Ext.destroyMembers(me, 'textEl', 'progressBar');\r
            if (bar && me.animate) {\r
                bar.stopAnimation();\r
            }\r
        }\r
        me.callParent();\r
    }\r
});\r