source/widgets/LoadMask.js

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