Upgrade to ExtJS 4.0.1 - Released 05/18/2011
[extjs.git] / docs / source / LoadMask.html
index 44ac065..afb7c09 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.LoadMask"></div>/**
- * @class Ext.LoadMask
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../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>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-LoadMask-method-constructor'><span id='Ext-LoadMask'>/**
+</span></span> * @class Ext.LoadMask
  * A simple utility class for generically masking elements while loading data.  If the {@link #store}
  * config option is specified, the masking will be automatically synchronized with the store's loading
- * process and the mask element will be cached for reuse.  For all other elements, this mask will replace the
- * element's Updater load indicator and will be destroyed after the initial load.
- * <p>Example usage:</p>
- *<pre><code>
+ * process and the mask element will be cached for reuse.
+ * &lt;p&gt;Example usage:&lt;/p&gt;
+ * &lt;pre&gt;&lt;code&gt;
 // Basic mask:
-var myMask = new Ext.LoadMask(Ext.getBody(), {msg:"Please wait..."});
+var myMask = new Ext.LoadMask(Ext.getBody(), {msg:&quot;Please wait...&quot;});
 myMask.show();
-</code></pre>
+&lt;/code&gt;&lt;/pre&gt;
+
  * @constructor
  * Create a new LoadMask
- * @param {Mixed} el The element or DOM node, or its id
+ * @param {Mixed} el The element, element ID, or DOM node you wish to mask. Also, may be a Component who's element you wish to mask.
  * @param {Object} config The config object
  */
-Ext.LoadMask = function(el, config){
-    this.el = Ext.get(el);
-    Ext.apply(this, config);
-    if(this.store){
-        this.store.on({
-            scope: this,
-            beforeload: this.onBeforeLoad,
-            load: this.onLoad,
-            exception: this.onLoad
-        });
-        this.removeMask = Ext.value(this.removeMask, false);
-    }else{
-        var um = this.el.getUpdater();
-        um.showLoadIndicator = false; // disable the default indicator
-        um.on({
-            scope: this,
-            beforeupdate: this.onBeforeLoad,
-            update: this.onLoad,
-            failure: this.onLoad
-        });
-        this.removeMask = Ext.value(this.removeMask, true);
-    }
-};
 
-Ext.LoadMask.prototype = {
-    <div id="cfg-Ext.LoadMask-store"></div>/**
-     * @cfg {Ext.data.Store} store
+Ext.define('Ext.LoadMask', {
+
+    /* Begin Definitions */
+
+    mixins: {
+        observable: 'Ext.util.Observable'
+    },
+
+    requires: ['Ext.data.StoreManager'],
+
+    /* End Definitions */
+
+<span id='Ext-LoadMask-cfg-store'>    /**
+</span>     * @cfg {Ext.data.Store} store
      * Optional Store to which the mask is bound. The mask is displayed when a load request is issued, and
-     * hidden on either load sucess, or load fail.
+     * hidden on either load success, or load fail.
      */
-    <div id="cfg-Ext.LoadMask-removeMask"></div>/**
-     * @cfg {Boolean} removeMask
-     * True to create a single-use mask that is automatically destroyed after loading (useful for page loads),
-     * False to persist the mask element reference for multiple uses (e.g., for paged data widgets).  Defaults to false.
-     */
-    <div id="cfg-Ext.LoadMask-msg"></div>/**
-     * @cfg {String} msg
+
+<span id='Ext-LoadMask-cfg-msg'>    /**
+</span>     * @cfg {String} msg
      * The text to display in a centered loading message box (defaults to 'Loading...')
      */
     msg : 'Loading...',
-    <div id="cfg-Ext.LoadMask-msgCls"></div>/**
-     * @cfg {String} msgCls
-     * The CSS class to apply to the loading message element (defaults to "x-mask-loading")
+<span id='Ext-LoadMask-cfg-msgCls'>    /**
+</span>     * @cfg {String} msgCls
+     * The CSS class to apply to the loading message element (defaults to &quot;x-mask-loading&quot;)
      */
-    msgCls : 'x-mask-loading',
+    msgCls : Ext.baseCSSPrefix + 'mask-loading',
+    
+<span id='Ext-LoadMask-cfg-useMsg'>    /**
+</span>     * @cfg {Boolean} useMsg
+     * Whether or not to use a loading message class or simply mask the bound element.
+     */
+    useMsg: true,
 
-    <div id="prop-Ext.LoadMask-disabled"></div>/**
-     * Read-only. True if the mask is currently disabled so that it will not be displayed (defaults to false)
+<span id='Ext-LoadMask-property-disabled'>    /**
+</span>     * Read-only. True if the mask is currently disabled so that it will not be displayed (defaults to false)
      * @type Boolean
      */
     disabled: false,
 
-    <div id="method-Ext.LoadMask-disable"></div>/**
-     * Disables the mask to prevent it from being displayed
+    constructor : function(el, config) {
+        var me = this;
+
+        if (el.isComponent) {
+            me.bindComponent(el);
+        } else {
+            me.el = Ext.get(el);
+        }
+        Ext.apply(me, config);
+
+        me.addEvents('beforeshow', 'show', 'hide');
+        if (me.store) {
+            me.bindStore(me.store, true);
+        }
+        me.mixins.observable.constructor.call(me, config);
+    },
+
+    bindComponent: function(comp) {
+        var me = this,
+            listeners = {
+                resize: me.onComponentResize,
+                scope: me
+            };
+
+        if (comp.el) {
+            me.onComponentRender(comp);
+        } else {
+            listeners.render = {
+                fn: me.onComponentRender,
+                scope: me,
+                single: true
+            };
+        }
+        me.mon(comp, listeners);
+    },
+
+<span id='Ext-LoadMask-method-onComponentRender'>    /**
+</span>     * @private
+     * Called if we were configured with a Component, and that Component was not yet rendered. Collects the element to mask.
      */
-    disable : function(){
-       this.disabled = true;
+    onComponentRender: function(comp) {
+        this.el = comp.getContentTarget();
     },
 
-    <div id="method-Ext.LoadMask-enable"></div>/**
-     * Enables the mask so that it can be displayed
+<span id='Ext-LoadMask-method-onComponentResize'>    /**
+</span>     * @private
+     * Called when this LoadMask's Component is resized. The isMasked method also re-centers any displayed message.
      */
-    enable : function(){
+    onComponentResize: function(comp, w, h) {
+        this.el.isMasked();
+    },
+
+<span id='Ext-LoadMask-method-bindStore'>    /**
+</span>     * Changes the data store bound to this LoadMask.
+     * @param {Store} store The store to bind to this LoadMask
+     */
+    bindStore : function(store, initial) {
+        var me = this;
+
+        if (!initial &amp;&amp; me.store) {
+            me.mun(me.store, {
+                scope: me,
+                beforeload: me.onBeforeLoad,
+                load: me.onLoad,
+                exception: me.onLoad
+            });
+            if(!store) {
+                me.store = null;
+            }
+        }
+        if (store) {
+            store = Ext.data.StoreManager.lookup(store);
+            me.mon(store, {
+                scope: me,
+                beforeload: me.onBeforeLoad,
+                load: me.onLoad,
+                exception: me.onLoad
+            });
+
+        }
+        me.store = store;
+        if (store &amp;&amp; store.isLoading()) {
+            me.onBeforeLoad();
+        }
+    },
+
+<span id='Ext-LoadMask-method-disable'>    /**
+</span>     * Disables the mask to prevent it from being displayed
+     */
+    disable : function() {
+        var me = this;
+
+       me.disabled = true;
+       if (me.loading) {
+           me.onLoad();
+       }
+    },
+
+<span id='Ext-LoadMask-method-enable'>    /**
+</span>     * Enables the mask so that it can be displayed
+     */
+    enable : function() {
         this.disabled = false;
     },
 
+<span id='Ext-LoadMask-method-isDisabled'>    /**
+</span>     * Method to determine whether this LoadMask is currently disabled.
+     * @return {Boolean} the disabled state of this LoadMask.
+     */
+    isDisabled : function() {
+        return this.disabled;
+    },
+
     // private
-    onLoad : function(){
-        this.el.unmask(this.removeMask);
+    onLoad : function() {
+        var me = this;
+
+        me.loading = false;
+        me.el.unmask();
+        me.fireEvent('hide', me, me.el, me.store);
     },
 
     // private
-    onBeforeLoad : function(){
-        if(!this.disabled){
-            this.el.mask(this.msg, this.msgCls);
+    onBeforeLoad : function() {
+        var me = this;
+
+        if (!me.disabled &amp;&amp; !me.loading &amp;&amp; me.fireEvent('beforeshow', me, me.el, me.store) !== false) {
+            if (me.useMsg) {
+                me.el.mask(me.msg, me.msgCls, false);
+            } else {
+                me.el.mask();
+            }
+            
+            me.fireEvent('show', me, me.el, me.store);
+            me.loading = true;
         }
     },
 
-    <div id="method-Ext.LoadMask-show"></div>/**
-     * Show this LoadMask over the configured Element.
+<span id='Ext-LoadMask-method-show'>    /**
+</span>     * Show this LoadMask over the configured Element.
      */
-    show: function(){
+    show: function() {
         this.onBeforeLoad();
     },
 
-    <div id="method-Ext.LoadMask-hide"></div>/**
-     * Hide this LoadMask.
+<span id='Ext-LoadMask-method-hide'>    /**
+</span>     * Hide this LoadMask.
      */
-    hide: function(){
+    hide: function() {
         this.onLoad();
     },
 
     // private
-    destroy : function(){
-        if(this.store){
-            this.store.un('beforeload', this.onBeforeLoad, this);
-            this.store.un('load', this.onLoad, this);
-            this.store.un('exception', this.onLoad, this);
-        }else{
-            var um = this.el.getUpdater();
-            um.un('beforeupdate', this.onBeforeLoad, this);
-            um.un('update', this.onLoad, this);
-            um.un('failure', this.onLoad, this);
-        }
+    destroy : function() {
+        this.hide();
+        this.clearListeners();
     }
-};</pre>    \r
-</body>\r
-</html>
\ No newline at end of file
+});
+</pre>
+</body>
+</html>