3 <title>The source code</title>
4 <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
5 <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 <body onload="prettyPrint();">
8 <pre class="prettyprint lang-js">/*!
10 * Copyright(c) 2006-2009 Ext JS, LLC
12 * http://www.extjs.com/license
14 <div id="cls-Ext.BoxComponent"></div>/**
15 * @class Ext.BoxComponent
16 * @extends Ext.Component
17 * <p>Base class for any {@link Ext.Component Component} that is to be sized as a box, using width and height.</p>
18 * <p>BoxComponent provides automatic box model adjustments for sizing and positioning and will work correctly
19 * within the Component rendering model.</p>
20 * <p>A BoxComponent may be created as a custom Component which encapsulates any HTML element, either a pre-existing
21 * element, or one that is created to your specifications at render time. Usually, to participate in layouts,
22 * a Component will need to be a <b>Box</b>Component in order to have its width and height managed.</p>
23 * <p>To use a pre-existing element as a BoxComponent, configure it so that you preset the <b>el</b> property to the
24 * element to reference:<pre><code>
25 var pageHeader = new Ext.BoxComponent({
28 * This may then be {@link Ext.Container#add added} to a {@link Ext.Container Container} as a child item.</p>
29 * <p>To create a BoxComponent based around a HTML element to be created at render time, use the
30 * {@link Ext.Component#autoEl autoEl} config option which takes the form of a
31 * {@link Ext.DomHelper DomHelper} specification:<pre><code>
32 var myImage = new Ext.BoxComponent({
35 src: '/images/my-image.jpg'
39 * @param {Ext.Element/String/Object} config The configuration options.
42 Ext.BoxComponent = Ext.extend(Ext.Component, {
44 // tabTip config is used when a BoxComponent is a child of a TabPanel
45 <div id="cfg-Ext.BoxComponent-tabTip"></div>/**
46 * @cfg {String} tabTip
47 * <p><b>Note</b>: this config is only used when this BoxComponent is a child item of a TabPanel.</p>
48 * A string to be used as innerHTML (html tags are accepted) to show in a tooltip when mousing over
49 * the associated tab selector element. {@link Ext.QuickTips}.init()
50 * must be called in order for the tips to render.
52 // Configs below are used for all Components when rendered by BorderLayout.
53 <div id="cfg-Ext.BoxComponent-region"></div>/**
54 * @cfg {String} region <p><b>Note</b>: this config is only used when this BoxComponent is rendered
55 * by a Container which has been configured to use the <b>{@link Ext.layout.BorderLayout BorderLayout}</b>
56 * layout manager (e.g. specifying <tt>layout:'border'</tt>).</p><br>
57 * <p>See {@link Ext.layout.BorderLayout} also.</p>
59 // margins config is used when a BoxComponent is rendered by BorderLayout or BoxLayout.
60 <div id="cfg-Ext.BoxComponent-margins"></div>/**
61 * @cfg {Object} margins <p><b>Note</b>: this config is only used when this BoxComponent is rendered
62 * by a Container which has been configured to use the <b>{@link Ext.layout.BorderLayout BorderLayout}</b>
63 * or one of the two <b>{@link Ext.layout.BoxLayout BoxLayout} subclasses.</b></p>
64 * <p>An object containing margins to apply to this BoxComponent in the
65 * format:</p><pre><code>
68 right: (right margin),
69 bottom: (bottom margin),
72 * <p>May also be a string containing space-separated, numeric margin values. The order of the
73 * sides associated with each value matches the way CSS processes margin values:</p>
74 * <p><div class="mdetail-params"><ul>
75 * <li>If there is only one value, it applies to all sides.</li>
76 * <li>If there are two values, the top and bottom borders are set to the first value and the
77 * right and left are set to the second.</li>
78 * <li>If there are three values, the top is set to the first value, the left and right are set
79 * to the second, and the bottom is set to the third.</li>
80 * <li>If there are four values, they apply to the top, right, bottom, and left, respectively.</li>
82 * <p>Defaults to:</p><pre><code>
83 * {top:0, right:0, bottom:0, left:0}
86 <div id="cfg-Ext.BoxComponent-x"></div>/**
88 * The local x (left) coordinate for this component if contained within a positioning container.
90 <div id="cfg-Ext.BoxComponent-y"></div>/**
92 * The local y (top) coordinate for this component if contained within a positioning container.
94 <div id="cfg-Ext.BoxComponent-pageX"></div>/**
96 * The page level x coordinate for this component if contained within a positioning container.
98 <div id="cfg-Ext.BoxComponent-pageY"></div>/**
100 * The page level y coordinate for this component if contained within a positioning container.
102 <div id="cfg-Ext.BoxComponent-height"></div>/**
103 * @cfg {Number} height
104 * The height of this component in pixels (defaults to auto).
105 * <b>Note</b> to express this dimension as a percentage or offset see {@link Ext.Component#anchor}.
107 <div id="cfg-Ext.BoxComponent-width"></div>/**
108 * @cfg {Number} width
109 * The width of this component in pixels (defaults to auto).
110 * <b>Note</b> to express this dimension as a percentage or offset see {@link Ext.Component#anchor}.
112 <div id="cfg-Ext.BoxComponent-autoHeight"></div>/**
113 * @cfg {Boolean} autoHeight
114 * <p>True to use height:'auto', false to use fixed height (or allow it to be managed by its parent
115 * Container's {@link Ext.Container#layout layout manager}. Defaults to false.</p>
116 * <p><b>Note</b>: Although many components inherit this config option, not all will
117 * function as expected with a height of 'auto'. Setting autoHeight:true means that the
118 * browser will manage height based on the element's contents, and that Ext will not manage it at all.</p>
119 * <p>If the <i>browser</i> is managing the height, be aware that resizes performed by the browser in response
120 * to changes within the structure of the Component cannot be detected. Therefore changes to the height might
121 * result in elements needing to be synchronized with the new height. Example:</p><pre><code>
122 var w = new Ext.Window({
127 title: 'Collapse Me',
132 beforecollapse: function() {
135 beforeexpand: function() {
138 collapse: function() {
149 <div id="cfg-Ext.BoxComponent-autoWidth"></div>/**
150 * @cfg {Boolean} autoWidth
151 * <p>True to use width:'auto', false to use fixed width (or allow it to be managed by its parent
152 * Container's {@link Ext.Container#layout layout manager}. Defaults to false.</p>
153 * <p><b>Note</b>: Although many components inherit this config option, not all will
154 * function as expected with a width of 'auto'. Setting autoWidth:true means that the
155 * browser will manage width based on the element's contents, and that Ext will not manage it at all.</p>
156 * <p>If the <i>browser</i> is managing the width, be aware that resizes performed by the browser in response
157 * to changes within the structure of the Component cannot be detected. Therefore changes to the width might
158 * result in elements needing to be synchronized with the new width. For example, where the target element is:</p><pre><code>
159 <div id='grid-container' style='margin-left:25%;width:50%'></div>
161 * A Panel rendered into that target element must listen for browser window resize in order to relay its
162 * child items when the browser changes its width:<pre><code>
163 var myPanel = new Ext.Panel({
164 renderTo: 'grid-container',
165 monitorResize: true, // relay on browser resize
187 /* // private internal config
188 * {Boolean} deferHeight
189 * True to defer height calculations to an external component, false to allow this component to set its own
190 * height (defaults to false).
194 initComponent : function(){
195 Ext.BoxComponent.superclass.initComponent.call(this);
197 <div id="event-Ext.BoxComponent-resize"></div>/**
199 * Fires after the component is resized.
200 * @param {Ext.Component} this
201 * @param {Number} adjWidth The box-adjusted width that was set
202 * @param {Number} adjHeight The box-adjusted height that was set
203 * @param {Number} rawWidth The width that was originally specified
204 * @param {Number} rawHeight The height that was originally specified
207 <div id="event-Ext.BoxComponent-move"></div>/**
209 * Fires after the component is moved.
210 * @param {Ext.Component} this
211 * @param {Number} x The new x position
212 * @param {Number} y The new y position
218 // private, set in afterRender to signify that the component has been rendered
220 // private, used to defer height settings to subclasses
223 <div id="method-Ext.BoxComponent-setSize"></div>/**
224 * Sets the width and height of this BoxComponent. This method fires the {@link #resize} event. This method can accept
225 * either width and height as separate arguments, or you can pass a size object like <code>{width:10, height:20}</code>.
226 * @param {Mixed} width The new width to set. This may be one of:<div class="mdetail-params"><ul>
227 * <li>A Number specifying the new width in the {@link #getEl Element}'s {@link Ext.Element#defaultUnit}s (by default, pixels).</li>
228 * <li>A String used to set the CSS width style.</li>
229 * <li>A size object in the format <code>{width: widthValue, height: heightValue}</code>.</li>
230 * <li><code>undefined</code> to leave the width unchanged.</li>
232 * @param {Mixed} height The new height to set (not required if a size object is passed as the first arg).
233 * This may be one of:<div class="mdetail-params"><ul>
234 * <li>A Number specifying the new height in the {@link #getEl Element}'s {@link Ext.Element#defaultUnit}s (by default, pixels).</li>
235 * <li>A String used to set the CSS height style. Animation may <b>not</b> be used.</li>
236 * <li><code>undefined</code> to leave the height unchanged.</li>
238 * @return {Ext.BoxComponent} this
240 setSize : function(w, h){
241 // support for standard size objects
242 if(typeof w == 'object'){
253 // prevent recalcs when not needed
254 if(this.cacheSizes !== false && this.lastSize && this.lastSize.width == w && this.lastSize.height == h){
257 this.lastSize = {width: w, height: h};
258 var adj = this.adjustSize(w, h);
259 var aw = adj.width, ah = adj.height;
260 if(aw !== undefined || ah !== undefined){ // this code is nasty but performs better with floaters
261 var rz = this.getResizeEl();
262 if(!this.deferHeight && aw !== undefined && ah !== undefined){
264 }else if(!this.deferHeight && ah !== undefined){
266 }else if(aw !== undefined){
269 this.onResize(aw, ah, w, h);
270 this.fireEvent('resize', this, aw, ah, w, h);
275 <div id="method-Ext.BoxComponent-setWidth"></div>/**
276 * Sets the width of the component. This method fires the {@link #resize} event.
277 * @param {Number} width The new width to setThis may be one of:<div class="mdetail-params"><ul>
278 * <li>A Number specifying the new width in the {@link #getEl Element}'s {@link Ext.Element#defaultUnit}s (by default, pixels).</li>
279 * <li>A String used to set the CSS width style.</li>
281 * @return {Ext.BoxComponent} this
283 setWidth : function(width){
284 return this.setSize(width);
287 <div id="method-Ext.BoxComponent-setHeight"></div>/**
288 * Sets the height of the component. This method fires the {@link #resize} event.
289 * @param {Number} height The new height to set. This may be one of:<div class="mdetail-params"><ul>
290 * <li>A Number specifying the new height in the {@link #getEl Element}'s {@link Ext.Element#defaultUnit}s (by default, pixels).</li>
291 * <li>A String used to set the CSS height style.</li>
292 * <li><i>undefined</i> to leave the height unchanged.</li>
294 * @return {Ext.BoxComponent} this
296 setHeight : function(height){
297 return this.setSize(undefined, height);
300 <div id="method-Ext.BoxComponent-getSize"></div>/**
301 * Gets the current size of the component's underlying element.
302 * @return {Object} An object containing the element's size {width: (element width), height: (element height)}
304 getSize : function(){
305 return this.getResizeEl().getSize();
308 <div id="method-Ext.BoxComponent-getWidth"></div>/**
309 * Gets the current width of the component's underlying element.
312 getWidth : function(){
313 return this.getResizeEl().getWidth();
316 <div id="method-Ext.BoxComponent-getHeight"></div>/**
317 * Gets the current height of the component's underlying element.
320 getHeight : function(){
321 return this.getResizeEl().getHeight();
324 <div id="method-Ext.BoxComponent-getOuterSize"></div>/**
325 * Gets the current size of the component's underlying element, including space taken by its margins.
326 * @return {Object} An object containing the element's size {width: (element width + left/right margins), height: (element height + top/bottom margins)}
328 getOuterSize : function(){
329 var el = this.getResizeEl();
330 return {width: el.getWidth() + el.getMargins('lr'),
331 height: el.getHeight() + el.getMargins('tb')};
334 <div id="method-Ext.BoxComponent-getPosition"></div>/**
335 * Gets the current XY position of the component's underlying element.
336 * @param {Boolean} local (optional) If true the element's left and top are returned instead of page XY (defaults to false)
337 * @return {Array} The XY position of the element (e.g., [100, 200])
339 getPosition : function(local){
340 var el = this.getPositionEl();
342 return [el.getLeft(true), el.getTop(true)];
344 return this.xy || el.getXY();
347 <div id="method-Ext.BoxComponent-getBox"></div>/**
348 * Gets the current box measurements of the component's underlying element.
349 * @param {Boolean} local (optional) If true the element's left and top are returned instead of page XY (defaults to false)
350 * @return {Object} box An object in the format {x, y, width, height}
352 getBox : function(local){
353 var pos = this.getPosition(local);
354 var s = this.getSize();
360 <div id="method-Ext.BoxComponent-updateBox"></div>/**
361 * Sets the current box measurements of the component's underlying element.
362 * @param {Object} box An object in the format {x, y, width, height}
363 * @return {Ext.BoxComponent} this
365 updateBox : function(box){
366 this.setSize(box.width, box.height);
367 this.setPagePosition(box.x, box.y);
371 <div id="method-Ext.BoxComponent-getResizeEl"></div>/**
372 * <p>Returns the outermost Element of this Component which defines the Components overall size.</p>
373 * <p><i>Usually</i> this will return the same Element as <code>{@link #getEl}</code>,
374 * but in some cases, a Component may have some more wrapping Elements around its main
375 * active Element.</p>
376 * <p>An example is a ComboBox. It is encased in a <i>wrapping</i> Element which
377 * contains both the <code><input></code> Element (which is what would be returned
378 * by its <code>{@link #getEl}</code> method, <i>and</i> the trigger button Element.
379 * This Element is returned as the <code>resizeEl</code>.
381 getResizeEl : function(){
382 return this.resizeEl || this.el;
386 getPositionEl : function(){
387 return this.positionEl || this.el;
390 <div id="method-Ext.BoxComponent-setPosition"></div>/**
391 * Sets the left and top of the component. To set the page XY position instead, use {@link #setPagePosition}.
392 * This method fires the {@link #move} event.
393 * @param {Number} left The new left
394 * @param {Number} top The new top
395 * @return {Ext.BoxComponent} this
397 setPosition : function(x, y){
398 if(x && typeof x[1] == 'number'){
407 var adj = this.adjustPosition(x, y);
408 var ax = adj.x, ay = adj.y;
410 var el = this.getPositionEl();
411 if(ax !== undefined || ay !== undefined){
412 if(ax !== undefined && ay !== undefined){
413 el.setLeftTop(ax, ay);
414 }else if(ax !== undefined){
416 }else if(ay !== undefined){
419 this.onPosition(ax, ay);
420 this.fireEvent('move', this, ax, ay);
425 <div id="method-Ext.BoxComponent-setPagePosition"></div>/**
426 * Sets the page XY position of the component. To set the left and top instead, use {@link #setPosition}.
427 * This method fires the {@link #move} event.
428 * @param {Number} x The new x position
429 * @param {Number} y The new y position
430 * @return {Ext.BoxComponent} this
432 setPagePosition : function(x, y){
433 if(x && typeof x[1] == 'number'){
442 if(x === undefined || y === undefined){ // cannot translate undefined points
445 var p = this.getPositionEl().translatePoints(x, y);
446 this.setPosition(p.left, p.top);
451 afterRender : function(){
452 Ext.BoxComponent.superclass.afterRender.call(this);
454 this.resizeEl = Ext.get(this.resizeEl);
457 this.positionEl = Ext.get(this.positionEl);
459 this.boxReady = true;
460 this.setSize(this.width, this.height);
461 if(this.x || this.y){
462 this.setPosition(this.x, this.y);
463 }else if(this.pageX || this.pageY){
464 this.setPagePosition(this.pageX, this.pageY);
468 <div id="method-Ext.BoxComponent-syncSize"></div>/**
469 * Force the component's size to recalculate based on the underlying element's current height and width.
470 * @return {Ext.BoxComponent} this
472 syncSize : function(){
473 delete this.lastSize;
474 this.setSize(this.autoWidth ? undefined : this.getResizeEl().getWidth(), this.autoHeight ? undefined : this.getResizeEl().getHeight());
479 * Called after the component is resized, this method is empty by default but can be implemented by any
480 * subclass that needs to perform custom logic after a resize occurs.
481 * @param {Number} adjWidth The box-adjusted width that was set
482 * @param {Number} adjHeight The box-adjusted height that was set
483 * @param {Number} rawWidth The width that was originally specified
484 * @param {Number} rawHeight The height that was originally specified
486 onResize : function(adjWidth, adjHeight, rawWidth, rawHeight){
491 * Called after the component is moved, this method is empty by default but can be implemented by any
492 * subclass that needs to perform custom logic after a move occurs.
493 * @param {Number} x The new x position
494 * @param {Number} y The new y position
496 onPosition : function(x, y){
501 adjustSize : function(w, h){
508 return {width : w, height: h};
512 adjustPosition : function(x, y){
513 return {x : x, y: y};
516 Ext.reg('box', Ext.BoxComponent);
519 <div id="cls-Ext.Spacer"></div>/**
521 * @extends Ext.BoxComponent
522 * <p>Used to provide a sizable space in a layout.</p>
524 * @param {Object} config
526 Ext.Spacer = Ext.extend(Ext.BoxComponent, {
529 Ext.reg('spacer', Ext.Spacer);</pre>