src/widgets/LoadMask.js

   1 /*!
   2  * Ext JS Library 3.0.3
   3  * Copyright(c) 2006-2009 Ext JS, LLC
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.LoadMask
   9  * A simple utility class for generically masking elements while loading data.  If the {@link #store}
  10  * config option is specified, the masking will be automatically synchronized with the store's loading
  11  * process and the mask element will be cached for reuse.  For all other elements, this mask will replace the
  12  * element's Updater load indicator and will be destroyed after the initial load.
  13  * <p>Example usage:</p>
  14  *<pre><code>
  15 // Basic mask:
  16 var myMask = new Ext.LoadMask(Ext.getBody(), {msg:"Please wait..."});
  17 myMask.show();
  18 </code></pre>
  19  * @constructor
  20  * Create a new LoadMask
  21  * @param {Mixed} el The element or DOM node, or its id
  22  * @param {Object} config The config object
  23  */
  24 Ext.LoadMask = function(el, config){
  25     this.el = Ext.get(el);
  26     Ext.apply(this, config);
  27     if(this.store){
  28         this.store.on('beforeload', this.onBeforeLoad, this);
  29         this.store.on('load', this.onLoad, this);
  30         this.store.on('exception', this.onLoad, this);
  31         this.removeMask = Ext.value(this.removeMask, false);
  32     }else{
  33         var um = this.el.getUpdater();
  34         um.showLoadIndicator = false; // disable the default indicator
  35         um.on('beforeupdate', this.onBeforeLoad, this);
  36         um.on('update', this.onLoad, this);
  37         um.on('failure', this.onLoad, this);
  38         this.removeMask = Ext.value(this.removeMask, true);
  39     }
  40 };
  41
  42 Ext.LoadMask.prototype = {
  43     /**
  44      * @cfg {Ext.data.Store} store
  45      * Optional Store to which the mask is bound. The mask is displayed when a load request is issued, and
  46      * hidden on either load sucess, or load fail.
  47      */
  48     /**
  49      * @cfg {Boolean} removeMask
  50      * True to create a single-use mask that is automatically destroyed after loading (useful for page loads),
  51      * False to persist the mask element reference for multiple uses (e.g., for paged data widgets).  Defaults to false.
  52      */
  53     /**
  54      * @cfg {String} msg
  55      * The text to display in a centered loading message box (defaults to 'Loading...')
  56      */
  57     msg : 'Loading...',
  58     /**
  59      * @cfg {String} msgCls
  60      * The CSS class to apply to the loading message element (defaults to "x-mask-loading")
  61      */
  62     msgCls : 'x-mask-loading',
  63
  64     /**
  65      * Read-only. True if the mask is currently disabled so that it will not be displayed (defaults to false)
  66      * @type Boolean
  67      */
  68     disabled: false,
  69
  70     /**
  71      * Disables the mask to prevent it from being displayed
  72      */
  73     disable : function(){
  74        this.disabled = true;
  75     },
  76
  77     /**
  78      * Enables the mask so that it can be displayed
  79      */
  80     enable : function(){
  81         this.disabled = false;
  82     },
  83
  84     // private
  85     onLoad : function(){
  86         this.el.unmask(this.removeMask);
  87     },
  88
  89     // private
  90     onBeforeLoad : function(){
  91         if(!this.disabled){
  92             this.el.mask(this.msg, this.msgCls);
  93         }
  94     },
  95
  96     /**
  97      * Show this LoadMask over the configured Element.
  98      */
  99     show: function(){
 100         this.onBeforeLoad();
 101     },
 102
 103     /**
 104      * Hide this LoadMask.
 105      */
 106     hide: function(){
 107         this.onLoad();
 108     },
 109
 110     // private
 111     destroy : function(){
 112         if(this.store){
 113             this.store.un('beforeload', this.onBeforeLoad, this);
 114             this.store.un('load', this.onLoad, this);
 115             this.store.un('exception', this.onLoad, this);
 116         }else{
 117             var um = this.el.getUpdater();
 118             um.un('beforeupdate', this.onBeforeLoad, this);
 119             um.un('update', this.onLoad, this);
 120             um.un('failure', this.onLoad, this);
 121         }
 122     }
 123 };