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