docs/source/ProgressBar2.html

   1 <!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-ProgressBar-cfg-id'><span id='Ext-ProgressBar-cfg-textEl'><span id='Ext-ProgressBar-cfg-text'><span id='Ext-ProgressBar-cfg-value'><span id='Ext-ProgressBar'>/**
   2 </span></span></span></span></span> * @class Ext.ProgressBar
   3  * @extends Ext.Component
   4  * &lt;p&gt;An updateable progress bar component.  The progress bar supports two different modes: manual and automatic.&lt;/p&gt;
   5  * &lt;p&gt;In manual mode, you are responsible for showing, updating (via {@link #updateProgress}) and clearing the
   6  * progress bar as needed from your own code.  This method is most appropriate when you want to show progress
   7  * throughout an operation that has predictable points of interest at which you can update the control.&lt;/p&gt;
   8  * &lt;p&gt;In automatic mode, you simply call {@link #wait} and let the progress bar run indefinitely, only clearing it
   9  * once the operation is complete.  You can optionally have the progress bar wait for a specific amount of time
  10  * and then clear itself.  Automatic mode is most appropriate for timed operations or asynchronous operations in
  11  * which you have no need for indicating intermediate progress.&lt;/p&gt;
  12  * {@img Ext.ProgressBar/Ext.ProgressBar.png Ext.ProgressBar component}
  13  * Example Usage:
  14      var p = Ext.create('Ext.ProgressBar', {
  15        renderTo: Ext.getBody(),
  16        width: 300
  17     });
  18
  19     //Wait for 5 seconds, then update the status el (progress bar will auto-reset)
  20     p.wait({
  21        interval: 500, //bar will move fast!
  22        duration: 50000,
  23        increment: 15,
  24        text: 'Updating...',
  25        scope: this,
  26        fn: function(){
  27           p.updateText('Done!');
  28        }
  29     });
  30  * @cfg {Float} value A floating point value between 0 and 1 (e.g., .5, defaults to 0)
  31  * @cfg {String} text The progress bar text (defaults to '')
  32  * @cfg {Mixed} textEl The element to render the progress text to (defaults to the progress
  33  * bar's internal text element)
  34  * @cfg {String} id The progress bar element's id (defaults to an auto-generated id)
  35  * @xtype progressbar
  36  */
  37 Ext.define('Ext.ProgressBar', {
  38     extend: 'Ext.Component',
  39     alias: 'widget.progressbar',
  40
  41     requires: [
  42         'Ext.Template',
  43         'Ext.CompositeElement',
  44         'Ext.TaskManager',
  45         'Ext.layout.component.ProgressBar'
  46     ],
  47
  48     uses: ['Ext.fx.Anim'],
  49 <span id='Ext-ProgressBar-cfg-baseCls'>   /**
  50 </span>    * @cfg {String} baseCls
  51     * The base CSS class to apply to the progress bar's wrapper element (defaults to 'x-progress')
  52     */
  53     baseCls: Ext.baseCSSPrefix + 'progress',
  54
  55     config: {
  56 <span id='Ext-ProgressBar-cfg-animate'>        /**
  57 </span>        * @cfg {Boolean} animate
  58         * True to animate the progress bar during transitions (defaults to false)
  59         */
  60         animate: false,
  61
  62 <span id='Ext-ProgressBar-cfg-text'>        /**
  63 </span>         * @cfg {String} text The text shown in the progress bar (defaults to '')
  64          */
  65         text: ''
  66     },
  67
  68     // private
  69     waitTimer: null,
  70
  71     renderTpl: [
  72         '&lt;div class=&quot;{baseCls}-text {baseCls}-text-back&quot;&gt;',
  73             '&lt;div&gt;&amp;#160;&lt;/div&gt;',
  74         '&lt;/div&gt;',
  75         '&lt;div class=&quot;{baseCls}-bar&quot;&gt;',
  76             '&lt;div class=&quot;{baseCls}-text&quot;&gt;',
  77                 '&lt;div&gt;&amp;#160;&lt;/div&gt;',
  78             '&lt;/div&gt;',
  79         '&lt;/div&gt;'
  80     ],
  81
  82     componentLayout: 'progressbar',
  83
  84     // private
  85     initComponent: function() {
  86         this.callParent();
  87
  88         this.renderSelectors = Ext.apply(this.renderSelectors || {}, {
  89             textTopEl: '.' + this.baseCls + '-text',
  90             textBackEl: '.' + this.baseCls + '-text-back',
  91             bar: '.' + this.baseCls + '-bar'
  92         });
  93
  94         this.addEvents(
  95 <span id='Ext-ProgressBar-event-update'>            /**
  96 </span>             * @event update
  97              * Fires after each update interval
  98              * @param {Ext.ProgressBar} this
  99              * @param {Number} The current progress value
 100              * @param {String} The current progress text
 101              */
 102             &quot;update&quot;
 103         );
 104     },
 105
 106     afterRender : function() {
 107         var me = this;
 108
 109         me.textEl = me.textEl ? Ext.get(me.textEl) : me.el.select('.' + me.baseCls + '-text');
 110
 111         this.callParent(arguments);
 112
 113         if (me.value) {
 114             me.updateProgress(me.value, me.text);
 115         }
 116         else {
 117             me.updateText(me.text);
 118         }
 119     },
 120
 121 <span id='Ext-ProgressBar-method-updateProgress'>    /**
 122 </span>     * Updates the progress bar value, and optionally its text.  If the text argument is not specified,
 123      * any existing text value will be unchanged.  To blank out existing text, pass ''.  Note that even
 124      * if the progress bar value exceeds 1, it will never automatically reset -- you are responsible for
 125      * determining when the progress is complete and calling {@link #reset} to clear and/or hide the control.
 126      * @param {Float} value (optional) A floating point value between 0 and 1 (e.g., .5, defaults to 0)
 127      * @param {String} text (optional) The string to display in the progress text element (defaults to '')
 128      * @param {Boolean} animate (optional) Whether to animate the transition of the progress bar. If this value is
 129      * not specified, the default for the class is used (default to false)
 130      * @return {Ext.ProgressBar} this
 131      */
 132     updateProgress: function(value, text, animate) {
 133         var newWidth;
 134         this.value = value || 0;
 135         if (text) {
 136             this.updateText(text);
 137         }
 138         if (this.rendered &amp;&amp; !this.isDestroyed) {
 139             newWidth = Math.floor(this.value * this.el.getWidth(true));
 140             if (Ext.isForcedBorderBox) {
 141                 newWidth += this.bar.getBorderWidth(&quot;lr&quot;);
 142             }
 143             if (animate === true || (animate !== false &amp;&amp; this.animate)) {
 144                 this.bar.stopAnimation();
 145                 this.bar.animate(Ext.apply({
 146                     to: {
 147                         width: newWidth + 'px'
 148                     }
 149                 }, this.animate));
 150             } else {
 151                 this.bar.setWidth(newWidth);
 152             }
 153         }
 154         this.fireEvent('update', this, this.value, text);
 155         return this;
 156     },
 157
 158 <span id='Ext-ProgressBar-method-updateText'>    /**
 159 </span>     * Updates the progress bar text.  If specified, textEl will be updated, otherwise the progress
 160      * bar itself will display the updated text.
 161      * @param {String} text (optional) The string to display in the progress text element (defaults to '')
 162      * @return {Ext.ProgressBar} this
 163      */
 164     updateText: function(text) {
 165         this.text = text;
 166         if (this.rendered) {
 167             this.textEl.update(this.text);
 168         }
 169         return this;
 170     },
 171
 172     applyText : function(text) {
 173         this.updateText(text);
 174     },
 175
 176 <span id='Ext-ProgressBar-method-wait'>    /**
 177 </span>         * Initiates an auto-updating progress bar.  A duration can be specified, in which case the progress
 178          * bar will automatically reset after a fixed amount of time and optionally call a callback function
 179          * if specified.  If no duration is passed in, then the progress bar will run indefinitely and must
 180          * be manually cleared by calling {@link #reset}.  The wait method accepts a config object with
 181          * the following properties:
 182          * &lt;pre&gt;
 183     Property   Type          Description
 184     ---------- ------------  ----------------------------------------------------------------------
 185     duration   Number        The length of time in milliseconds that the progress bar should
 186                              run before resetting itself (defaults to undefined, in which case it
 187                              will run indefinitely until reset is called)
 188     interval   Number        The length of time in milliseconds between each progress update
 189                              (defaults to 1000 ms)
 190     animate    Boolean       Whether to animate the transition of the progress bar. If this value is
 191                              not specified, the default for the class is used.
 192     increment  Number        The number of progress update segments to display within the progress
 193                              bar (defaults to 10).  If the bar reaches the end and is still
 194                              updating, it will automatically wrap back to the beginning.
 195     text       String        Optional text to display in the progress bar element (defaults to '').
 196     fn         Function      A callback function to execute after the progress bar finishes auto-
 197                              updating.  The function will be called with no arguments.  This function
 198                              will be ignored if duration is not specified since in that case the
 199                              progress bar can only be stopped programmatically, so any required function
 200                              should be called by the same code after it resets the progress bar.
 201     scope      Object        The scope that is passed to the callback function (only applies when
 202                              duration and fn are both passed).
 203     &lt;/pre&gt;
 204              *
 205              * Example usage:
 206              * &lt;pre&gt;&lt;code&gt;
 207     var p = new Ext.ProgressBar({
 208        renderTo: 'my-el'
 209     });
 210
 211     //Wait for 5 seconds, then update the status el (progress bar will auto-reset)
 212     var p = Ext.create('Ext.ProgressBar', {
 213        renderTo: Ext.getBody(),
 214        width: 300
 215     });
 216
 217     //Wait for 5 seconds, then update the status el (progress bar will auto-reset)
 218     p.wait({
 219        interval: 500, //bar will move fast!
 220        duration: 50000,
 221        increment: 15,
 222        text: 'Updating...',
 223        scope: this,
 224        fn: function(){
 225           p.updateText('Done!');
 226        }
 227     });
 228
 229     //Or update indefinitely until some async action completes, then reset manually
 230     p.wait();
 231     myAction.on('complete', function(){
 232         p.reset();
 233         p.updateText('Done!');
 234     });
 235     &lt;/code&gt;&lt;/pre&gt;
 236          * @param {Object} config (optional) Configuration options
 237          * @return {Ext.ProgressBar} this
 238          */
 239     wait: function(o) {
 240         if (!this.waitTimer) {
 241             var scope = this;
 242             o = o || {};
 243             this.updateText(o.text);
 244             this.waitTimer = Ext.TaskManager.start({
 245                 run: function(i){
 246                     var inc = o.increment || 10;
 247                     i -= 1;
 248                     this.updateProgress(((((i+inc)%inc)+1)*(100/inc))*0.01, null, o.animate);
 249                 },
 250                 interval: o.interval || 1000,
 251                 duration: o.duration,
 252                 onStop: function(){
 253                     if (o.fn) {
 254                         o.fn.apply(o.scope || this);
 255                     }
 256                     this.reset();
 257                 },
 258                 scope: scope
 259             });
 260         }
 261         return this;
 262     },
 263
 264 <span id='Ext-ProgressBar-method-isWaiting'>    /**
 265 </span>     * Returns true if the progress bar is currently in a {@link #wait} operation
 266      * @return {Boolean} True if waiting, else false
 267      */
 268     isWaiting: function(){
 269         return this.waitTimer !== null;
 270     },
 271
 272 <span id='Ext-ProgressBar-method-reset'>    /**
 273 </span>     * Resets the progress bar value to 0 and text to empty string.  If hide = true, the progress
 274      * bar will also be hidden (using the {@link #hideMode} property internally).
 275      * @param {Boolean} hide (optional) True to hide the progress bar (defaults to false)
 276      * @return {Ext.ProgressBar} this
 277      */
 278     reset: function(hide){
 279         this.updateProgress(0);
 280         this.clearTimer();
 281         if (hide === true) {
 282             this.hide();
 283         }
 284         return this;
 285     },
 286
 287     // private
 288     clearTimer: function(){
 289         if (this.waitTimer) {
 290             this.waitTimer.onStop = null; //prevent recursion
 291             Ext.TaskManager.stop(this.waitTimer);
 292             this.waitTimer = null;
 293         }
 294     },
 295
 296     onDestroy: function(){
 297         this.clearTimer();
 298         if (this.rendered) {
 299             if (this.textEl.isComposite) {
 300                 this.textEl.clear();
 301             }
 302             Ext.destroyMembers(this, 'textEl', 'progressBar', 'textTopEl');
 303         }
 304         this.callParent();
 305     }
 306 });
 307 </pre></pre></body></html>