Upgrade to ExtJS 3.2.0 - Released 03/30/2010
[extjs.git] / docs / source / Layer.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.2.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.Layer"></div>/**
16  * @class Ext.Layer
17  * @extends Ext.Element
18  * An extended {@link Ext.Element} object that supports a shadow and shim, constrain to viewport and
19  * automatic maintaining of shadow/shim positions.
20  * @cfg {Boolean} shim False to disable the iframe shim in browsers which need one (defaults to true)
21  * @cfg {String/Boolean} shadow True to automatically create an {@link Ext.Shadow}, or a string indicating the
22  * shadow's display {@link Ext.Shadow#mode}. False to disable the shadow. (defaults to false)
23  * @cfg {Object} dh DomHelper object config to create element with (defaults to {tag: 'div', cls: 'x-layer'}).
24  * @cfg {Boolean} constrain False to disable constrain to viewport (defaults to true)
25  * @cfg {String} cls CSS class to add to the element
26  * @cfg {Number} zindex Starting z-index (defaults to 11000)
27  * @cfg {Number} shadowOffset Number of pixels to offset the shadow (defaults to 4)
28  * @cfg {Boolean} useDisplay
29  * Defaults to use css offsets to hide the Layer. Specify <tt>true</tt>
30  * to use css style <tt>'display:none;'</tt> to hide the Layer.
31  * @constructor
32  * @param {Object} config An object with config options.
33  * @param {String/HTMLElement} existingEl (optional) Uses an existing DOM element. If the element is not found it creates it.
34  */
35 (function(){
36 Ext.Layer = function(config, existingEl){
37     config = config || {};
38     var dh = Ext.DomHelper;
39     var cp = config.parentEl, pel = cp ? Ext.getDom(cp) : document.body;
40     if(existingEl){
41         this.dom = Ext.getDom(existingEl);
42     }
43     if(!this.dom){
44         var o = config.dh || {tag: 'div', cls: 'x-layer'};
45         this.dom = dh.append(pel, o);
46     }
47     if(config.cls){
48         this.addClass(config.cls);
49     }
50     this.constrain = config.constrain !== false;
51     this.setVisibilityMode(Ext.Element.VISIBILITY);
52     if(config.id){
53         this.id = this.dom.id = config.id;
54     }else{
55         this.id = Ext.id(this.dom);
56     }
57     this.zindex = config.zindex || this.getZIndex();
58     this.position('absolute', this.zindex);
59     if(config.shadow){
60         this.shadowOffset = config.shadowOffset || 4;
61         this.shadow = new Ext.Shadow({
62             offset : this.shadowOffset,
63             mode : config.shadow
64         });
65     }else{
66         this.shadowOffset = 0;
67     }
68     this.useShim = config.shim !== false && Ext.useShims;
69     this.useDisplay = config.useDisplay;
70     this.hide();
71 };
72
73 var supr = Ext.Element.prototype;
74
75 // shims are shared among layer to keep from having 100 iframes
76 var shims = [];
77
78 Ext.extend(Ext.Layer, Ext.Element, {
79
80     getZIndex : function(){
81         return this.zindex || parseInt((this.getShim() || this).getStyle('z-index'), 10) || 11000;
82     },
83
84     getShim : function(){
85         if(!this.useShim){
86             return null;
87         }
88         if(this.shim){
89             return this.shim;
90         }
91         var shim = shims.shift();
92         if(!shim){
93             shim = this.createShim();
94             shim.enableDisplayMode('block');
95             shim.dom.style.display = 'none';
96             shim.dom.style.visibility = 'visible';
97         }
98         var pn = this.dom.parentNode;
99         if(shim.dom.parentNode != pn){
100             pn.insertBefore(shim.dom, this.dom);
101         }
102         shim.setStyle('z-index', this.getZIndex()-2);
103         this.shim = shim;
104         return shim;
105     },
106
107     hideShim : function(){
108         if(this.shim){
109             this.shim.setDisplayed(false);
110             shims.push(this.shim);
111             delete this.shim;
112         }
113     },
114
115     disableShadow : function(){
116         if(this.shadow){
117             this.shadowDisabled = true;
118             this.shadow.hide();
119             this.lastShadowOffset = this.shadowOffset;
120             this.shadowOffset = 0;
121         }
122     },
123
124     enableShadow : function(show){
125         if(this.shadow){
126             this.shadowDisabled = false;
127             this.shadowOffset = this.lastShadowOffset;
128             delete this.lastShadowOffset;
129             if(show){
130                 this.sync(true);
131             }
132         }
133     },
134
135     // private
136     // this code can execute repeatedly in milliseconds (i.e. during a drag) so
137     // code size was sacrificed for effeciency (e.g. no getBox/setBox, no XY calls)
138     sync : function(doShow){
139         var shadow = this.shadow;
140         if(!this.updating && this.isVisible() && (shadow || this.useShim)){
141             var shim = this.getShim(),
142                 w = this.getWidth(),
143                 h = this.getHeight(),
144                 l = this.getLeft(true),
145                 t = this.getTop(true);
146
147             if(shadow && !this.shadowDisabled){
148                 if(doShow && !shadow.isVisible()){
149                     shadow.show(this);
150                 }else{
151                     shadow.realign(l, t, w, h);
152                 }
153                 if(shim){
154                     if(doShow){
155                        shim.show();
156                     }
157                     // fit the shim behind the shadow, so it is shimmed too
158                     var shadowAdj = shadow.el.getXY(), shimStyle = shim.dom.style,
159                         shadowSize = shadow.el.getSize();
160                     shimStyle.left = (shadowAdj[0])+'px';
161                     shimStyle.top = (shadowAdj[1])+'px';
162                     shimStyle.width = (shadowSize.width)+'px';
163                     shimStyle.height = (shadowSize.height)+'px';
164                 }
165             }else if(shim){
166                 if(doShow){
167                    shim.show();
168                 }
169                 shim.setSize(w, h);
170                 shim.setLeftTop(l, t);
171             }
172         }
173     },
174
175     // private
176     destroy : function(){
177         this.hideShim();
178         if(this.shadow){
179             this.shadow.hide();
180         }
181         this.removeAllListeners();
182         Ext.removeNode(this.dom);
183         delete this.dom;
184     },
185
186     remove : function(){
187         this.destroy();
188     },
189
190     // private
191     beginUpdate : function(){
192         this.updating = true;
193     },
194
195     // private
196     endUpdate : function(){
197         this.updating = false;
198         this.sync(true);
199     },
200
201     // private
202     hideUnders : function(negOffset){
203         if(this.shadow){
204             this.shadow.hide();
205         }
206         this.hideShim();
207     },
208
209     // private
210     constrainXY : function(){
211         if(this.constrain){
212             var vw = Ext.lib.Dom.getViewWidth(),
213                 vh = Ext.lib.Dom.getViewHeight();
214             var s = Ext.getDoc().getScroll();
215
216             var xy = this.getXY();
217             var x = xy[0], y = xy[1];
218             var so = this.shadowOffset;
219             var w = this.dom.offsetWidth+so, h = this.dom.offsetHeight+so;
220             // only move it if it needs it
221             var moved = false;
222             // first validate right/bottom
223             if((x + w) > vw+s.left){
224                 x = vw - w - so;
225                 moved = true;
226             }
227             if((y + h) > vh+s.top){
228                 y = vh - h - so;
229                 moved = true;
230             }
231             // then make sure top/left isn't negative
232             if(x < s.left){
233                 x = s.left;
234                 moved = true;
235             }
236             if(y < s.top){
237                 y = s.top;
238                 moved = true;
239             }
240             if(moved){
241                 if(this.avoidY){
242                     var ay = this.avoidY;
243                     if(y <= ay && (y+h) >= ay){
244                         y = ay-h-5;
245                     }
246                 }
247                 xy = [x, y];
248                 this.storeXY(xy);
249                 supr.setXY.call(this, xy);
250                 this.sync();
251             }
252         }
253         return this;
254     },
255
256     isVisible : function(){
257         return this.visible;
258     },
259
260     // private
261     showAction : function(){
262         this.visible = true; // track visibility to prevent getStyle calls
263         if(this.useDisplay === true){
264             this.setDisplayed('');
265         }else if(this.lastXY){
266             supr.setXY.call(this, this.lastXY);
267         }else if(this.lastLT){
268             supr.setLeftTop.call(this, this.lastLT[0], this.lastLT[1]);
269         }
270     },
271
272     // private
273     hideAction : function(){
274         this.visible = false;
275         if(this.useDisplay === true){
276             this.setDisplayed(false);
277         }else{
278             this.setLeftTop(-10000,-10000);
279         }
280     },
281
282     // overridden Element method
283     setVisible : function(v, a, d, c, e){
284         if(v){
285             this.showAction();
286         }
287         if(a && v){
288             var cb = function(){
289                 this.sync(true);
290                 if(c){
291                     c();
292                 }
293             }.createDelegate(this);
294             supr.setVisible.call(this, true, true, d, cb, e);
295         }else{
296             if(!v){
297                 this.hideUnders(true);
298             }
299             var cb = c;
300             if(a){
301                 cb = function(){
302                     this.hideAction();
303                     if(c){
304                         c();
305                     }
306                 }.createDelegate(this);
307             }
308             supr.setVisible.call(this, v, a, d, cb, e);
309             if(v){
310                 this.sync(true);
311             }else if(!a){
312                 this.hideAction();
313             }
314         }
315         return this;
316     },
317
318     storeXY : function(xy){
319         delete this.lastLT;
320         this.lastXY = xy;
321     },
322
323     storeLeftTop : function(left, top){
324         delete this.lastXY;
325         this.lastLT = [left, top];
326     },
327
328     // private
329     beforeFx : function(){
330         this.beforeAction();
331         return Ext.Layer.superclass.beforeFx.apply(this, arguments);
332     },
333
334     // private
335     afterFx : function(){
336         Ext.Layer.superclass.afterFx.apply(this, arguments);
337         this.sync(this.isVisible());
338     },
339
340     // private
341     beforeAction : function(){
342         if(!this.updating && this.shadow){
343             this.shadow.hide();
344         }
345     },
346
347     // overridden Element method
348     setLeft : function(left){
349         this.storeLeftTop(left, this.getTop(true));
350         supr.setLeft.apply(this, arguments);
351         this.sync();
352         return this;
353     },
354
355     setTop : function(top){
356         this.storeLeftTop(this.getLeft(true), top);
357         supr.setTop.apply(this, arguments);
358         this.sync();
359         return this;
360     },
361
362     setLeftTop : function(left, top){
363         this.storeLeftTop(left, top);
364         supr.setLeftTop.apply(this, arguments);
365         this.sync();
366         return this;
367     },
368
369     setXY : function(xy, a, d, c, e){
370         this.fixDisplay();
371         this.beforeAction();
372         this.storeXY(xy);
373         var cb = this.createCB(c);
374         supr.setXY.call(this, xy, a, d, cb, e);
375         if(!a){
376             cb();
377         }
378         return this;
379     },
380
381     // private
382     createCB : function(c){
383         var el = this;
384         return function(){
385             el.constrainXY();
386             el.sync(true);
387             if(c){
388                 c();
389             }
390         };
391     },
392
393     // overridden Element method
394     setX : function(x, a, d, c, e){
395         this.setXY([x, this.getY()], a, d, c, e);
396         return this;
397     },
398
399     // overridden Element method
400     setY : function(y, a, d, c, e){
401         this.setXY([this.getX(), y], a, d, c, e);
402         return this;
403     },
404
405     // overridden Element method
406     setSize : function(w, h, a, d, c, e){
407         this.beforeAction();
408         var cb = this.createCB(c);
409         supr.setSize.call(this, w, h, a, d, cb, e);
410         if(!a){
411             cb();
412         }
413         return this;
414     },
415
416     // overridden Element method
417     setWidth : function(w, a, d, c, e){
418         this.beforeAction();
419         var cb = this.createCB(c);
420         supr.setWidth.call(this, w, a, d, cb, e);
421         if(!a){
422             cb();
423         }
424         return this;
425     },
426
427     // overridden Element method
428     setHeight : function(h, a, d, c, e){
429         this.beforeAction();
430         var cb = this.createCB(c);
431         supr.setHeight.call(this, h, a, d, cb, e);
432         if(!a){
433             cb();
434         }
435         return this;
436     },
437
438     // overridden Element method
439     setBounds : function(x, y, w, h, a, d, c, e){
440         this.beforeAction();
441         var cb = this.createCB(c);
442         if(!a){
443             this.storeXY([x, y]);
444             supr.setXY.call(this, [x, y]);
445             supr.setSize.call(this, w, h, a, d, cb, e);
446             cb();
447         }else{
448             supr.setBounds.call(this, x, y, w, h, a, d, cb, e);
449         }
450         return this;
451     },
452
453     /**
454      * Sets the z-index of this layer and adjusts any shadow and shim z-indexes. The layer z-index is automatically
455      * incremented by two more than the value passed in so that it always shows above any shadow or shim (the shadow
456      * element, if any, will be assigned z-index + 1, and the shim element, if any, will be assigned the unmodified z-index).
457      * @param {Number} zindex The new z-index to set
458      * @return {this} The Layer
459      */
460     setZIndex : function(zindex){
461         this.zindex = zindex;
462         this.setStyle('z-index', zindex + 2);
463         if(this.shadow){
464             this.shadow.setZIndex(zindex + 1);
465         }
466         if(this.shim){
467             this.shim.setStyle('z-index', zindex);
468         }
469         return this;
470     }
471 });
472 })();
473 </pre>    
474 </body>
475 </html>