Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / Element.position.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.1
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.com/license
14  */
15 /**
16  * @class Ext.Element
17  */
18 (function(){
19 var D = Ext.lib.Dom,
20         LEFT = "left",
21         RIGHT = "right",
22         TOP = "top",
23         BOTTOM = "bottom",
24         POSITION = "position",
25         STATIC = "static",
26         RELATIVE = "relative",
27         AUTO = "auto",
28         ZINDEX = "z-index";
29
30 Ext.Element.addMethods({
31         <div id="method-Ext.Element-getX"></div>/**
32       * 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).
33       * @return {Number} The X position of the element
34       */
35     getX : function(){
36         return D.getX(this.dom);
37     },
38
39     <div id="method-Ext.Element-getY"></div>/**
40       * 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).
41       * @return {Number} The Y position of the element
42       */
43     getY : function(){
44         return D.getY(this.dom);
45     },
46
47     <div id="method-Ext.Element-getXY"></div>/**
48       * 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).
49       * @return {Array} The XY position of the element
50       */
51     getXY : function(){
52         return D.getXY(this.dom);
53     },
54
55     <div id="method-Ext.Element-getOffsetsTo"></div>/**
56       * 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.
57       * @param {Mixed} element The element to get the offsets from.
58       * @return {Array} The XY page offsets (e.g. [100, -200])
59       */
60     getOffsetsTo : function(el){
61         var o = this.getXY(),
62                 e = Ext.fly(el, '_internal').getXY();
63         return [o[0]-e[0],o[1]-e[1]];
64     },
65
66     <div id="method-Ext.Element-setX"></div>/**
67      * 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).
68      * @param {Number} The X position of the element
69      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
70      * @return {Ext.Element} this
71      */
72     setX : function(x, animate){            
73             return this.setXY([x, this.getY()], this.animTest(arguments, animate, 1));
74     },
75
76     <div id="method-Ext.Element-setY"></div>/**
77      * 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).
78      * @param {Number} The Y position of the element
79      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
80      * @return {Ext.Element} this
81      */
82     setY : function(y, animate){            
83             return this.setXY([this.getX(), y], this.animTest(arguments, animate, 1));
84     },
85
86     <div id="method-Ext.Element-setLeft"></div>/**
87      * Sets the element's left position directly using CSS style (instead of {@link #setX}).
88      * @param {String} left The left CSS property value
89      * @return {Ext.Element} this
90      */
91     setLeft : function(left){
92         this.setStyle(LEFT, this.addUnits(left));
93         return this;
94     },
95
96     <div id="method-Ext.Element-setTop"></div>/**
97      * Sets the element's top position directly using CSS style (instead of {@link #setY}).
98      * @param {String} top The top CSS property value
99      * @return {Ext.Element} this
100      */
101     setTop : function(top){
102         this.setStyle(TOP, this.addUnits(top));
103         return this;
104     },
105
106     <div id="method-Ext.Element-setRight"></div>/**
107      * Sets the element's CSS right style.
108      * @param {String} right The right CSS property value
109      * @return {Ext.Element} this
110      */
111     setRight : function(right){
112         this.setStyle(RIGHT, this.addUnits(right));
113         return this;
114     },
115
116     <div id="method-Ext.Element-setBottom"></div>/**
117      * Sets the element's CSS bottom style.
118      * @param {String} bottom The bottom CSS property value
119      * @return {Ext.Element} this
120      */
121     setBottom : function(bottom){
122         this.setStyle(BOTTOM, this.addUnits(bottom));
123         return this;
124     },
125
126     <div id="method-Ext.Element-setXY"></div>/**
127      * Sets the position of the element in page coordinates, regardless of how the element is positioned.
128      * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
129      * @param {Array} pos Contains X & Y [x, y] values for new position (coordinates are page-based)
130      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
131      * @return {Ext.Element} this
132      */
133     setXY : function(pos, animate){
134             var me = this;
135         if(!animate || !me.anim){
136             D.setXY(me.dom, pos);
137         }else{
138             me.anim({points: {to: pos}}, me.preanim(arguments, 1), 'motion');
139         }
140         return me;
141     },
142
143     <div id="method-Ext.Element-setLocation"></div>/**
144      * Sets the position of the element in page coordinates, regardless of how the element is positioned.
145      * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
146      * @param {Number} x X value for new position (coordinates are page-based)
147      * @param {Number} y Y value for new position (coordinates are page-based)
148      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
149      * @return {Ext.Element} this
150      */
151     setLocation : function(x, y, animate){
152         return this.setXY([x, y], this.animTest(arguments, animate, 2));
153     },
154
155     <div id="method-Ext.Element-moveTo"></div>/**
156      * Sets the position of the element in page coordinates, regardless of how the element is positioned.
157      * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
158      * @param {Number} x X value for new position (coordinates are page-based)
159      * @param {Number} y Y value for new position (coordinates are page-based)
160      * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
161      * @return {Ext.Element} this
162      */
163     moveTo : function(x, y, animate){
164         return this.setXY([x, y], this.animTest(arguments, animate, 2));        
165     },    
166     
167     <div id="method-Ext.Element-getLeft"></div>/**
168      * Gets the left X coordinate
169      * @param {Boolean} local True to get the local css position instead of page coordinate
170      * @return {Number}
171      */
172     getLeft : function(local){
173             return !local ? this.getX() : parseInt(this.getStyle(LEFT), 10) || 0;
174     },
175
176     <div id="method-Ext.Element-getRight"></div>/**
177      * Gets the right X coordinate of the element (element X position + element width)
178      * @param {Boolean} local True to get the local css position instead of page coordinate
179      * @return {Number}
180      */
181     getRight : function(local){
182             var me = this;
183             return !local ? me.getX() + me.getWidth() : (me.getLeft(true) + me.getWidth()) || 0;
184     },
185
186     <div id="method-Ext.Element-getTop"></div>/**
187      * Gets the top Y coordinate
188      * @param {Boolean} local True to get the local css position instead of page coordinate
189      * @return {Number}
190      */
191     getTop : function(local) {
192             return !local ? this.getY() : parseInt(this.getStyle(TOP), 10) || 0;
193     },
194
195     <div id="method-Ext.Element-getBottom"></div>/**
196      * Gets the bottom Y coordinate of the element (element Y position + element height)
197      * @param {Boolean} local True to get the local css position instead of page coordinate
198      * @return {Number}
199      */
200     getBottom : function(local){
201             var me = this;
202             return !local ? me.getY() + me.getHeight() : (me.getTop(true) + me.getHeight()) || 0;
203     },
204
205     <div id="method-Ext.Element-position"></div>/**
206     * Initializes positioning on this element. If a desired position is not passed, it will make the
207     * the element positioned relative IF it is not already positioned.
208     * @param {String} pos (optional) Positioning to use "relative", "absolute" or "fixed"
209     * @param {Number} zIndex (optional) The zIndex to apply
210     * @param {Number} x (optional) Set the page X position
211     * @param {Number} y (optional) Set the page Y position
212     */
213     position : function(pos, zIndex, x, y){
214             var me = this;
215             
216         if(!pos && me.isStyle(POSITION, STATIC)){           
217             me.setStyle(POSITION, RELATIVE);           
218         } else if(pos) {
219             me.setStyle(POSITION, pos);
220         }
221         if(zIndex){
222             me.setStyle(ZINDEX, zIndex);
223         }
224         if(x || y) me.setXY([x || false, y || false]);
225     },
226
227     <div id="method-Ext.Element-clearPositioning"></div>/**
228     * Clear positioning back to the default when the document was loaded
229     * @param {String} value (optional) The value to use for the left,right,top,bottom, defaults to '' (empty string). You could use 'auto'.
230     * @return {Ext.Element} this
231      */
232     clearPositioning : function(value){
233         value = value || '';
234         this.setStyle({
235             left : value,
236             right : value,
237             top : value,
238             bottom : value,
239             "z-index" : "",
240             position : STATIC
241         });
242         return this;
243     },
244
245     <div id="method-Ext.Element-getPositioning"></div>/**
246     * Gets an object with all CSS positioning properties. Useful along with setPostioning to get
247     * snapshot before performing an update and then restoring the element.
248     * @return {Object}
249     */
250     getPositioning : function(){
251         var l = this.getStyle(LEFT);
252         var t = this.getStyle(TOP);
253         return {
254             "position" : this.getStyle(POSITION),
255             "left" : l,
256             "right" : l ? "" : this.getStyle(RIGHT),
257             "top" : t,
258             "bottom" : t ? "" : this.getStyle(BOTTOM),
259             "z-index" : this.getStyle(ZINDEX)
260         };
261     },
262     
263     <div id="method-Ext.Element-setPositioning"></div>/**
264     * Set positioning with an object returned by getPositioning().
265     * @param {Object} posCfg
266     * @return {Ext.Element} this
267      */
268     setPositioning : function(pc){
269             var me = this,
270                 style = me.dom.style;
271                 
272         me.setStyle(pc);
273         
274         if(pc.right == AUTO){
275             style.right = "";
276         }
277         if(pc.bottom == AUTO){
278             style.bottom = "";
279         }
280         
281         return me;
282     },    
283         
284     <div id="method-Ext.Element-translatePoints"></div>/**
285      * Translates the passed page coordinates into left/top css values for this element
286      * @param {Number/Array} x The page x or an array containing [x, y]
287      * @param {Number} y (optional) The page y, required if x is not an array
288      * @return {Object} An object with left and top properties. e.g. {left: (value), top: (value)}
289      */
290     translatePoints : function(x, y){                
291             y = isNaN(x[1]) ? y : x[1];
292         x = isNaN(x[0]) ? x : x[0];
293         var me = this,
294                 relative = me.isStyle(POSITION, RELATIVE),
295                 o = me.getXY(),
296                 l = parseInt(me.getStyle(LEFT), 10),
297                 t = parseInt(me.getStyle(TOP), 10);
298         
299         l = !isNaN(l) ? l : (relative ? 0 : me.dom.offsetLeft);
300         t = !isNaN(t) ? t : (relative ? 0 : me.dom.offsetTop);        
301
302         return {left: (x - o[0] + l), top: (y - o[1] + t)}; 
303     },
304     
305     animTest : function(args, animate, i) {
306         return !!animate && this.preanim ? this.preanim(args, i) : false;
307     }
308 });
309 })();</pre>    
310 </body>
311 </html>