Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / LoadMask.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-LoadMask'>/**
19 </span> * @class Ext.LoadMask
20  * &lt;p&gt;A modal, floating Component which may be shown above a specified {@link Ext.core.Element Element}, or a specified
21  * {@link Ext.Component Component} while loading data. When shown, the configured owning Element or Component will
22  * be covered with a modality mask, and the LoadMask's {@link #msg} will be displayed centered, accompanied by a spinner image.&lt;/p&gt;
23  * &lt;p&gt;If the {@link #store} config option is specified, the masking will be automatically shown and then hidden synchronized with
24  * the Store's loading process.&lt;/p&gt;
25  * &lt;p&gt;Because this is a floating Component, its z-index will be managed by the global {@link Ext.WindowManager ZIndexManager}
26  * object, and upon show, it will place itsef at the top of the hierarchy.&lt;/p&gt;
27  * &lt;p&gt;Example usage:&lt;/p&gt;
28  * &lt;pre&gt;&lt;code&gt;
29 // Basic mask:
30 var myMask = new Ext.LoadMask(Ext.getBody(), {msg:&quot;Please wait...&quot;});
31 myMask.show();
32 &lt;/code&gt;&lt;/pre&gt;
33
34  */
35
36 Ext.define('Ext.LoadMask', {
37
38     extend: 'Ext.Component',
39
40     alias: 'widget.loadmask',
41
42     /* Begin Definitions */
43
44     mixins: {
45         floating: 'Ext.util.Floating'
46     },
47
48     uses: ['Ext.data.StoreManager'],
49
50     /* End Definitions */
51
52 <span id='Ext-LoadMask-cfg-store'>    /**
53 </span>     * @cfg {Ext.data.Store} store
54      * Optional Store to which the mask is bound. The mask is displayed when a load request is issued, and
55      * hidden on either load success, or load fail.
56      */
57
58 <span id='Ext-LoadMask-cfg-msg'>    /**
59 </span>     * @cfg {String} msg
60      * The text to display in a centered loading message box.
61      */
62     msg : 'Loading...',
63 <span id='Ext-LoadMask-cfg-msgCls'>    /**
64 </span>     * @cfg {String} [msgCls=&quot;x-mask-loading&quot;]
65      * The CSS class to apply to the loading message element.
66      */
67     msgCls : Ext.baseCSSPrefix + 'mask-loading',
68     
69 <span id='Ext-LoadMask-cfg-useMsg'>    /**
70 </span>     * @cfg {Boolean} useMsg
71      * Whether or not to use a loading message class or simply mask the bound element.
72      */
73     useMsg: true,
74
75 <span id='Ext-LoadMask-property-disabled'>    /**
76 </span>     * Read-only. True if the mask is currently disabled so that it will not be displayed
77      * @type Boolean
78      */
79     disabled: false,
80
81     baseCls: Ext.baseCSSPrefix + 'mask-msg',
82
83     renderTpl: '&lt;div style=&quot;position:relative&quot; class=&quot;{msgCls}&quot;&gt;&lt;/div&gt;',
84
85     // Private. The whole point is that there's a mask.
86     modal: true,
87
88     // Private. Obviously, it's floating.
89     floating: {
90         shadow: 'frame'
91     },
92
93     // Private. Masks are not focusable
94     focusOnToFront: false,
95
96 <span id='Ext-LoadMask-method-constructor'>    /**
97 </span>     * Creates new LoadMask.
98      * @param {String/HTMLElement/Ext.Element} el The element, element ID, or DOM node you wish to mask.
99      * &lt;p&gt;Also, may be a {@link Ext.Component Component} who's element you wish to mask. If a Component is specified, then
100      * the mask will be automatically sized upon Component resize, the message box will be kept centered,
101      * and the mask only be visible when the Component is.&lt;/p&gt;
102      * @param {Object} [config] The config object
103      */
104     constructor : function(el, config) {
105         var me = this;
106
107         // If a Component passed, bind to it.
108         if (el.isComponent) {
109             me.ownerCt = el;
110             me.bindComponent(el);
111         }
112         // Create a dumy Component encapsulating the specified Element
113         else {
114             me.ownerCt = new Ext.Component({
115                 el: Ext.get(el),
116                 rendered: true,
117                 componentLayoutCounter: 1
118             });
119             me.container = el;
120         }
121         me.callParent([config]);
122
123         if (me.store) {
124             me.bindStore(me.store, true);
125         }
126         me.renderData = {
127             msgCls: me.msgCls
128         };
129         me.renderSelectors = {
130             msgEl: 'div'
131         };
132     },
133
134     bindComponent: function(comp) {
135         this.mon(comp, {
136             resize: this.onComponentResize,
137             scope: this
138         });
139     },
140
141     afterRender: function() {
142         this.callParent(arguments);
143         this.container = this.floatParent.getContentTarget();
144     },
145
146 <span id='Ext-LoadMask-method-onComponentResize'>    /**
147 </span>     * @private
148      * Called when this LoadMask's Component is resized. The toFront method rebases and resizes the modal mask.
149      */
150     onComponentResize: function() {
151         var me = this;
152         if (me.rendered &amp;&amp; me.isVisible()) {
153             me.toFront();
154             me.center();
155         }
156     },
157
158 <span id='Ext-LoadMask-method-bindStore'>    /**
159 </span>     * Changes the data store bound to this LoadMask.
160      * @param {Ext.data.Store} store The store to bind to this LoadMask
161      */
162     bindStore : function(store, initial) {
163         var me = this;
164
165         if (!initial &amp;&amp; me.store) {
166             me.mun(me.store, {
167                 scope: me,
168                 beforeload: me.onBeforeLoad,
169                 load: me.onLoad,
170                 exception: me.onLoad
171             });
172             if (!store) {
173                 me.store = null;
174             }
175         }
176         if (store) {
177             store = Ext.data.StoreManager.lookup(store);
178             me.mon(store, {
179                 scope: me,
180                 beforeload: me.onBeforeLoad,
181                 load: me.onLoad,
182                 exception: me.onLoad
183             });
184
185         }
186         me.store = store;
187         if (store &amp;&amp; store.isLoading()) {
188             me.onBeforeLoad();
189         }
190     },
191
192     onDisable : function() {
193         this.callParent(arguments);
194         if (this.loading) {
195             this.onLoad();
196         }
197     },
198
199     // private
200     onBeforeLoad : function() {
201         var me = this,
202             owner = me.ownerCt || me.floatParent,
203             origin;
204         if (!this.disabled) {
205             // If the owning Component has not been layed out, defer so that the ZIndexManager
206             // gets to read its layed out size when sizing the modal mask
207             if (owner.componentLayoutCounter) {
208                 Ext.Component.prototype.show.call(me);
209             } else {
210                 // The code below is a 'run-once' interceptor.
211                 origin = owner.afterComponentLayout;
212                 owner.afterComponentLayout = function() {
213                     owner.afterComponentLayout = origin;
214                     origin.apply(owner, arguments);
215                     if(me.loading) {
216                         Ext.Component.prototype.show.call(me);
217                     }
218                 };
219             }
220         }
221     },
222
223     onHide: function(){
224         var me = this;
225         me.callParent(arguments);
226         me.showOnParentShow = true;
227     },
228
229     onShow: function() {
230         var me = this,
231             msgEl = me.msgEl;
232             
233         me.callParent(arguments);
234         me.loading = true;
235         if (me.useMsg) {
236             msgEl.show().update(me.msg);
237         } else {
238             msgEl.parent().hide();
239         }
240     },
241
242     afterShow: function() {
243         this.callParent(arguments);
244         this.center();
245     },
246
247     // private
248     onLoad : function() {
249         this.loading = false;
250         Ext.Component.prototype.hide.call(this);
251     }
252 });</pre>
253 </body>
254 </html>