Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / ProgressBar.html
index 6e27114..7d0c8d3 100644 (file)
+<!DOCTYPE html>
 <html>
 <head>
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
   <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
 </head>
 </head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.2.2
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-<div id="cls-Ext.ProgressBar"></div>/**
- * @class Ext.ProgressBar
- * @extends Ext.BoxComponent
- * <p>An updateable progress bar component.  The progress bar supports two different modes: manual and automatic.</p>
- * <p>In manual mode, you are responsible for showing, updating (via {@link #updateProgress}) and clearing the
- * progress bar as needed from your own code.  This method is most appropriate when you want to show progress
- * throughout an operation that has predictable points of interest at which you can update the control.</p>
- * <p>In automatic mode, you simply call {@link #wait} and let the progress bar run indefinitely, only clearing it
- * once the operation is complete.  You can optionally have the progress bar wait for a specific amount of time
- * and then clear itself.  Automatic mode is most appropriate for timed operations or asynchronous operations in
- * which you have no need for indicating intermediate progress.</p>
- * @cfg {Float} value A floating point value between 0 and 1 (e.g., .5, defaults to 0)
- * @cfg {String} text The progress bar text (defaults to '')
- * @cfg {Mixed} textEl The element to render the progress text to (defaults to the progress
- * bar's internal text element)
- * @cfg {String} id The progress bar element's id (defaults to an auto-generated id)
- * @xtype progress
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-layout-component-ProgressBar'>/**
+</span> * @class Ext.layout.component.ProgressBar
+ * @extends Ext.layout.component.Component
+ * @private
  */
  */
-Ext.ProgressBar = Ext.extend(Ext.BoxComponent, {
-   /**
-    * @cfg {String} baseCls
-    * The base CSS class to apply to the progress bar's wrapper element (defaults to 'x-progress')
-    */
-    baseCls : 'x-progress',
-    
-    /**
-    * @cfg {Boolean} animate
-    * True to animate the progress bar during transitions (defaults to false)
-    */
-    animate : false,
-
-    // private
-    waitTimer : null,
-
-    // private
-    initComponent : function(){
-        Ext.ProgressBar.superclass.initComponent.call(this);
-        this.addEvents(
-            /**
-             * @event update
-             * Fires after each update interval
-             * @param {Ext.ProgressBar} this
-             * @param {Number} The current progress value
-             * @param {String} The current progress text
-             */
-            "update"
-        );
-    },
-
-    // private
-    onRender : function(ct, position){
-        var tpl = new Ext.Template(
-            '<div class="{cls}-wrap">',
-                '<div class="{cls}-inner">',
-                    '<div class="{cls}-bar">',
-                        '<div class="{cls}-text">',
-                            '<div>&#160;</div>',
-                        '</div>',
-                    '</div>',
-                    '<div class="{cls}-text {cls}-text-back">',
-                        '<div>&#160;</div>',
-                    '</div>',
-                '</div>',
-            '</div>'
-        );
-
-        this.el = position ? tpl.insertBefore(position, {cls: this.baseCls}, true)
-            : tpl.append(ct, {cls: this.baseCls}, true);
-                
-        if(this.id){
-            this.el.dom.id = this.id;
-        }
-        var inner = this.el.dom.firstChild;
-        this.progressBar = Ext.get(inner.firstChild);
-
-        if(this.textEl){
-            //use an external text el
-            this.textEl = Ext.get(this.textEl);
-            delete this.textTopEl;
-        }else{
-            //setup our internal layered text els
-            this.textTopEl = Ext.get(this.progressBar.dom.firstChild);
-            var textBackEl = Ext.get(inner.childNodes[1]);
-            this.textTopEl.setStyle("z-index", 99).addClass('x-hidden');
-            this.textEl = new Ext.CompositeElement([this.textTopEl.dom.firstChild, textBackEl.dom.firstChild]);
-            this.textEl.setWidth(inner.offsetWidth);
-        }
-        this.progressBar.setHeight(inner.offsetHeight);
-    },
-    
-    // private
-    afterRender : function(){
-        Ext.ProgressBar.superclass.afterRender.call(this);
-        if(this.value){
-            this.updateProgress(this.value, this.text);
-        }else{
-            this.updateText(this.text);
-        }
-    },
-
-    /**
-     * Updates the progress bar value, and optionally its text.  If the text argument is not specified,
-     * any existing text value will be unchanged.  To blank out existing text, pass ''.  Note that even
-     * if the progress bar value exceeds 1, it will never automatically reset -- you are responsible for
-     * determining when the progress is complete and calling {@link #reset} to clear and/or hide the control.
-     * @param {Float} value (optional) A floating point value between 0 and 1 (e.g., .5, defaults to 0)
-     * @param {String} text (optional) The string to display in the progress text element (defaults to '')
-     * @param {Boolean} animate (optional) Whether to animate the transition of the progress bar. If this value is
-     * not specified, the default for the class is used (default to false)
-     * @return {Ext.ProgressBar} this
-     */
-    updateProgress : function(value, text, animate){
-        this.value = value || 0;
-        if(text){
-            this.updateText(text);
-        }
-        if(this.rendered && !this.isDestroyed){
-            var w = Math.floor(value*this.el.dom.firstChild.offsetWidth);
-            this.progressBar.setWidth(w, animate === true || (animate !== false && this.animate));
-            if(this.textTopEl){
-                //textTopEl should be the same width as the bar so overflow will clip as the bar moves
-                this.textTopEl.removeClass('x-hidden').setWidth(w);
-            }
-        }
-        this.fireEvent('update', this, value, text);
-        return this;
-    },
 
 
-    /**
-     * Initiates an auto-updating progress bar.  A duration can be specified, in which case the progress
-     * bar will automatically reset after a fixed amount of time and optionally call a callback function
-     * if specified.  If no duration is passed in, then the progress bar will run indefinitely and must
-     * be manually cleared by calling {@link #reset}.  The wait method accepts a config object with
-     * the following properties:
-     * <pre>
-Property   Type          Description
----------- ------------  ----------------------------------------------------------------------
-duration   Number        The length of time in milliseconds that the progress bar should
-                         run before resetting itself (defaults to undefined, in which case it
-                         will run indefinitely until reset is called)
-interval   Number        The length of time in milliseconds between each progress update
-                         (defaults to 1000 ms)
-animate    Boolean       Whether to animate the transition of the progress bar. If this value is
-                         not specified, the default for the class is used.                                                   
-increment  Number        The number of progress update segments to display within the progress
-                         bar (defaults to 10).  If the bar reaches the end and is still
-                         updating, it will automatically wrap back to the beginning.
-text       String        Optional text to display in the progress bar element (defaults to '').
-fn         Function      A callback function to execute after the progress bar finishes auto-
-                         updating.  The function will be called with no arguments.  This function
-                         will be ignored if duration is not specified since in that case the
-                         progress bar can only be stopped programmatically, so any required function
-                         should be called by the same code after it resets the progress bar.
-scope      Object        The scope that is passed to the callback function (only applies when
-                         duration and fn are both passed).
-</pre>
-         *
-         * Example usage:
-         * <pre><code>
-var p = new Ext.ProgressBar({
-   renderTo: 'my-el'
-});
+Ext.define('Ext.layout.component.ProgressBar', {
 
 
-//Wait for 5 seconds, then update the status el (progress bar will auto-reset)
-p.wait({
-   interval: 100, //bar will move fast!
-   duration: 5000,
-   increment: 15,
-   text: 'Updating...',
-   scope: this,
-   fn: function(){
-      Ext.fly('status').update('Done!');
-   }
-});
+    /* Begin Definitions */
 
 
-//Or update indefinitely until some async action completes, then reset manually
-p.wait();
-myAction.on('complete', function(){
-    p.reset();
-    Ext.fly('status').update('Done!');
-});
-</code></pre>
-     * @param {Object} config (optional) Configuration options
-     * @return {Ext.ProgressBar} this
-     */
-    wait : function(o){
-        if(!this.waitTimer){
-            var scope = this;
-            o = o || {};
-            this.updateText(o.text);
-            this.waitTimer = Ext.TaskMgr.start({
-                run: function(i){
-                    var inc = o.increment || 10;
-                    i -= 1;
-                    this.updateProgress(((((i+inc)%inc)+1)*(100/inc))*0.01, null, o.animate);
-                },
-                interval: o.interval || 1000,
-                duration: o.duration,
-                onStop: function(){
-                    if(o.fn){
-                        o.fn.apply(o.scope || this);
-                    }
-                    this.reset();
-                },
-                scope: scope
-            });
-        }
-        return this;
-    },
+    alias: ['layout.progressbar'],
 
 
-    /**
-     * Returns true if the progress bar is currently in a {@link #wait} operation
-     * @return {Boolean} True if waiting, else false
-     */
-    isWaiting : function(){
-        return this.waitTimer !== null;
-    },
+    extend: 'Ext.layout.component.Component',
 
 
-    /**
-     * Updates the progress bar text.  If specified, textEl will be updated, otherwise the progress
-     * bar itself will display the updated text.
-     * @param {String} text (optional) The string to display in the progress text element (defaults to '')
-     * @return {Ext.ProgressBar} this
-     */
-    updateText : function(text){
-        this.text = text || '&#160;';
-        if(this.rendered){
-            this.textEl.update(this.text);
-        }
-        return this;
-    },
-    
-    /**
-     * Synchronizes the inner bar width to the proper proportion of the total componet width based
-     * on the current progress {@link #value}.  This will be called automatically when the ProgressBar
-     * is resized by a layout, but if it is rendered auto width, this method can be called from
-     * another resize handler to sync the ProgressBar if necessary.
-     */
-    syncProgressBar : function(){
-        if(this.value){
-            this.updateProgress(this.value, this.text);
-        }
-        return this;
-    },
+    /* End Definitions */
 
 
-    /**
-     * Sets the size of the progress bar.
-     * @param {Number} width The new width in pixels
-     * @param {Number} height The new height in pixels
-     * @return {Ext.ProgressBar} this
-     */
-    setSize : function(w, h){
-        Ext.ProgressBar.superclass.setSize.call(this, w, h);
-        if(this.textTopEl){
-            var inner = this.el.dom.firstChild;
-            this.textEl.setSize(inner.offsetWidth, inner.offsetHeight);
-        }
-        this.syncProgressBar();
-        return this;
-    },
+    type: 'progressbar',
 
 
-    /**
-     * Resets the progress bar value to 0 and text to empty string.  If hide = true, the progress
-     * bar will also be hidden (using the {@link #hideMode} property internally).
-     * @param {Boolean} hide (optional) True to hide the progress bar (defaults to false)
-     * @return {Ext.ProgressBar} this
-     */
-    reset : function(hide){
-        this.updateProgress(0);
-        if(this.textTopEl){
-            this.textTopEl.addClass('x-hidden');
-        }
-        this.clearTimer();
-        if(hide === true){
-            this.hide();
-        }
-        return this;
-    },
-    
-    // private
-    clearTimer : function(){
-        if(this.waitTimer){
-            this.waitTimer.onStop = null; //prevent recursion
-            Ext.TaskMgr.stop(this.waitTimer);
-            this.waitTimer = null;
-        }
-    },
-    
-    onDestroy: function(){
-        this.clearTimer();
-        if(this.rendered){
-            if(this.textEl.isComposite){
-                this.textEl.clear();
-            }
-            Ext.destroyMembers(this, 'textEl', 'progressBar', 'textTopEl');
-        }
-        Ext.ProgressBar.superclass.onDestroy.call(this);
+    onLayout: function(width, height) {
+        var me = this,
+            owner = me.owner,
+            textEl = owner.textEl;
+        
+        me.setElementSize(owner.el, width, height);
+        textEl.setWidth(owner.el.getWidth(true));
+        
+        me.callParent([width, height]);
+        
+        owner.updateProgress(owner.value);
     }
     }
-});
-Ext.reg('progress', Ext.ProgressBar);</pre>    
+});</pre>
 </body>
 </body>
-</html>
\ No newline at end of file
+</html>