3 * Copyright(c) 2006-2010 Ext JS, Inc.
5 * http://www.extjs.com/license
16 POSITION = "position",
18 RELATIVE = "relative",
22 Ext.Element.addMethods({
24 * 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).
25 * @return {Number} The X position of the element
28 return D.getX(this.dom);
32 * 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).
33 * @return {Number} The Y position of the element
36 return D.getY(this.dom);
40 * 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).
41 * @return {Array} The XY position of the element
44 return D.getXY(this.dom);
48 * 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.
49 * @param {Mixed} element The element to get the offsets from.
50 * @return {Array} The XY page offsets (e.g. [100, -200])
52 getOffsetsTo : function(el){
54 e = Ext.fly(el, '_internal').getXY();
55 return [o[0]-e[0],o[1]-e[1]];
59 * 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).
60 * @param {Number} The X position of the element
61 * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
62 * @return {Ext.Element} this
64 setX : function(x, animate){
65 return this.setXY([x, this.getY()], this.animTest(arguments, animate, 1));
69 * 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).
70 * @param {Number} The Y position of the element
71 * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
72 * @return {Ext.Element} this
74 setY : function(y, animate){
75 return this.setXY([this.getX(), y], this.animTest(arguments, animate, 1));
79 * Sets the element's left position directly using CSS style (instead of {@link #setX}).
80 * @param {String} left The left CSS property value
81 * @return {Ext.Element} this
83 setLeft : function(left){
84 this.setStyle(LEFT, this.addUnits(left));
89 * Sets the element's top position directly using CSS style (instead of {@link #setY}).
90 * @param {String} top The top CSS property value
91 * @return {Ext.Element} this
93 setTop : function(top){
94 this.setStyle(TOP, this.addUnits(top));
99 * Sets the element's CSS right style.
100 * @param {String} right The right CSS property value
101 * @return {Ext.Element} this
103 setRight : function(right){
104 this.setStyle(RIGHT, this.addUnits(right));
109 * Sets the element's CSS bottom style.
110 * @param {String} bottom The bottom CSS property value
111 * @return {Ext.Element} this
113 setBottom : function(bottom){
114 this.setStyle(BOTTOM, this.addUnits(bottom));
119 * Sets the position of the element in page coordinates, regardless of how the element is positioned.
120 * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
121 * @param {Array} pos Contains X & Y [x, y] values for new position (coordinates are page-based)
122 * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
123 * @return {Ext.Element} this
125 setXY : function(pos, animate){
127 if(!animate || !me.anim){
128 D.setXY(me.dom, pos);
130 me.anim({points: {to: pos}}, me.preanim(arguments, 1), 'motion');
136 * Sets the position of the element in page coordinates, regardless of how the element is positioned.
137 * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
138 * @param {Number} x X value for new position (coordinates are page-based)
139 * @param {Number} y Y value for new position (coordinates are page-based)
140 * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
141 * @return {Ext.Element} this
143 setLocation : function(x, y, animate){
144 return this.setXY([x, y], this.animTest(arguments, animate, 2));
148 * Sets the position of the element in page coordinates, regardless of how the element is positioned.
149 * The element must be part of the DOM tree to have page coordinates (display:none or elements not appended return false).
150 * @param {Number} x X value for new position (coordinates are page-based)
151 * @param {Number} y Y value for new position (coordinates are page-based)
152 * @param {Boolean/Object} animate (optional) True for the default animation, or a standard Element animation config object
153 * @return {Ext.Element} this
155 moveTo : function(x, y, animate){
156 return this.setXY([x, y], this.animTest(arguments, animate, 2));
160 * Gets the left X coordinate
161 * @param {Boolean} local True to get the local css position instead of page coordinate
164 getLeft : function(local){
165 return !local ? this.getX() : parseInt(this.getStyle(LEFT), 10) || 0;
169 * Gets the right X coordinate of the element (element X position + element width)
170 * @param {Boolean} local True to get the local css position instead of page coordinate
173 getRight : function(local){
175 return !local ? me.getX() + me.getWidth() : (me.getLeft(true) + me.getWidth()) || 0;
179 * Gets the top Y coordinate
180 * @param {Boolean} local True to get the local css position instead of page coordinate
183 getTop : function(local) {
184 return !local ? this.getY() : parseInt(this.getStyle(TOP), 10) || 0;
188 * Gets the bottom Y coordinate of the element (element Y position + element height)
189 * @param {Boolean} local True to get the local css position instead of page coordinate
192 getBottom : function(local){
194 return !local ? me.getY() + me.getHeight() : (me.getTop(true) + me.getHeight()) || 0;
198 * Initializes positioning on this element. If a desired position is not passed, it will make the
199 * the element positioned relative IF it is not already positioned.
200 * @param {String} pos (optional) Positioning to use "relative", "absolute" or "fixed"
201 * @param {Number} zIndex (optional) The zIndex to apply
202 * @param {Number} x (optional) Set the page X position
203 * @param {Number} y (optional) Set the page Y position
205 position : function(pos, zIndex, x, y){
208 if(!pos && me.isStyle(POSITION, STATIC)){
209 me.setStyle(POSITION, RELATIVE);
211 me.setStyle(POSITION, pos);
214 me.setStyle(ZINDEX, zIndex);
216 if(x || y) me.setXY([x || false, y || false]);
220 * Clear positioning back to the default when the document was loaded
221 * @param {String} value (optional) The value to use for the left,right,top,bottom, defaults to '' (empty string). You could use 'auto'.
222 * @return {Ext.Element} this
224 clearPositioning : function(value){
238 * Gets an object with all CSS positioning properties. Useful along with setPostioning to get
239 * snapshot before performing an update and then restoring the element.
242 getPositioning : function(){
243 var l = this.getStyle(LEFT);
244 var t = this.getStyle(TOP);
246 "position" : this.getStyle(POSITION),
248 "right" : l ? "" : this.getStyle(RIGHT),
250 "bottom" : t ? "" : this.getStyle(BOTTOM),
251 "z-index" : this.getStyle(ZINDEX)
256 * Set positioning with an object returned by getPositioning().
257 * @param {Object} posCfg
258 * @return {Ext.Element} this
260 setPositioning : function(pc){
262 style = me.dom.style;
266 if(pc.right == AUTO){
269 if(pc.bottom == AUTO){
277 * Translates the passed page coordinates into left/top css values for this element
278 * @param {Number/Array} x The page x or an array containing [x, y]
279 * @param {Number} y (optional) The page y, required if x is not an array
280 * @return {Object} An object with left and top properties. e.g. {left: (value), top: (value)}
282 translatePoints : function(x, y){
283 y = isNaN(x[1]) ? y : x[1];
284 x = isNaN(x[0]) ? x : x[0];
286 relative = me.isStyle(POSITION, RELATIVE),
288 l = parseInt(me.getStyle(LEFT), 10),
289 t = parseInt(me.getStyle(TOP), 10);
291 l = !isNaN(l) ? l : (relative ? 0 : me.dom.offsetLeft);
292 t = !isNaN(t) ? t : (relative ? 0 : me.dom.offsetTop);
294 return {left: (x - o[0] + l), top: (y - o[1] + t)};
297 animTest : function(args, animate, i) {
298 return !!animate && this.preanim ? this.preanim(args, i) : false;