src/widgets/LoadMask.js

   1 /*!
   2  * Ext JS Library 3.2.1
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   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({
  29             scope: this,
  30             beforeload: this.onBeforeLoad,
  31             load: this.onLoad,
  32             exception: this.onLoad
  33         });
  34         this.removeMask = Ext.value(this.removeMask, false);
  35     }else{
  36         var um = this.el.getUpdater();
  37         um.showLoadIndicator = false; // disable the default indicator
  38         um.on({
  39             scope: this,
  40             beforeupdate: this.onBeforeLoad,
  41             update: this.onLoad,
  42             failure: this.onLoad
  43         });
  44         this.removeMask = Ext.value(this.removeMask, true);
  45     }
  46 };
  47
  48 Ext.LoadMask.prototype = {
  49     /**
  50      * @cfg {Ext.data.Store} store
  51      * Optional Store to which the mask is bound. The mask is displayed when a load request is issued, and
  52      * hidden on either load sucess, or load fail.
  53      */
  54     /**
  55      * @cfg {Boolean} removeMask
  56      * True to create a single-use mask that is automatically destroyed after loading (useful for page loads),
  57      * False to persist the mask element reference for multiple uses (e.g., for paged data widgets).  Defaults to false.
  58      */
  59     /**
  60      * @cfg {String} msg
  61      * The text to display in a centered loading message box (defaults to 'Loading...')
  62      */
  63     msg : 'Loading...',
  64     /**
  65      * @cfg {String} msgCls
  66      * The CSS class to apply to the loading message element (defaults to "x-mask-loading")
  67      */
  68     msgCls : 'x-mask-loading',
  69
  70     /**
  71      * Read-only. True if the mask is currently disabled so that it will not be displayed (defaults to false)
  72      * @type Boolean
  73      */
  74     disabled: false,
  75
  76     /**
  77      * Disables the mask to prevent it from being displayed
  78      */
  79     disable : function(){
  80        this.disabled = true;
  81     },
  82
  83     /**
  84      * Enables the mask so that it can be displayed
  85      */
  86     enable : function(){
  87         this.disabled = false;
  88     },
  89
  90     // private
  91     onLoad : function(){
  92         this.el.unmask(this.removeMask);
  93     },
  94
  95     // private
  96     onBeforeLoad : function(){
  97         if(!this.disabled){
  98             this.el.mask(this.msg, this.msgCls);
  99         }
 100     },
 101
 102     /**
 103      * Show this LoadMask over the configured Element.
 104      */
 105     show: function(){
 106         this.onBeforeLoad();
 107     },
 108
 109     /**
 110      * Hide this LoadMask.
 111      */
 112     hide: function(){
 113         this.onLoad();
 114     },
 115
 116     // private
 117     destroy : function(){
 118         if(this.store){
 119             this.store.un('beforeload', this.onBeforeLoad, this);
 120             this.store.un('load', this.onLoad, this);
 121             this.store.un('exception', this.onLoad, this);
 122         }else{
 123             var um = this.el.getUpdater();
 124             um.un('beforeupdate', this.onBeforeLoad, this);
 125             um.un('update', this.onLoad, this);
 126             um.un('failure', this.onLoad, this);
 127         }
 128     }
 129 };