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