2 * Ext JS Library 2.2.1
\r
3 * Copyright(c) 2006-2009, Ext JS, LLC.
\r
4 * licensing@extjs.com
\r
6 * http://extjs.com/license
\r
10 * @class Ext.BoxComponent
\r
11 * @extends Ext.Component
\r
12 * <p>Base class for any visual {@link Ext.Component} that uses a box container. BoxComponent provides automatic box
\r
13 * model adjustments for sizing and positioning and will work correctly withnin the Component rendering model. All
\r
14 * container classes should subclass BoxComponent so that they will work consistently when nested within other Ext
\r
15 * layout containers.</p>
\r
16 * <p>A BoxComponent may be created as a custom Component which encapsulates any HTML element, either a pre-existing
\r
17 * element, or one that is created to your specifications at render time. Usually, to participate in layouts,
\r
18 * a Component will need to be a <b>Box</b>Component in order to have its width and height managed.</p>
\r
19 * <p>To use a pre-existing element as a BoxComponent, configure it so that you preset the <b>el</b> property to the
\r
20 * element to reference:<pre><code>
\r
21 var pageHeader = new Ext.BoxComponent({
\r
24 * This may then be {@link Ext.Container#add added} to a {@link Ext.Container Container} as a child item.</p>
\r
25 * <p>To create a BoxComponent based around a HTML element to be created at render time, use the
\r
26 * {@link Ext.Component#autoEl autoEl} config option which takes the form of a
\r
27 * {@link Ext.DomHelper DomHelper} specification:<pre><code>
\r
28 var myImage = new Ext.BoxComponent({
\r
31 src: '/images/my-image.jpg'
\r
33 });</code></pre></p>
\r
35 * @param {Ext.Element/String/Object} config The configuration options.
\r
37 Ext.BoxComponent = Ext.extend(Ext.Component, {
\r
40 * The local x (left) coordinate for this component if contained within a positioning container.
\r
44 * The local y (top) coordinate for this component if contained within a positioning container.
\r
47 * @cfg {Number} pageX
\r
48 * The page level x coordinate for this component if contained within a positioning container.
\r
51 * @cfg {Number} pageY
\r
52 * The page level y coordinate for this component if contained within a positioning container.
\r
55 * @cfg {Number} height
\r
56 * The height of this component in pixels (defaults to auto).
\r
59 * @cfg {Number} width
\r
60 * The width of this component in pixels (defaults to auto).
\r
63 * @cfg {Boolean} autoHeight
\r
64 * True to use height:'auto', false to use fixed height (defaults to false). <b>Note</b>: Although many components
\r
65 * inherit this config option, not all will function as expected with a height of 'auto'. Setting autoHeight:true
\r
66 * means that the browser will manage height based on the element's contents, and that Ext will not manage it at all.
\r
69 * @cfg {Boolean} autoWidth
\r
70 * True to use width:'auto', false to use fixed width (defaults to false). <b>Note</b>: Although many components
\r
71 * inherit this config option, not all will function as expected with a width of 'auto'. Setting autoWidth:true
\r
72 * means that the browser will manage width based on the element's contents, and that Ext will not manage it at all.
\r
75 /* // private internal config
\r
76 * {Boolean} deferHeight
\r
77 * True to defer height calculations to an external component, false to allow this component to set its own
\r
78 * height (defaults to false).
\r
82 initComponent : function(){
\r
83 Ext.BoxComponent.superclass.initComponent.call(this);
\r
87 * Fires after the component is resized.
\r
88 * @param {Ext.Component} this
\r
89 * @param {Number} adjWidth The box-adjusted width that was set
\r
90 * @param {Number} adjHeight The box-adjusted height that was set
\r
91 * @param {Number} rawWidth The width that was originally specified
\r
92 * @param {Number} rawHeight The height that was originally specified
\r
97 * Fires after the component is moved.
\r
98 * @param {Ext.Component} this
\r
99 * @param {Number} x The new x position
\r
100 * @param {Number} y The new y position
\r
106 // private, set in afterRender to signify that the component has been rendered
\r
108 // private, used to defer height settings to subclasses
\r
109 deferHeight: false,
\r
112 * Sets the width and height of the component. This method fires the {@link #resize} event. This method can accept
\r
113 * either width and height as separate numeric arguments, or you can pass a size object like {width:10, height:20}.
\r
114 * @param {Number/Object} width The new width to set, or a size object in the format {width, height}
\r
115 * @param {Number} height The new height to set (not required if a size object is passed as the first arg)
\r
116 * @return {Ext.BoxComponent} this
\r
118 setSize : function(w, h){
\r
119 // support for standard size objects
\r
120 if(typeof w == 'object'){
\r
125 if(!this.boxReady){
\r
131 // prevent recalcs when not needed
\r
132 if(this.lastSize && this.lastSize.width == w && this.lastSize.height == h){
\r
135 this.lastSize = {width: w, height: h};
\r
136 var adj = this.adjustSize(w, h);
\r
137 var aw = adj.width, ah = adj.height;
\r
138 if(aw !== undefined || ah !== undefined){ // this code is nasty but performs better with floaters
\r
139 var rz = this.getResizeEl();
\r
140 if(!this.deferHeight && aw !== undefined && ah !== undefined){
\r
141 rz.setSize(aw, ah);
\r
142 }else if(!this.deferHeight && ah !== undefined){
\r
144 }else if(aw !== undefined){
\r
147 this.onResize(aw, ah, w, h);
\r
148 this.fireEvent('resize', this, aw, ah, w, h);
\r
154 * Sets the width of the component. This method fires the {@link #resize} event.
\r
155 * @param {Number} width The new width to set
\r
156 * @return {Ext.BoxComponent} this
\r
158 setWidth : function(width){
\r
159 return this.setSize(width);
\r
163 * Sets the height of the component. This method fires the {@link #resize} event.
\r
164 * @param {Number} height The new height to set
\r
165 * @return {Ext.BoxComponent} this
\r
167 setHeight : function(height){
\r
168 return this.setSize(undefined, height);
\r
172 * Gets the current size of the component's underlying element.
\r
173 * @return {Object} An object containing the element's size {width: (element width), height: (element height)}
\r
175 getSize : function(){
\r
176 return this.el.getSize();
\r
180 * Gets the current XY position of the component's underlying element.
\r
181 * @param {Boolean} local (optional) If true the element's left and top are returned instead of page XY (defaults to false)
\r
182 * @return {Array} The XY position of the element (e.g., [100, 200])
\r
184 getPosition : function(local){
\r
185 if(local === true){
\r
186 return [this.el.getLeft(true), this.el.getTop(true)];
\r
188 return this.xy || this.el.getXY();
\r
192 * Gets the current box measurements of the component's underlying element.
\r
193 * @param {Boolean} local (optional) If true the element's left and top are returned instead of page XY (defaults to false)
\r
194 * @return {Object} box An object in the format {x, y, width, height}
\r
196 getBox : function(local){
\r
197 var s = this.el.getSize();
\r
198 if(local === true){
\r
199 s.x = this.el.getLeft(true);
\r
200 s.y = this.el.getTop(true);
\r
202 var xy = this.xy || this.el.getXY();
\r
210 * Sets the current box measurements of the component's underlying element.
\r
211 * @param {Object} box An object in the format {x, y, width, height}
\r
212 * @return {Ext.BoxComponent} this
\r
214 updateBox : function(box){
\r
215 this.setSize(box.width, box.height);
\r
216 this.setPagePosition(box.x, box.y);
\r
221 getResizeEl : function(){
\r
222 return this.resizeEl || this.el;
\r
226 getPositionEl : function(){
\r
227 return this.positionEl || this.el;
\r
231 * Sets the left and top of the component. To set the page XY position instead, use {@link #setPagePosition}.
\r
232 * This method fires the {@link #move} event.
\r
233 * @param {Number} left The new left
\r
234 * @param {Number} top The new top
\r
235 * @return {Ext.BoxComponent} this
\r
237 setPosition : function(x, y){
\r
238 if(x && typeof x[1] == 'number'){
\r
244 if(!this.boxReady){
\r
247 var adj = this.adjustPosition(x, y);
\r
248 var ax = adj.x, ay = adj.y;
\r
250 var el = this.getPositionEl();
\r
251 if(ax !== undefined || ay !== undefined){
\r
252 if(ax !== undefined && ay !== undefined){
\r
253 el.setLeftTop(ax, ay);
\r
254 }else if(ax !== undefined){
\r
256 }else if(ay !== undefined){
\r
259 this.onPosition(ax, ay);
\r
260 this.fireEvent('move', this, ax, ay);
\r
266 * Sets the page XY position of the component. To set the left and top instead, use {@link #setPosition}.
\r
267 * This method fires the {@link #move} event.
\r
268 * @param {Number} x The new x position
\r
269 * @param {Number} y The new y position
\r
270 * @return {Ext.BoxComponent} this
\r
272 setPagePosition : function(x, y){
\r
273 if(x && typeof x[1] == 'number'){
\r
279 if(!this.boxReady){
\r
282 if(x === undefined || y === undefined){ // cannot translate undefined points
\r
285 var p = this.el.translatePoints(x, y);
\r
286 this.setPosition(p.left, p.top);
\r
291 onRender : function(ct, position){
\r
292 Ext.BoxComponent.superclass.onRender.call(this, ct, position);
\r
294 this.resizeEl = Ext.get(this.resizeEl);
\r
296 if(this.positionEl){
\r
297 this.positionEl = Ext.get(this.positionEl);
\r
302 afterRender : function(){
\r
303 Ext.BoxComponent.superclass.afterRender.call(this);
\r
304 this.boxReady = true;
\r
305 this.setSize(this.width, this.height);
\r
306 if(this.x || this.y){
\r
307 this.setPosition(this.x, this.y);
\r
308 }else if(this.pageX || this.pageY){
\r
309 this.setPagePosition(this.pageX, this.pageY);
\r
314 * Force the component's size to recalculate based on the underlying element's current height and width.
\r
315 * @return {Ext.BoxComponent} this
\r
317 syncSize : function(){
\r
318 delete this.lastSize;
\r
319 this.setSize(this.autoWidth ? undefined : this.el.getWidth(), this.autoHeight ? undefined : this.el.getHeight());
\r
324 * Called after the component is resized, this method is empty by default but can be implemented by any
\r
325 * subclass that needs to perform custom logic after a resize occurs.
\r
326 * @param {Number} adjWidth The box-adjusted width that was set
\r
327 * @param {Number} adjHeight The box-adjusted height that was set
\r
328 * @param {Number} rawWidth The width that was originally specified
\r
329 * @param {Number} rawHeight The height that was originally specified
\r
331 onResize : function(adjWidth, adjHeight, rawWidth, rawHeight){
\r
336 * Called after the component is moved, this method is empty by default but can be implemented by any
\r
337 * subclass that needs to perform custom logic after a move occurs.
\r
338 * @param {Number} x The new x position
\r
339 * @param {Number} y The new y position
\r
341 onPosition : function(x, y){
\r
346 adjustSize : function(w, h){
\r
347 if(this.autoWidth){
\r
350 if(this.autoHeight){
\r
353 return {width : w, height: h};
\r
357 adjustPosition : function(x, y){
\r
358 return {x : x, y: y};
\r
361 Ext.reg('box', Ext.BoxComponent);