Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Element.position.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-Element'>/**
19 </span> * @class Ext.Element
20  */
21 (function(){
22
23 var ELEMENT = Ext.Element,
24     LEFT = &quot;left&quot;,
25     RIGHT = &quot;right&quot;,
26     TOP = &quot;top&quot;,
27     BOTTOM = &quot;bottom&quot;,
28     POSITION = &quot;position&quot;,
29     STATIC = &quot;static&quot;,
30     RELATIVE = &quot;relative&quot;,
31     AUTO = &quot;auto&quot;,
32     ZINDEX = &quot;z-index&quot;;
33
34 Ext.override(Ext.Element, {
35 <span id='Ext-Element-method-getX'>    /**
36 </span>      * Gets the current X position of the element based on page coordinates.  Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
37       * @return {Number} The X position of the element
38       */
39     getX : function(){
40         return ELEMENT.getX(this.dom);
41     },
42
43 <span id='Ext-Element-method-getY'>    /**
44 </span>      * Gets the current Y position of the element based on page coordinates.  Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
45       * @return {Number} The Y position of the element
46       */
47     getY : function(){
48         return ELEMENT.getY(this.dom);
49     },
50
51 <span id='Ext-Element-method-getXY'>    /**
52 </span>      * Gets the current position of the element based on page coordinates.  Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
53       * @return {Number[]} The XY position of the element
54       */
55     getXY : function(){
56         return ELEMENT.getXY(this.dom);
57     },
58
59 <span id='Ext-Element-method-getOffsetsTo'>    /**
60 </span>      * Returns the offsets of this element from the passed element. Both element must be part of the DOM tree and not have display:none to have page coordinates.
61       * @param {String/HTMLElement/Ext.Element} element The element to get the offsets from.
62       * @return {Number[]} The XY page offsets (e.g. [100, -200])
63       */
64     getOffsetsTo : function(el){
65         var o = this.getXY(),
66             e = Ext.fly(el, '_internal').getXY();
67         return [o[0]-e[0],o[1]-e[1]];
68     },
69
70 <span id='Ext-Element-method-setX'>    /**
71 </span>     * Sets the X position of the element based on page coordinates.  Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
72      * @param {Number} The X position of the element
73      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
74      * @return {Ext.Element} this
75      */
76     setX : function(x, animate){
77         return this.setXY([x, this.getY()], animate);
78     },
79
80 <span id='Ext-Element-method-setY'>    /**
81 </span>     * Sets the Y position of the element based on page coordinates.  Element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
82      * @param {Number} The Y position of the element
83      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
84      * @return {Ext.Element} this
85      */
86     setY : function(y, animate){
87         return this.setXY([this.getX(), y], animate);
88     },
89
90 <span id='Ext-Element-method-setLeft'>    /**
91 </span>     * Sets the element's left position directly using CSS style (instead of {@link #setX}).
92      * @param {String} left The left CSS property value
93      * @return {Ext.Element} this
94      */
95     setLeft : function(left){
96         this.setStyle(LEFT, this.addUnits(left));
97         return this;
98     },
99
100 <span id='Ext-Element-method-setTop'>    /**
101 </span>     * Sets the element's top position directly using CSS style (instead of {@link #setY}).
102      * @param {String} top The top CSS property value
103      * @return {Ext.Element} this
104      */
105     setTop : function(top){
106         this.setStyle(TOP, this.addUnits(top));
107         return this;
108     },
109
110 <span id='Ext-Element-method-setRight'>    /**
111 </span>     * Sets the element's CSS right style.
112      * @param {String} right The right CSS property value
113      * @return {Ext.Element} this
114      */
115     setRight : function(right){
116         this.setStyle(RIGHT, this.addUnits(right));
117         return this;
118     },
119
120 <span id='Ext-Element-method-setBottom'>    /**
121 </span>     * Sets the element's CSS bottom style.
122      * @param {String} bottom The bottom CSS property value
123      * @return {Ext.Element} this
124      */
125     setBottom : function(bottom){
126         this.setStyle(BOTTOM, this.addUnits(bottom));
127         return this;
128     },
129
130 <span id='Ext-Element-method-setXY'>    /**
131 </span>     * Sets the position of the element in page coordinates, regardless of how the element is positioned.
132      * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
133      * @param {Number[]} pos Contains X &amp; Y [x, y] values for new position (coordinates are page-based)
134      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
135      * @return {Ext.Element} this
136      */
137     setXY: function(pos, animate) {
138         var me = this;
139         if (!animate || !me.anim) {
140             ELEMENT.setXY(me.dom, pos);
141         }
142         else {
143             if (!Ext.isObject(animate)) {
144                 animate = {};
145             }
146             me.animate(Ext.applyIf({ to: { x: pos[0], y: pos[1] } }, animate));
147         }
148         return me;
149     },
150
151 <span id='Ext-Element-method-setLocation'>    /**
152 </span>     * Sets the position of the element in page coordinates, regardless of how the element is positioned.
153      * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
154      * @param {Number} x X value for new position (coordinates are page-based)
155      * @param {Number} y Y value for new position (coordinates are page-based)
156      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
157      * @return {Ext.Element} this
158      */
159     setLocation : function(x, y, animate){
160         return this.setXY([x, y], animate);
161     },
162
163 <span id='Ext-Element-method-moveTo'>    /**
164 </span>     * Sets the position of the element in page coordinates, regardless of how the element is positioned.
165      * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
166      * @param {Number} x X value for new position (coordinates are page-based)
167      * @param {Number} y Y value for new position (coordinates are page-based)
168      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
169      * @return {Ext.Element} this
170      */
171     moveTo : function(x, y, animate){
172         return this.setXY([x, y], animate);
173     },
174
175 <span id='Ext-Element-method-getLeft'>    /**
176 </span>     * Gets the left X coordinate
177      * @param {Boolean} local True to get the local css position instead of page coordinate
178      * @return {Number}
179      */
180     getLeft : function(local){
181         return !local ? this.getX() : parseInt(this.getStyle(LEFT), 10) || 0;
182     },
183
184 <span id='Ext-Element-method-getRight'>    /**
185 </span>     * Gets the right X coordinate of the element (element X position + element width)
186      * @param {Boolean} local True to get the local css position instead of page coordinate
187      * @return {Number}
188      */
189     getRight : function(local){
190         var me = this;
191         return !local ? me.getX() + me.getWidth() : (me.getLeft(true) + me.getWidth()) || 0;
192     },
193
194 <span id='Ext-Element-method-getTop'>    /**
195 </span>     * Gets the top Y coordinate
196      * @param {Boolean} local True to get the local css position instead of page coordinate
197      * @return {Number}
198      */
199     getTop : function(local) {
200         return !local ? this.getY() : parseInt(this.getStyle(TOP), 10) || 0;
201     },
202
203 <span id='Ext-Element-method-getBottom'>    /**
204 </span>     * Gets the bottom Y coordinate of the element (element Y position + element height)
205      * @param {Boolean} local True to get the local css position instead of page coordinate
206      * @return {Number}
207      */
208     getBottom : function(local){
209         var me = this;
210         return !local ? me.getY() + me.getHeight() : (me.getTop(true) + me.getHeight()) || 0;
211     },
212
213 <span id='Ext-Element-method-position'>    /**
214 </span>    * Initializes positioning on this element. If a desired position is not passed, it will make the
215     * the element positioned relative IF it is not already positioned.
216     * @param {String} pos (optional) Positioning to use &quot;relative&quot;, &quot;absolute&quot; or &quot;fixed&quot;
217     * @param {Number} zIndex (optional) The zIndex to apply
218     * @param {Number} x (optional) Set the page X position
219     * @param {Number} y (optional) Set the page Y position
220     */
221     position : function(pos, zIndex, x, y) {
222         var me = this;
223
224         if (!pos &amp;&amp; me.isStyle(POSITION, STATIC)){
225             me.setStyle(POSITION, RELATIVE);
226         } else if(pos) {
227             me.setStyle(POSITION, pos);
228         }
229         if (zIndex){
230             me.setStyle(ZINDEX, zIndex);
231         }
232         if (x || y) {
233             me.setXY([x || false, y || false]);
234         }
235     },
236
237 <span id='Ext-Element-method-clearPositioning'>    /**
238 </span>    * Clear positioning back to the default when the document was loaded
239     * @param {String} value (optional) The value to use for the left,right,top,bottom, defaults to '' (empty string). You could use 'auto'.
240     * @return {Ext.Element} this
241      */
242     clearPositioning : function(value){
243         value = value || '';
244         this.setStyle({
245             left : value,
246             right : value,
247             top : value,
248             bottom : value,
249             &quot;z-index&quot; : &quot;&quot;,
250             position : STATIC
251         });
252         return this;
253     },
254
255 <span id='Ext-Element-method-getPositioning'>    /**
256 </span>    * Gets an object with all CSS positioning properties. Useful along with setPostioning to get
257     * snapshot before performing an update and then restoring the element.
258     * @return {Object}
259     */
260     getPositioning : function(){
261         var l = this.getStyle(LEFT);
262         var t = this.getStyle(TOP);
263         return {
264             &quot;position&quot; : this.getStyle(POSITION),
265             &quot;left&quot; : l,
266             &quot;right&quot; : l ? &quot;&quot; : this.getStyle(RIGHT),
267             &quot;top&quot; : t,
268             &quot;bottom&quot; : t ? &quot;&quot; : this.getStyle(BOTTOM),
269             &quot;z-index&quot; : this.getStyle(ZINDEX)
270         };
271     },
272
273 <span id='Ext-Element-method-setPositioning'>    /**
274 </span>    * Set positioning with an object returned by getPositioning().
275     * @param {Object} posCfg
276     * @return {Ext.Element} this
277      */
278     setPositioning : function(pc){
279         var me = this,
280             style = me.dom.style;
281
282         me.setStyle(pc);
283
284         if(pc.right == AUTO){
285             style.right = &quot;&quot;;
286         }
287         if(pc.bottom == AUTO){
288             style.bottom = &quot;&quot;;
289         }
290
291         return me;
292     },
293
294 <span id='Ext-Element-method-translatePoints'>    /**
295 </span>     * Translates the passed page coordinates into left/top css values for this element
296      * @param {Number/Number[]} x The page x or an array containing [x, y]
297      * @param {Number} y (optional) The page y, required if x is not an array
298      * @return {Object} An object with left and top properties. e.g. {left: (value), top: (value)}
299      */
300     translatePoints: function(x, y) {
301         if (Ext.isArray(x)) {
302              y = x[1];
303              x = x[0];
304         }
305         var me = this,
306             relative = me.isStyle(POSITION, RELATIVE),
307             o = me.getXY(),
308             left = parseInt(me.getStyle(LEFT), 10),
309             top = parseInt(me.getStyle(TOP), 10);
310
311         if (!Ext.isNumber(left)) {
312             left = relative ? 0 : me.dom.offsetLeft;
313         }
314         if (!Ext.isNumber(top)) {
315             top = relative ? 0 : me.dom.offsetTop;
316         }
317         left = (Ext.isNumber(x)) ? x - o[0] + left : undefined;
318         top = (Ext.isNumber(y)) ? y - o[1] + top : undefined;
319         return {
320             left: left,
321             top: top
322         };
323     },
324
325 <span id='Ext-Element-method-setBox'>    /**
326 </span>     * Sets the element's box. Use getBox() on another element to get a box obj. If animate is true then width, height, x and y will be animated concurrently.
327      * @param {Object} box The box to fill {x, y, width, height}
328      * @param {Boolean} adjust (optional) Whether to adjust for box-model issues automatically
329      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
330      * @return {Ext.Element} this
331      */
332     setBox: function(box, adjust, animate) {
333         var me = this,
334             w = box.width,
335             h = box.height;
336         if ((adjust &amp;&amp; !me.autoBoxAdjust) &amp;&amp; !me.isBorderBox()) {
337             w -= (me.getBorderWidth(&quot;lr&quot;) + me.getPadding(&quot;lr&quot;));
338             h -= (me.getBorderWidth(&quot;tb&quot;) + me.getPadding(&quot;tb&quot;));
339         }
340         me.setBounds(box.x, box.y, w, h, animate);
341         return me;
342     },
343
344 <span id='Ext-Element-method-getBox'>    /**
345 </span>     * Return an object defining the area of this Element which can be passed to {@link #setBox} to
346      * set another Element's size/location to match this element.
347      * @param {Boolean} contentBox (optional) If true a box for the content of the element is returned.
348      * @param {Boolean} local (optional) If true the element's left and top are returned instead of page x/y.
349      * @return {Object} box An object in the format&lt;pre&gt;&lt;code&gt;
350 {
351     x: &amp;lt;Element's X position&gt;,
352     y: &amp;lt;Element's Y position&gt;,
353     width: &amp;lt;Element's width&gt;,
354     height: &amp;lt;Element's height&gt;,
355     bottom: &amp;lt;Element's lower bound&gt;,
356     right: &amp;lt;Element's rightmost bound&gt;
357 }
358 &lt;/code&gt;&lt;/pre&gt;
359      * The returned object may also be addressed as an Array where index 0 contains the X position
360      * and index 1 contains the Y position. So the result may also be used for {@link #setXY}
361      */
362     getBox: function(contentBox, local) {
363         var me = this,
364             xy,
365             left,
366             top,
367             getBorderWidth = me.getBorderWidth,
368             getPadding = me.getPadding,
369             l, r, t, b, w, h, bx;
370         if (!local) {
371             xy = me.getXY();
372         } else {
373             left = parseInt(me.getStyle(&quot;left&quot;), 10) || 0;
374             top = parseInt(me.getStyle(&quot;top&quot;), 10) || 0;
375             xy = [left, top];
376         }
377         w = me.getWidth();
378         h = me.getHeight();
379         if (!contentBox) {
380             bx = {
381                 x: xy[0],
382                 y: xy[1],
383                 0: xy[0],
384                 1: xy[1],
385                 width: w,
386                 height: h
387             };
388         } else {
389             l = getBorderWidth.call(me, &quot;l&quot;) + getPadding.call(me, &quot;l&quot;);
390             r = getBorderWidth.call(me, &quot;r&quot;) + getPadding.call(me, &quot;r&quot;);
391             t = getBorderWidth.call(me, &quot;t&quot;) + getPadding.call(me, &quot;t&quot;);
392             b = getBorderWidth.call(me, &quot;b&quot;) + getPadding.call(me, &quot;b&quot;);
393             bx = {
394                 x: xy[0] + l,
395                 y: xy[1] + t,
396                 0: xy[0] + l,
397                 1: xy[1] + t,
398                 width: w - (l + r),
399                 height: h - (t + b)
400             };
401         }
402         bx.right = bx.x + bx.width;
403         bx.bottom = bx.y + bx.height;
404         return bx;
405     },
406
407 <span id='Ext-Element-method-move'>    /**
408 </span>     * Move this element relative to its current position.
409      * @param {String} direction Possible values are: &quot;l&quot; (or &quot;left&quot;), &quot;r&quot; (or &quot;right&quot;), &quot;t&quot; (or &quot;top&quot;, or &quot;up&quot;), &quot;b&quot; (or &quot;bottom&quot;, or &quot;down&quot;).
410      * @param {Number} distance How far to move the element in pixels
411      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
412      */
413     move: function(direction, distance, animate) {
414         var me = this,
415             xy = me.getXY(),
416             x = xy[0],
417             y = xy[1],
418             left = [x - distance, y],
419             right = [x + distance, y],
420             top = [x, y - distance],
421             bottom = [x, y + distance],
422             hash = {
423                 l: left,
424                 left: left,
425                 r: right,
426                 right: right,
427                 t: top,
428                 top: top,
429                 up: top,
430                 b: bottom,
431                 bottom: bottom,
432                 down: bottom
433             };
434
435         direction = direction.toLowerCase();
436         me.moveTo(hash[direction][0], hash[direction][1], animate);
437     },
438
439 <span id='Ext-Element-method-setLeftTop'>    /**
440 </span>     * Quick set left and top adding default units
441      * @param {String} left The left CSS property value
442      * @param {String} top The top CSS property value
443      * @return {Ext.Element} this
444      */
445     setLeftTop: function(left, top) {
446         var me = this,
447             style = me.dom.style;
448         style.left = me.addUnits(left);
449         style.top = me.addUnits(top);
450         return me;
451     },
452
453 <span id='Ext-Element-method-getRegion'>    /**
454 </span>     * Returns the region of this element.
455      * The element must be part of the DOM tree to have a region (display:none or elements not appended return false).
456      * @return {Ext.util.Region} A Region containing &quot;top, left, bottom, right&quot; member data.
457      */
458     getRegion: function() {
459         return this.getPageBox(true);
460     },
461
462 <span id='Ext-Element-method-getViewRegion'>    /**
463 </span>     * Returns the &lt;b&gt;content&lt;/b&gt; region of this element. That is the region within the borders and padding.
464      * @return {Ext.util.Region} A Region containing &quot;top, left, bottom, right&quot; member data.
465      */
466     getViewRegion: function() {
467         var me = this,
468             isBody = me.dom === document.body,
469             scroll, pos, top, left, width, height;
470
471         // For the body we want to do some special logic
472         if (isBody) {
473             scroll = me.getScroll();
474             left = scroll.left;
475             top = scroll.top;
476             width = Ext.Element.getViewportWidth();
477             height = Ext.Element.getViewportHeight();
478         }
479         else {
480             pos = me.getXY();
481             left = pos[0] + me.getBorderWidth('l') + me.getPadding('l');
482             top = pos[1] + me.getBorderWidth('t') + me.getPadding('t');
483             width = me.getWidth(true);
484             height = me.getHeight(true);
485         }
486
487         return Ext.create('Ext.util.Region', top, left + width, top + height, left);
488     },
489
490 <span id='Ext-Element-method-getPageBox'>    /**
491 </span>     * Return an object defining the area of this Element which can be passed to {@link #setBox} to
492      * set another Element's size/location to match this element.
493      * @param {Boolean} asRegion(optional) If true an Ext.util.Region will be returned
494      * @return {Object} box An object in the format&lt;pre&gt;&lt;code&gt;
495 {
496     x: &amp;lt;Element's X position&gt;,
497     y: &amp;lt;Element's Y position&gt;,
498     width: &amp;lt;Element's width&gt;,
499     height: &amp;lt;Element's height&gt;,
500     bottom: &amp;lt;Element's lower bound&gt;,
501     right: &amp;lt;Element's rightmost bound&gt;
502 }
503 &lt;/code&gt;&lt;/pre&gt;
504      * The returned object may also be addressed as an Array where index 0 contains the X position
505      * and index 1 contains the Y position. So the result may also be used for {@link #setXY}
506      */
507     getPageBox : function(getRegion) {
508         var me = this,
509             el = me.dom,
510             isDoc = el === document.body,
511             w = isDoc ? Ext.Element.getViewWidth()  : el.offsetWidth,
512             h = isDoc ? Ext.Element.getViewHeight() : el.offsetHeight,
513             xy = me.getXY(),
514             t = xy[1],
515             r = xy[0] + w,
516             b = xy[1] + h,
517             l = xy[0];
518
519         if (getRegion) {
520             return Ext.create('Ext.util.Region', t, r, b, l);
521         }
522         else {
523             return {
524                 left: l,
525                 top: t,
526                 width: w,
527                 height: h,
528                 right: r,
529                 bottom: b
530             };
531         }
532     },
533
534 <span id='Ext-Element-method-setBounds'>    /**
535 </span>     * Sets the element's position and size in one shot. If animation is true then width, height, x and y will be animated concurrently.
536      * @param {Number} x X value for new position (coordinates are page-based)
537      * @param {Number} y Y value for new position (coordinates are page-based)
538      * @param {Number/String} width The new width. This may be one of:&lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
539      * &lt;li&gt;A Number specifying the new width in this Element's {@link #defaultUnit}s (by default, pixels)&lt;/li&gt;
540      * &lt;li&gt;A String used to set the CSS width style. Animation may &lt;b&gt;not&lt;/b&gt; be used.
541      * &lt;/ul&gt;&lt;/div&gt;
542      * @param {Number/String} height The new height. This may be one of:&lt;div class=&quot;mdetail-params&quot;&gt;&lt;ul&gt;
543      * &lt;li&gt;A Number specifying the new height in this Element's {@link #defaultUnit}s (by default, pixels)&lt;/li&gt;
544      * &lt;li&gt;A String used to set the CSS height style. Animation may &lt;b&gt;not&lt;/b&gt; be used.&lt;/li&gt;
545      * &lt;/ul&gt;&lt;/div&gt;
546      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
547      * @return {Ext.Element} this
548      */
549     setBounds: function(x, y, width, height, animate) {
550         var me = this;
551         if (!animate || !me.anim) {
552             me.setSize(width, height);
553             me.setLocation(x, y);
554         } else {
555             if (!Ext.isObject(animate)) {
556                 animate = {};
557             }
558             me.animate(Ext.applyIf({
559                 to: {
560                     x: x,
561                     y: y,
562                     width: me.adjustWidth(width),
563                     height: me.adjustHeight(height)
564                 }
565             }, animate));
566         }
567         return me;
568     },
569
570 <span id='Ext-Element-method-setRegion'>    /**
571 </span>     * Sets the element's position and size the specified region. If animation is true then width, height, x and y will be animated concurrently.
572      * @param {Ext.util.Region} region The region to fill
573      * @param {Boolean/Object} animate (optional) true for the default animation or a standard Element animation config object
574      * @return {Ext.Element} this
575      */
576     setRegion: function(region, animate) {
577         return this.setBounds(region.left, region.top, region.right - region.left, region.bottom - region.top, animate);
578     }
579 });
580 })();
581 </pre>
582 </body>
583 </html>